如何使用腾讯云云硬盘API

介绍

腾讯云控制台允许您以类似于使用硬盘驱动器的方式管理腾讯云CVM的额外存储。只需点击腾讯云简化的GUI或图形用户界面，即可为我们的CVM添加云硬盘。但是，这不是一个在大型集群的实用方法，因此腾讯云提供了相关API。我们可以通过腾讯云官方命令行工具直接与API进行交互。

在本教程中，我们将学习如何使用云硬盘API创建，列出，附加，分离和删除云硬盘。

准备

硬盘准备：

通过API使用弹性云盘，您需要依次完成以下三个步骤：

1. 创建弹性云盘：您可以使用CreateDisks（创建弹性云盘）接口创建弹性云盘。
2. 将弹性云盘挂载到指定云主机上：创建完弹性云盘后，使用AttachDisks（挂载弹性云盘）接口将弹性云盘挂载到指定的云主机上。注意：这里的挂载指的是将弹性云盘分配给指定的云主机，相当于热插了一块硬盘到服务器上。
3. 登录云主机初始化弹性云盘：初次使用新创建的弹性云盘时，需要进行分区、格式化等一系列操作。具体操作方式请见：Windows系统数据盘分区及格式化、Linux系统分区、格式化、挂载及创建文件系统。注意，对于linux系统，分区并不是必要的，您可以跳过分区直接进行格式化操作。

接口准备：

服务地址

腾讯云 API 接口按照功能划分成了不同的功能模块，每个模块使用不同的域名访问。API 支持就近地域访问，也支持指定地域访问。例如云服务器的就近访问域名为 cvm.tencentcloudapi.com ，广州地域的域名为 cvm.ap-guangzhou.tencentcloudapi.com 。

目前支持的域名列表为：

支持 POST 和 GET 请求。 POST 请求目前仅支持 Content-Type 类型为 application/x-www-form-urlencoded 。

公共参数

公共参数是用于标识用户和接口鉴权目的的参数，如非必要，在每个接口单独的接口文档中不再对这些参数进行说明，但每次请求均需要携带这些参数，才能正常发起请求。

假设用户想要查询广州地域的云服务器实例列表，则其请求链接的形式可能如下:

https://cvm.tencentcloudapi.com/?Action=DescribeInstances
&SecretId=xxxxxxx
&Region=ap-guangzhou
&Timestamp=1402992826
&Nonce=345122
&Signature=xxxxxxxx
&Version=2017-03-12

地域列表

本产品所有接口 Region 字段的可选值如下表所示。如果接口不支持该表中的所有地域，则会在接口文档中单独说明。

接口鉴权

腾讯云 API 会对每个访问请求进行身份验证，即每个请求都需要在公共请求参数中包含签名信息（Signature）以验证请求者身份。 签名信息由安全凭证生成，安全凭证包括 SecretId 和 SecretKey；若用户还没有安全凭证，请前往云API密钥页面申请，否则无法调用云API接口。

生成签名串

有了安全凭证SecretId 和 SecretKey后，就可以生成签名串了。以下是生成签名串的详细过程：

假设用户的 SecretId 和 SecretKey 分别是：

SecretId: AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE SecretKey: Gu5t9xGARNpq86cd98joQYCN3EXAMPLE

注意：这里只是示例，请请根据用户实际申请的SecretId和SecretKey进行后续操作！

以云服务器查看实例列表(DescribeInstances)请求为例，当用户调用这一接口时，其请求参数可能如下:

对参数排序

首先对所有请求参数按参数名做字典序升序排列，所谓字典序升序排列，直观上就如同在字典中排列单词一样排序，按照字母表或数字表里递增顺序的排列次序，即先考虑第一个“字母”，在相同的情况下考虑第二个“字母”，依此类推。用户可以借助编程语言中的相关排序函数来实现这一功能，如php中的ksort函数。上述示例参数的排序结果如下:

{
    'Action' : 'DescribeInstances',
    'InstanceIds.0' : 'ins-09dx96dg',
    'Limit' : 20,
    'Nonce' : 11886,
    'Offset' : 0,
    'Region' : 'ap-guangzhou',
    'SecretId' : 'AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE',
    'Timestamp' : 1465185768,
    'Version': '2017-03-12',
}

使用其它程序设计语言开发时，可对上面示例中的参数进行排序，得到的结果一致即可。

拼接请求字符串

此步骤生成请求字符串。 将把上一步排序好的请求参数格式化成“参数名称”=“参数值”的形式，如对Action参数，其参数名称为"Action"，参数值为"DescribeInstances"，因此格式化后就为Action=DescribeInstances。 注意：“参数值”为原始值而非url编码后的值。

