修订记录
发布日期 | 修改说明 |
2019-01-01 | 第一次发布 |
说明
排版约定
排版格式 | 含义 |
< > | 变量 |
[ ] | 可选项 |
{ } | 必选项 |
| | 互斥关系 |
等宽字体Courier New | 屏幕输出 |
编码
若请求消息体中的参数支持中文，则中文字符必须为UTF-8编码。
时间与日期
日期与时间的表示有多种方式。为统一起见，除非是约定俗成或者有相应规范的，凡需要日期时间表示的地方一律采用UTC时间，遵循ISO 8601，并做以下约束：
- 表示日期一律采用YYYY-MM-DD方式，例如2016-06-01表示2016年6月1日
- 表示时间一律采用hh:mm:ss方式，并在最后加一个大写字母Z表示UTC时间。例如23:00:10Z表示UTC时间23点0分10秒。
- 凡涉及日期和时间合并表示时，在两者中间加大写字母T，例如2016-06-01T23:00:10Z表示UTC时间2016年6月1日23点0分10秒
发送请求
共有三种方式可以基于已构建好的请求消息发起请求，分别为：
- cURL
cURL是一个命令行工具，用来执行各种URL操作和信息传输。cURL充当的是HTTP客户端，可以发送HTTP请求给服务端，并接收响应消息。cURL适用于接口调试。关于cURL详细信息请参见https://curl.haxx.se/。 - 编码
通过编码调用接口，组装请求消息，并发送处理请求消息。 - REST客户端
Mozilla、Google都为REST提供了图形化的浏览器插件，发送处理请求消息。针对Firefox，请参见FirefoxREST Client；针对Chrome，请参见Postman。
API 规格
公共请求消息头
下表列出了所有 XXX API 所携带的公共头域。HTTP 协议的标准头域不再这里列出了。
消息头（Header） | 是否必须 | 说明 |
Content-Type | 可选 | application/json; charset=utf-8 |
公共响应消息头
下表列出了所有 XXX API的公共响应头域。HTTP协议的标准响应头域不再这里列出了。
消息头（Header） | 说明 |
Content-Type | 只支持JSON格式，application/json; charset=utf-8 |
错误返回格式
XXX 错误响应符合BCE规范，统一为如下格式。后续各接口不再单独列出。
参数名 | 类型 | 说明 |
code | string | 错误码 |
message | string | 错误描述 |
body | string | 本次请求的体 |
示例
{
"code" : "AccessDenied",
"message" : "Access denied.",
"body" : ""
}其中，code为错误码，所有错误码取值来源 XXX 公共错误码和 XXX 专有错误码。
公共错误码
错误码 | 错误描述 | HTTP 状态码 | 中文解释 | 英文解释 |
错误码
参考各接口错误码。
接口说明
接口简介
依次列出所有接口
类型 | 子类型 | 说明 |
接口调用流程
说明接口使用流程
XXXX
描述
对接口的描述
URI
POST /v1/{id}/user
Path 参数
参数 | 说明 |
query 参数
参数 | 是否必须 | 描述 |
请求消息头
除公共消息头外，无其它特殊消息头。
参数 | 说明 | 是否必须 | 示例 |
请求参数体
参数名称 | 类型 | 描述 | 是否必须 |
result | xxx | 对取值范围，约束，说明，示例的描述 | 是 |
注：类型部分，如果是一个对象，可以在用 xxx 字段数据结构 在下面表格说明
xxx 字段数据结构说明
参数 | 类型 | 描述 | 是否必选 |
返回消息头
除公共消息头，无其它特殊消息头。
或
参数 | 说明 | 是否必须 | 示例 |
返回参数
参数名称 | 类型 | 描述 |
subnets | List xxx | 子网列表 |
xxx 字段数据结构说明
参数 | 是否必选 | 参数说明 | 描述 |
错误码
HTTP 状态码 | 错误码 | 错误描述 | 中文解释 | 英文解释 | 建议措施 |
请求示例
URI
Header
Body应答示例
Status
Header
Body附录
通用请求返回值
- 正常
返回值 | 说明 |
200 | 请求成功。 |
202 | 任务提交成功，当前系统繁忙，下发的任务会延迟处理。 |
204 | 任务提交成功。 |
- 异常
返回值 | 说明 |
300 multiple choices | 被请求的资源存在多个可供选择的响应。 |
400 Bad Request | 服务器未能处理请求。 |
401 Unauthorized | 被请求的页面需要用户名和密码。 |
403 Forbidden | 对被请求页面的访问被禁止。 |
404 Not Found | 服务器无法找到被请求的页面。 |
405 Method Not Allowed | 请求中指定的方法不被允许。 |
406 Not Acceptable | 服务器生成的响应无法被客户端所接受。 |
407 Proxy Authentication Required | 用户必须首先使用代理服务器进行验证，这样请求才会被处理。 |
408 Request Timeout | 请求超出了服务器的等待时间。 |
409 Conflict | 由于冲突，请求无法被完成。 |
500 Internal Server Error | 请求未完成。服务异常。 |
501 Not Implemented | 请求未完成。服务器不支持所请求的功能。 |
502 Bad Gateway | 请求未完成。服务器从上游服务器收到一个无效的响应。 |
503 Service Unavailable | 请求未完成。系统暂时异常。 |
504 Gateway Timeout | 网关超时。 |
状态码 | 编码 | 状态说明 |
100 | Continue | 继续请求。这个临时响应用来通知客户端，它的部分请求已经被服务器接收，且仍未被拒绝。 |
101 | Switching Protocols | 切换协议。只能切换到更高级的协议。例如，切换到HTTP的新版本协议。 |
201 | Created | 创建类的请求完全成功。 |
202 | Accepted | 已经接受请求，但未处理完成。 |
203 | Non-Authoritative Information | 非授权信息，请求成功。 |
204 | NoContent | 请求完全成功，同时HTTP响应不包含响应体。在响应OPTIONS方法的HTTP请求时返回此状态码。 |
205 | Reset Content | 重置内容，服务器处理成功。 |
206 | Partial Content | 服务器成功处理了部分GET请求。 |
300 | Multiple Choices | 多种选择。请求的资源可包括多个位置，相应可返回一个资源特征与地址的列表用于用户终端（例如：浏览器）选择。 |
301 | Moved Permanently | 永久移动，请求的资源已被永久的移动到新的URI，返回信息会包括新的URI。 |
302 | Found | 资源被临时移动。 |
303 | See Other | 查看其它地址。使用GET和POST请求查看。 |
304 | Not Modified | 所请求的资源未修改，服务器返回此状态码时，不会返回任何资源。 |
305 | Use Proxy | 所请求的资源必须通过代理访问。 |
306 | Unused | 已经被废弃的HTTP状态码。 |
400 | BadRequest | 非法请求。建议直接修改该请求，不要重试该请求。 |
401 | Unauthorized | 在客户端提供认证信息后，返回该状态码，表明服务端指出客户端所提供的认证信息不正确或非法。 |
402 | Payment Required | 保留请求。 |
403 | Forbidden | 请求被拒绝访问。返回该状态码，表明请求能够到达服务端，且服务端能够理解用户请求，但是拒绝做更多的事情，因为该请求被设置为拒绝访问，建议直接修改该请求，不要重试该请求。 |
404 | NotFound | 所请求的资源不存在。建议直接修改该请求，不要重试该请求。 |
405 | MethodNotAllowed | 请求中带有该资源不支持的方法。建议直接修改该请求，不要重试该请求。 |
406 | Not Acceptable | 服务器无法根据客户端请求的内容特性完成请求。 |
407 | Proxy Authentication Required | 请求要求代理的身份认证，与401类似，但请求者应当使用代理进行授权。 |
408 | Request Time-out | 服务器等候请求时发生超时。客户端可以随时再次提交该请求而无需进行任何更改。 |
409 | Conflict | 服务器在完成请求时发生冲突。返回该状态码，表明客户端尝试创建的资源已经存在，或者由于冲突请求的更新操作不能被完成。 |
410 | Gone | 客户端请求的资源已经不存在。返回该状态码，表明请求的资源已被永久删除。 |
411 | Length Required | 服务器无法处理客户端发送的不带Content-Length的请求信息。 |
412 | Precondition Failed | 未满足前提条件，服务器未满足请求者在请求中设置的其中一个前提条件。 |
413 | Request Entity Too Large | 由于请求的实体过大，服务器无法处理，因此拒绝请求。为防止客户端的连续请求，服务器可能会关闭连接。如果只是服务器暂时无法处理，则会包含一个Retry-After的响应信息。 |
414 | Request-URI Too Large | 请求的URI过长（URI通常为网址），服务器无法处理。 |
415 | Unsupported Media Type | 服务器无法处理请求附带的媒体格式。 |
416 | Requested range not satisfiable | 客户端请求的范围无效。 |
417 | Expectation Failed | 服务器无法满足Expect的请求头信息。 |
422 | UnprocessableEntity | 请求格式正确，但是由于含有语义错误，无法响应。 |
429 | TooManyRequests | 表明请求超出了客户端访问频率的限制或者服务端接收到多于它能处理的请求。建议客户端读取相应的Retry-After首部，然后等待该首部指出的时间后再重试。 |
500 | InternalServerError | 表明服务端能被请求访问到，但是不能理解用户的请求。 |
501 | Not Implemented | 服务器不支持请求的功能，无法完成请求。 |
502 | Bad Gateway | 充当网关或代理的服务器，从远端服务器接收到了一个无效的请求。 |
503 | ServiceUnavailable | 被请求的服务无效。建议直接修改该请求，不要重试该请求。 |
504 | ServerTimeout | 请求在给定的时间内无法完成。客户端仅在为请求指定超时（Timeout）参数时会得到该响应。 |
505 | HTTP Version not supported | 服务器不支持请求的HTTP协议的版本，无法完成处理。 |
任务类接口
- 正常响应要素说明
名称 | 参数类型 | 说明 |
job_id | String | 提交任务成功后返回的任务ID，用户可以使用该ID对任务执行情况进行查询。如何根据job_id来查询Job的执行状态，请参考查询Job状态。 |
- 异常响应要素说明
名称 | 参数类型 | 说明 |
error | 字典数据结构 | 提交任务异常是返回的异常信息，详情请参见 error 数据结构说明。 |
error 数据结构说明
名称 | 参数类型 | 说明 |
message | String | 任务异常错误信息描述。 |
code | String | 任务异常错误信息编码。 |
- 响应样例
正常响应：
{
"job_id": "70a599e0-31e7-49b7-b260-868f441e862b",
}异常响应：
{
"error": {"message": "", "code": XXX}
}批量接口
- 正常响应要素说明
名称 | 参数类型 | 说明 |
response | 列表数据结构 | 提交请求成功后返回的响应列表，详情请参见下面response数据结构说明。 |
response数据结构说明
名称 | 参数类型 | 说明 |
id | String | 操作成功的虚拟机id |
- 异常响应要素说明
名称 | 参数类型 | 说明 |
error | 字典数据结构 | 批量请求异常时返回的整体异常信息，详情请参见 error 数据结构。 |
internalError | 列表数据结构 | 批量请求处理中，每一个单个请求的具体异常信息，详情请参见 internalError 数据结构说明。 |
error 数据结构说明
名称 | 参数类型 | 说明 |
message | String | 批量操作整体异常错误信息描述。 |
code | String | 批量操作整体异常错误信息编码。 |
internalError 数据结构说明
名称 | 参数类型 | 说明 |
id | String | 具体单个请求操作失败的虚拟机id |
error_message | String | 具体单个请求操作失败的错误信息描述。 |
error_code | String | 具体单个请求操作失败的错误信息编码。 |
- 响应样例
正常响应：
{
"response": [
{
"id": "616fb98f-46ca-475e-917e-2563e5a8cd19"
},
{
"id": "516fb98f-46ca-475e-917e-2563e5a8cd12"
}
]
}异常响应：
{
"error": {
"code": "Ecs.xxxx",
"message": "xxxxxxxxxxxxxxx"
},
"internalError": [
{
"id": "616fb98f-46ca-475e-917e-2563e5a8cd19",
"error_code": "ECS.XXXX",
"error_message": "xxxxxxxxxxxxxxx"
},
{
"id": "516fb98f-46ca-475e-917e-2563e5a8cd12",
"error_code": "ECS.XXXX",
"error_message": "xxxxxxxxxxxxxxx"
}
]
}
