使用限制

在调用 API 之前，用户需要先在青云控制台申请 API 密钥。API 密钥由 API 密钥 ID access_key_id 和 API 密钥的私钥 secret_access_key 两部分组成。

  • access_key_id 将作为参数包含在每一个请求中发送。

  • secret_access_key 用于生成请求串的签名。因此，出于安全考虑，青云提醒用户，需妥善保管 secret_access_key，请勿外传。

API 请求说明

请求限制

  • 配额限制

    为了保证用户能合理地使用 API，青云对每位用户的 API 访问配额进行了限制。如，初始用户为 2000次/3600秒，未来会开放更高的配额。

  • 返回数据集长度限制

    当获取资源列表时，系统返回的最大数据长度是 100，即便你传了更大的 limit。因此，当您需要获取很多的数据时，请根据返回的 total_sum 进行分批获取。

请求类型

青云的 API 请求主要分为 延迟请求 和 实时请求 两种。

  • 延迟请求

    对于耗时请求，无法实时返回执行结果，例如 RunInstances 等。这些请求将以任务形式提交给青云的后台进行执行，并会在 API 请求的返回中返回任务 ID。

    这种情况下，用户可以通过查看资源状态来判断任务是否执行完成。例如，在提交 RunInstances 操作之后，用户可以通过 DescribeInstances 来查看 Instance 的状态以确认 Instance 是否创建成功。

  • 实时请求

    对于非耗时请求，青云会直接返回操作结果。

请求结构

完整的 API 请求应该包含四个部分，API 入口、公共参数、指令名称以及指令参数。各部分说明如下。

名称 描述 说明

API 入口

API 调用的 Webservice 入口

格式为 https://api.qingcloud.com/iaas/。

公共参数

每个 API 调用都需要包含公共参数

详情可见公共参数。

指令参数

指令参数请参见每个指令的说明文档。

例如 CeaseInstances，可查参考请求参数。

请求示例

这里以发送 DescribeInstances 请求为例，说明一个 API 请求的完整结构。

https://api.qingcloud.com/iaas/?access_key_id=QYACCESSKEYIDEXAMPLE&action=DescribeInstances&expires=2013-08-29T07%3A42%3A25Z&limit=20&signature_method=HmacSHA256&signature_version=1&status.1=running&time_stamp=2013-08-29T06%3A42%3A25Z&version=1&zone=pek3b&signature=ihPnXFgsg5yyqhDN2IejJ2%2Bbo89ABQ1UqFkyOdzRITY%3D

为了方便查看，我们将文档中的请求进行换行来显示。

https://api.qingcloud.com/iaas/?access_key_id=QYACCESSKEYIDEXAMPLE
&action=DescribeInstances
&expires=2013-08-29T07%3A42%3A25Z
&limit=20
&signature_method=HmacSHA256
&signature_version=1
&status.1=running
&time_stamp=2013-08-29T06%3A42%3A25Z
&version=1
&zone=pek3b
&signature=ihPnXFgsg5yyqhDN2IejJ2%2Bbo89ABQ1UqFkyOdzRITY%3D

API 响应说明

完整的 API 相应消息应该包含三个部分，指令名称、返回码以及返回参数。各部分说明如下。

响应结构

名称 描述 说明

action

API 返回的指令名称，例如 DescribeInstancesResponse 等。

API 返回的指令名称一般以 API 请求指令名称 + Response 来表示。

ret_code

返回码是用来表示 API 请求的返回值。

  • 当 ret_code 的值是 0 的时候，表示 API 请求正常。

  • 当 ret_code 的值不为 0 的时候表示 API 请求错误。

详情可见错误码。

返回参数

返回参数请参见每个指令的相关文档。

-

job_id

延迟请求 的返回结构中包含有任务 ID。

-

响应示例

API 的返回结果为 JSON 结构，这里以 DescribeInstances 请求返回为咧，说明一个 API 请求的返回消息的完整结构。

{
  "action":"DescribeInstancesResponse",
  "instance_set":[
    {
      "vcpus_current":1,
      "instance_id":"i-ogbndull",
      "vxnets":[
        {
          "vxnet_name":"primary vxnet",
          "vxnet_type":1,
          "vxnet_id":"vxnet-0",
          "nic_id":"52:54:ef:0c:ed:66",
          "private_ip":"10.50.13.54"
        }
      ],
      "memory_current":1024,
      "sub_code":0,
      "transition_status":"",
      "instance_name":"",
      "instance_type":"c1m1",
      "create_time":"2013-08-28T14:26:03Z",
      "status":"running",
      "status_time":"2013-08-28T14:26:03Z",
      "image":{
        "processor_type":"64bit",
        "platform":"linux",
        "image_size":20,
        "image_name":"CentOS 6.4 64bit",
        "image_id":"centos64x64",
        "os_family":"centos",
        "provider":"system"
      },
      "description":null
    }
  ],
  "ret_code":0,
  "total_count":1
}