Skip to Content
API 摘要快速开始

快速开始

认识 API

我们的 API 采用指令式的风格，每个 API 请求包含一个指令（Action）、指令参数和认证信息（PublicKey、Signature）。

公共参数

公共参数是在操作所有 API 的时候，都必需给出的参数，通常会展示在 API 文档所有参数的最上方。

参数名类型描述信息必填
Actionstring对应的 API 指令名称，例如 DescribeUHostInstanceYes
PublicKeystring用户公钥，可从 控制台  获取Yes
Signaturestring根据公钥及 API 指令生成的用户签名，参见 签名算法Yes

通用参数

通用参数是大部分 API 都可能使用到的参数，具有一致的含义，是否需要给出，取决于具体 API 的定义。

参数名类型描述信息
Regionstring地域。 参见 地域和可用区列表
Zonestring可用区。参见 地域和可用区列表
ProjectIdstring项目ID。不填写为默认项目，子帐号必须填写。 参见 获取项目 ID

公共响应

公共响应是所有 API 都统一遵循的响应风格，包括一个指令响应名称（Action），识别 API 是否成功的状态码（RetCode）以及当遇到错误时，返回的错误提示信息（Message）。

字段名类型描述信息必填
RetCodeint返回状态码，为 0 则为成功返回，非 0 为失败Yes
Actionstring操作指令名称Yes
Messagestring返回错误消息，当 RetCode 非 0 时提供详细的描述信息No

错误码说明

RetCode描述
110API 响应超时（60秒）
130API 网关或者认证鉴权服务异常
150服务目前不可用，我们正在努力恢复中，请稍后重试
153API 请求被限流
160缺少关键参数 Action，请提供完整的参数
161Action 不存在
170缺少签名
171签名错误
172用户不存在
174Token 不存在
292项目不存在
293可用区权限错误
294访问 IP 被拒绝
295安全锁验证失败
299IAM 权限校验未通过

快速开始

准备工作

  1. 获取 API 访问地址
  2. 从 UAPI 控制台  获取 API 密钥，包括 PublicKey 和 PrivateKey
  3. 如果待操作资源属于某个地域下，获取地域和可用区列表
  4. 如果账号属于子账号，或需要操作某个特定项目，获取项目 ID

发起请求

您可以通过多种方式向 API 访问地址发起请求，包括 cURL 、Postman  等客户端。 我们的 API 支持 GET / POST 两种方法，支持 application/json 和 application/x-www-form-urlencoded 两种请求方式。

本文以 cURL POST JSON 为例，描述如何构造并发起一个 HTTP 请求。

数据假设

本例中假设

PublicKey  = 'someone@example.com1296235120854146120'
PrivateKey = '46f09bb9fab4f12dfc160dae12273d5332b5debe'

假设用户请求参数如下:

{
    "Action"     :  "DescribeUHostInstance",
    "Region"     :  "cn-bj2",
    "Limit"      :  10
}

计算签名

可参考 签名算法 文档，计算出的 Signature 为 4201919d267504385deb93af19e0197870fed36b 。

构造请求

将 PublicKey 和 Signature 填入请求参数中，构造出的请求最终为：

curl -X POST \
  https://api.tnqacloud.com \
  -H 'Content-Type: application/json' \
  -d '{
      "Action"     :  "DescribeUHostInstance",
      "Limit"      :  10,
      "PublicKey"  :  "someone@example.com1296235120854146120",
      "Region"     :  "cn-bj2",
      "Signature"  :  "4201919d267504385deb93af19e0197870fed36b"
  }'
索引签名算法