然后将格式化后的各个参数用"&"拼接在一起，最终生成的请求字符串为:

Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&Limit=20&Nonce=11886&Offset=0&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE&Timestamp=1465185768&Version=2017-03-12

拼接签名原文字符串

此步骤生成签名原文字符串。 签名原文字符串由以下几个参数构成:

1) 请求方法: 支持 POST 和 GET 方式，这里使用 GET 请求，注意方法为全大写。 2) 请求主机:查看实例列表(DescribeInstances)的请求域名为：cvm.tencentcloudapi.com。实际的请求域名根据接口所属模块的不同而不同，详见各接口说明。 3) 请求路径: 当前版本云API的请求路径固定为 / 。 4) 请求字符串: 即上一步生成的请求字符串。

签名原文串的拼接规则为:

请求方法 + 请求主机 +请求路径 + ? + 请求字符串

示例的拼接结果为：

GETcvm.tencentcloudapi.com/?Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&Limit=20&Nonce=11886&Offset=0&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE&Timestamp=1465185768&Version=2017-03-12

生成签名串

此步骤生成签名串。 首先使用 HMAC-SHA1 算法对上一步中获得的签名原文字符串进行签名，然后将生成的签名串使用 Base64 进行编码，即可获得最终的签名串。

具体代码如下，以 PHP 语言为例:

$secretKey = 'Gu5t9xGARNpq86cd98joQYCN3EXAMPLE';
$srcStr = 'GETcvm.tencentcloudapi.com/?Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&Limit=20&Nonce=11886&Offset=0&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE&Timestamp=1465185768&Version=2017-03-12';
$signStr = base64_encode(hash_hmac('sha1', $srcStr, $secretKey, true));
echo $signStr;

最终得到的签名串为:

EliP9YW3pW28FpsEdkXt/+WcGeI=

使用其它程序设计语言开发时，可用上面示例中的原文进行签名验证，得到的签名串与例子中的一致即可。

签名串编码

生成的签名串并不能直接作为请求参数，需要对其进行 URL 编码。 注意：如果用户的请求方法是GET，则对所有请求参数值均需要做URL编码。 如上一步生成的签名串为 EliP9YW3pW28FpsEdkXt/+WcGeI= ，最终得到的签名串请求参数(Signature)为： EliP9YW3pW28FpsEdkXt%2f%2bWcGeI%3d ，它将用于生成最终的请求URL。

签名演示

在实际调用 API 3.0 时，推荐使用配套的腾讯云 SDK 3.0 ，SDK 封装了签名的过程，开发时只关注产品提供的具体接口即可。详细信息参见 SDK 中心。当前支持的编程语言有：

• Python
• Java
• PHP
• Go
• JavaScript

创建云硬盘

要创建云硬盘，我们可以使用以下参数：

接口请求域名： cbs.tencentcloudapi.com

本接口（CreateDisks）用于创建云硬盘。

• 预付费云盘的购买会预先扣除本次云盘购买所需金额，在调用本接口前请确保账户余额充足。
• 本接口支持传入数据盘快照来创建云盘，实现将快照数据复制到新购云盘上。
• 本接口为异步接口，当创建请求下发成功后会返回一个新建的云盘ID列表，此时云盘的创建并未立即完成。可以通过调用DescribeDisks接口根据DiskId查询对应云盘，如果能查到云盘，且状态为'UNATTACHED'或'ATTACHED'，则表示创建成功。

输入示例

https://cbs.tencentcloudapi.com/?Action=CreateDisks
&DiskType=CLOUD_BASIC
&DiskCount=1
&DiskSize=50
&Placement.Zone=ap-guangzhou-2
&Placement.ProjectId=0
&DiskChargeType=PREPAID
&DiskChargePrepaid.Period=1
&DiskChargePrepaid.RenewFlag=NOTIFY_AND_AUTO_RENEW
&<公共请求参数>

输出示例

{
  "Response": {
    "DiskIdSet": [
      "disk-lzrg2pwi"
    ],
    "RequestId": "6a57da9a-2049-7182-2de3-5a1f8014ccfd"
  }
}

查询云硬盘列表

要查看现在挂在了那些硬盘，可以使用下面的命令：

接口请求域名： cbs.tencentcloudapi.com

本接口（DescribeDisks）用于查询云硬盘列表。

• 可以根据云硬盘ID、云硬盘类型或者云硬盘状态等信息来查询云硬盘的详细信息，不同条件之间为与(AND)的关系，过滤信息详细请见过滤器Filter。
• 如果参数为空，返回当前用户一定数量（Limit所指定的数量，默认为20）的云硬盘列表。

输入示例

https://cbs.tencentcloudapi.com/?Action=DescribeDisks
&Filters.0.Name=disk-usage
&Filters.0.Values.0=DATA_DISK
&Filters.1.Name=disk-state
&Filters.1.Values.0=ATTACHED
&<公共请求参数>

