通用说明
实名认证
使用VPC API 前需要进行实名认证,如您还未开通实名认证,请前往官网控制台安全认证下进行实名认证,参考实名认证操作。
未通过实名认证的用户提交API请求时,将返回下述错误码:
错误返回码 | 错误消息 | 状态码 | 说明 |
---|---|---|---|
QualifyNotPass | The User has not pass qualify. | 403 | 账号没有通过实名认证 |
API认证机制
用户可以通过两种方式与百度智能云进行交互,包括认证方式和匿名方式。对于认证方式,需要通过使用Access Key Id / Secret Access Key加密的方法来验证某个请求的发送者身份。Access Key Id(AK)用于标示用户,Secret Access Key(SK)是用户用于加密认证字符串和百度智能云用来验证认证字符串的密钥,其中SK必须保密,只有用户和百度智能云知道。
当百度智能云接收到用户的请求后,系统将使用相同的SK和同样的认证机制生成认证字符串,并与用户请求中包含的认证字符串进行比对。如果认证字符串相同,系统认为用户拥有指定的操作权限,并执行相关操作;如果认证字符串不同,系统将忽略该操作并返回错误码。鉴权认证机制的详细内容请参见鉴权认证机制。
密码加密传输规范定义
所有涉及密码的接口参数都需要加密,禁止明文传输。密码一律采用AES 128位加密算法进行加密,用SK的前16位作为密钥,加密后生成的二进制字节流需要转成十六进制,并以字符串的形式传到服务端。具体步骤如下:
- byte[] bCiphertext= AES(明文,SK)
- String strHex = HexStr(bCiphertext)
幂等性
当调用创建接口时如果遇到了请求超时或服务器内部错误,用户可能会尝试重发请求,这时用户通过clientToken参数避免创建出比预期要多的资源,即保证请求的幂等性。
幂等性基于clientToken,clientToken是一个长度不超过64位的ASCII字符串,通常放在query string里,如http://bcc.bj.baidubce.com/v1/instance?clientToken=be31b98c-5e41-4838-9830-9be700de5a20
。
如果用户使用同一个clientToken值调用创建接口,则服务端会返回相同的请求结果。因此用户在遇到错误进行重试的时候,可以通过提供相同的clientToken值,来确保只创建一个资源;如果用户提供了一个已经使用过的clientToken,但其他请求参数(包括queryString和requestBody)不同甚至url Path不同,则会返回IdempotentParameterMismatch的错误代码。
clientToken的有效期为24小时,以服务端最后一次收到该clientToken为准。也就是说,如果客户端不断发送同一个clientToken,那么该clientToken将长期有效。
排版约定
排版格式 | 含义 |
---|---|
< > | 变量 |
[ ] | 可选项 |
{ } | 必选项 |
| | 互斥关系 |
等宽字体Courier New | 屏幕输出 |
请求参数
数据交换格式为JSON,所有request/response body内容均采用UTF-8编码。
请求参数包括如下4种:
参数类型 | 说明 |
---|---|
URI | 通常用于指明操作实体,如:PUT /v1/vpc/{vpc} |
Query参数 | URL中携带的请求参数 |
HEADER | 通过HTTP头域传入,如:x-bce-date |
RequestBody | 通过JSON格式组织的请求数据体 |
返回值说明
返回值分为两种形式:
返回内容 | 说明 |
---|---|
HTTP STATUS CODE | 如200,400,403,404等 |
ResponseBody | JSON格式组织的响应数据体 |
API版本号
参数 | 类型 | 参数位置 | 描述 | 是否必须 |
---|---|---|---|---|
version | String | URL参数 | API版本号,当前 API 版本v1。 | 是 |