调用说明
请求结构
请求结构简介
1. API 服务域名
云原生数据库 GaiaDB API 的服务域名包括:
Region | EndPoint | Protocol |
---|---|---|
北京 | gaiadb.bj.baidubce.com | HTTP and HTTPS |
保定 | gaiadb.bd.baidubce.com | HTTP and HTTPS |
广州 | gaiadb.gz.baidubce.com | HTTP and HTTPS |
南京 | gaiadb.nj.baidubce.com | HTTP and HTTPS |
武汉 | gaiadb.fwh.baidubce.com | HTTP and HTTPS |
2. 通信协议
API 调用遵循 HTTP 协议,各 Region 采用不同的域名,具体域名为 gaiadb.{region}.baidubce.com。
3. 请求参数
百度智能云 API 的每个请求都需要指定两类参数:即公共请求参数以及接口请求参数。其中公共请求参数是每个接口都要用到的请求参数,而接口请求参数是各个接口所特有的,具体见各个接口的“请求参数”描述。
请求参数包括如下4种:
参数类型 | 参数说明 |
---|---|
URI | 通常用于指明操作实体,如:POST /v{version}/gaiadb/cluster/{clusterId} |
Query参数 | URL中携带的请求参数 |
HEADER | 通过HTTP头域传入,如:x-bce-date |
RequestBody | 通过JSON格式组织的请求数据体 |
4. API 版本号
参数 | 类型 | 参数位置 | 描述 | 是否必选 |
---|---|---|---|---|
version | string | URL参数 | API 版本号,当前API 版本为 v1 | 是 |
5. 字符编码
可解析内容,所有 request/response body 内容目前均使用 UTF-8 编码,后续会支持更多 encoding 类型。
公共头
公共请求头
参数名称 | 描述 |
---|---|
Authorization | 包含Access Key与请求签名。 |
Content-Type | application/json; charset=utf-8。 |
x-bce-date | 表示日期的字符串,符合 API 规范。 |
Host | 表示请求 API 的域名。 |
x-bce-content-sha256 | 表示内容部分的SHA256签名的十六进制字符串。 这里内容指HTTP Request Payload Body。 即 Content 部分在被 HTTP encode之前的原始数据。 |
HTTP协议的标准头域不再这里列出。公共头域将在每个云数据库 RDS API 中出现,是必需的头域,其中x-bce-content-sha256头域只出现在POST和PUT请求中。POST、PUT、DELETE等请求数据放在request body中。
公共响应头
参数名称 | 描述 |
---|---|
Content-Type | application/json; charset=utf-8。 |
x-bce-request-id | 云原生数据库 GaiaDB 后端生成,并自动设置到响应头域中。 |
接口特殊请求参数说明
接口请求参数与具体的接口有关,不同的接口支持的接口请求参数也不一样。
以查询集群列表为例,支持的接口请求参数如下:
参数名称 | 类型 | 是否必选 | 参数位置 | 描述 |
---|---|---|---|---|
version | string | 是 | URL参数 | API 版本号 |
marker | string | 否 | Query参数 | 批量获取列表的查询的起始位置,是一个由系统生成的字符串 |
maxKeys | string | 否 | Query参数 | 每页包含的最大数量,最大数量通常不超过100,缺省值为100 |
其中各字段说明如下:
字段 | 说明 |
---|---|
参数名称 | 该接口支持的请求参数名,用户可以在使用此接口时将其作为接口请求参数。 |
类型 | 此接口参数的数据类型。 |
是否必选 | 标志此参数是否是必选的,若为“是”;,则表明调用该接口必须传入此参数;若为“否”,表示可以不传入。 |
参数位置 | 此接口参数的所属位置。 |
描述 | 简要描述了此接口请求参数的内容。 |
最终请求形式
最终的请求由以下几部分组成:
- 请求域名: 如北京区域的域名为gaiadb.bj.baidubce.com。
- 请求路径: 各个接口请求路径不同,详见具体接口详情。
- 请求方式: 支持RESTful风格的请求方式,本接口文档中涉及POST,GET,PUT,DELETE四种方式。
- 请求头: 包括鉴权信息在内的各个公共请求头。详细参考公共头。
- 最终请求参数串: 包括接口路径参数(请求路径中问号后面的部分)和接口请求参数。
- 请求body体:根据接口规定的RequestBody参数结构组成的json结构体。
示例:
POST /v{version}/gaiadb/cluster?clientToken={clientToken} HTTP/1.1
HOST: gaiadb.bj.baidubce.com
Authorization: authorization string
{
"number": 1,
"instanceParam": {
"engineVersion": "8.0",
"subnetId": "sbn-cifq6ky2gx9v",
"allocatedStorageInGB": 5120,
"allocatedMemoryInMB": 8192,
"allocatedCpuInCore": 2,
"engine": "MySQL",
"vpcId": "vpc-grrb0xpy1xr7",
"instanceAmount": 2,
"proxyAmount": 2
},
"productType": "postpay"
}
返回结果
正确返回结果
云原生数据库 GaiaDB 的API 服务要求使用JSON格式的结构体来描述一个请求返回的具体内容。作为示例,以下是一个正确的返回结果格式:
HTTP/1.1 200 OK
x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
Date: Wed, 03 Dec 2014 06:42:19 GMT
Content-Type: application/json;charset=UTF-8
Server: BWS
{
"orderId": "97a868674a964aad8aba2dcb1dxxxxxx",
"clusterIds": [
"gaiadbxxxxxx"
]
}
错误返回结果
请求发生错误时通过respone body返回详细错误信息,遵循如下格式:
参数名 | 类型 | 说明 |
---|---|---|
code | string | 错误码 |
message | string | 错误描述 |
requestId | string | 本次请求的 requestId |
示例:
{
"requestId" : "ae2225f7-1c2e-427a-a1ad-5413b762957d",
"code" : "AccessDenied",
"message" : "Access denied."
}
云原生数据库 GaiaDB 错误返回码说明
错误码 | 错误描述 | HTTP状态码 | 中文解释 |
---|---|---|---|
ClusterNotExist | Cluster not exist. | 404 | 集群不存在 |
AccessDenied | Access denied. | 403 | 禁止操作 |
InvalidAction | Invalid Action. | 400 | 非法操作 |
InternalFailure | We encountered an internal error. Please try again. | 500 | 内部错误 |
ValidationError | Validation Error. | 400 | 校验失败 |
AlreadyMaxLimit | Already Max Limit. | 400 | 达到最大限额 |
MalformedJSON | The JSON you provided was not well-formed. | 400 | JSON格式错误 |
MissingDateHeader | Request must have a "date" or "x-bce-date" header. | 400 | Header中缺少"date" 或 "x-bce-date" |
MissingAuthToken | Request must have a "authorization" header. | 400 | Header中缺少"authorization" |
RequestExpired | Request has expired. | 400 | 请求中authorization过期 |
NotSupportOperation | You are not allowed to execute this operation | 409 | 您没有权限进行此操作。 |
InternalServerError | Internal Server Error. | 503 | 内部服务器错误。 |
ParamValidationFailed | Parameter validate error:{detail} | 403 | 参数校验失败。 |
DurationValidationError | Instance Duration Validate Error. | 403 | 预付费时长参数错误。 |
CpuCountValidationException | Instance Cpu Size Validate Error. | 403 | CPU参数错误。 |
签名认证
云原生数据库 GaiaDB API 会对每个访问的请求进行身份认证,以保障用户的安全。安全认证采用 Access Key 与请求签名机制。Access Key 由 Access Key ID 和 Secret Access Key 组成,均为字符串,由百度智能云官方颁发给用户。其中 Access Key ID 用于标识用户身份,Access Key Secret 是用于加密签名字符串和服务器端验证签名字符串的密钥,必须严格保密。
对于每个HTTP请求,用户需要使用下文所描述的方式生成一个签名字符串,并将认证字符串放在HTTP请求的Authorization头域里。
签名字符串格式
bce-auth-v{version}/{accessKeyId}/{timestamp}/{expireTime}/{signedHeaders}/{signature}
签名申请步骤
关于AK/SK的获取,请参看获取AK/SK
签名生成算法
有关签名生成算法的具体介绍,请参看鉴权认证机制。
其他说明
幂等性
当调用创建接口时如果遇到了请求超时或服务器内部错误,用户可能会尝试重发请求,这时用户通过 clientToken 参数避免创建出比预期要多的资源,即保证请求的幂等性。
幂等性基于 clientToken,clientToken 是一个长度不超过 64 位的 ASCII 字符串,通常放在 query string 里,如http://gaiadb.bj.baidubce.com/v1/gaiadb/cluster?clientToken=be31b98c-5e41-4838-9830-9be700de5a20
。
如果用户使用同一个 clientToken 值调用创建接口,则服务端会返回相同的请求结果。因此用户在遇到错误进行重试的时候,可以通过提供相同的 clientToken 值,来确保只创建一个资源;如果用户提供了一个已经使用过的 clientToken,但其他请求参数(包括 queryString 和 requestBody)不同甚至 url Path 不同,则会返回 IdempotentParameterMismatch 的错误代码。
clientToken 的有效期为 24 小时,以服务端最后一次收到该 clientToken 为准。也就是说,如果客户端不断发送同一个 clientToken,那么该 clientToken 将长期有效。
日期与时间规范
日期与时间的表示有多种方式。为统一起见,除非是约定俗成或者有相应规范的,凡需要日期时间表示的地方一律采用UTC时间,遵循ISO 8601,并做以下约束:
- 表示日期一律采用YYYY-MM-DD方式,例如2014-06-01表示2014年6月1日
- 表示时间一律采用hh:mm:ss方式,并在最后加一个大写字母Z表示UTC时间。例如23:00:10Z表示UTC时间23点0分10秒。
- 凡涉及日期和时间合并表示时,在两者中间加大写字母T,例如2014-06-01T23:00:10Z表示UTC时间2014年6月1日23点0分10秒。
排版约定
排版格式 | 含义 |
---|---|
< > | 变量 |
[ ] | 可选项 |
{ } | 必选项 |
| | 互斥关系 |
等宽字体 Courier New | 屏幕输出 |