输出示例

{
  "Response": {
    "DiskSet": [
      {
        "Attached": true,
        "AutoRenewFlagError": false,
        "CreateTime": "2017-07-27 15:16:56",
        "DeadlineError": false,
        "DeadlineTime": "2017-10-27 15:17:05",
        "DifferDaysOfDeadline": -139,
        "DiskChargeType": "PREPAID",
        "DiskId": "disk-5w50lrms",
        "DiskName": "data1",
        "DiskSize": 10,
        "DiskState": "ATTACHED",
        "DiskType": "CLOUD_BASIC",
        "DiskUsage": "DATA_DISK",
        "Encrypt": false,
        "InstanceId": "ins-6p8zngem",
        "IsReturnable": false,
        "Placement": {
          "ProjectId": 10086,
          "Zone": "ap-guangzhou-2"
        },
        "Portable": true,
        "RenewFlag": "NOTIFY_AND_AUTO_RENEW",
        "ReturnFailCode": 2,
        "RollbackPercent": 0,
        "Rollbacking": false,
        "SnapshotAbility": true
      }
    ],
    "RequestId": "e63c7075-4b34-4825-9850-b19edb1eda89",
    "TotalCount": 1
  }
}

扩容云硬盘

有时您可能需要将云硬盘扩容到CVM，例如在调试需要大量日志的问题或创建某些时间限制数据的备份时。 在这些情况下，我们需要能够扩容一个块存储卷。

接口请求域名： cbs.tencentcloudapi.com

本接口（ResizeDisk）用于扩容云硬盘。

• 只支持扩容弹性云盘。云硬盘类型可以通过DescribeDisks接口查询，见输出参数中Portable字段解释。随云主机创建的云硬盘需通过ResizeInstanceDisks接口扩容。
• 本接口为异步接口，接口成功返回时，云盘并未立即扩容到指定大小，可通过接口DescribeDisks来查询对应云盘的状态，如果云盘的状态为“EXPANDING”，表示正在扩容中，当状态变为“UNATTACHED”，表示扩容完成。

将云硬盘扩容到200G

输入示例

https://cbs.tencentcloudapi.com/?Action=ResizeDisk
&DiskId=disk-lzrg2pwi
&DiskSize=200
&<公共请求参数>

输出示例

{
  "Response": {
    "RequestId": "adefc06d-2cf1-29f6-24a6-5a1f81b5c0ac"
  }
}

解挂云硬盘

接口请求域名： cbs.tencentcloudapi.com

本接口（DetachDisks）用于解挂云硬盘。

• 支持批量操作，解挂挂载在同一主机上的多块云盘。如果多块云盘存在不允许解挂载的云盘，则操作不执行，以返回特定的错误码返回。
• 本接口为异步接口，当请求成功返回时，云盘并未立即从主机解挂载，可通过接口DescribeDisks来查询对应云盘的状态，如果云盘的状态由“ATTACHED”变为“UNATTACHED”，则为解挂载成功。

解挂单块云硬盘

输入示例

https://cbs.tencentcloudapi.com/?Action=DetachDisks
&DiskIds.0=disk-lzrg2pwi
&<公共请求参数>

输出示例

{
  "Response": {
    "RequestId": "aafa71a0-ed62-0fac-3ebf-5a1f808d1085"
  }
}

退还云硬盘

当您不再需要某个云硬盘云硬盘卷时，可以将其退还，然后将其从您的帐户中删除。

接口请求域名： cbs.tencentcloudapi.com

本接口（TerminateDisks）用于退还云硬盘。

• 不再使用的云盘，可通过本接口主动退还。
• 本接口支持退还预付费云盘和按小时后付费云盘。按小时后付费云盘可直接退还，预付费云盘需符合退还规则。
• 支持批量操作，每次请求批量云硬盘的上限为50。如果批量云盘存在不允许操作的，请求会以特定错误码返回。

批量退还云硬盘

输入示例

https://cbs.tencentcloudapi.com/?Action=TerminateDisks
DiskIds.0=disk-lzrg2pwi
DiskIds.1=disk-g27hqeo2
&<公共请求参数>

输出示例

{
  "Response": {
    "RequestId": "52c965d2-5deb-459a-8b5a-b3b9a1376544"
  }
}

结论

在本教程中，我们学习了在CVM中如何使用腾讯云API添加，扩容，退还，列出和删除云硬盘。

如果您已经知道如何执行此操作，那么您可能还需要学习创建脚本并将这些脚本添加到您喜欢的自动化工具中，例如Jenkins或Drone。

参考文献：《腾讯云云硬盘API文档》