调用说明

通用约定

实名认证

百度智能云提供个人认证、企业认证两种认证方式,您可以选择任意一种方式进行认证。

认证机制

所有API的安全认证一律采用Access Key与请求签名机制。 Access Key由Access Key ID和Secret Access Key组成,均为字符串。 对于每个HTTP请求,使用下面所描述的算法生成一个认证字符串。提交认证字符串放在Authorization头域里。服务端根据生成算法验证认证字符串的正确性。 认证字符串的格式为bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}

  • version是正整数。
  • timestamp是生成签名时的UTC时间。
  • expirationPeriodInSeconds表示签名有效期限。
  • signedHeaders是签名算法中涉及到的头域列表。头域名之间用分号(;)分隔,如host;x-bce-date。列表按照字典序排列。(本API签名仅使用host和x-bce-date两个header)
  • signature是256位签名的十六进制表示,由64个小写字母组成。

当百度智能云接收到用户的请求后,系统将使用相同的SK和同样的认证机制生成认证字符串,并与用户请求中包含的认证字符串进行比对。如果认证字符串相同,系统认为用户拥有指定的操作权限,并执行相关操作;如果认证字符串不同,系统将忽略该操作并返回错误码。鉴权认证机制的详细内容请参见鉴权认证机制

通信协议

支持HTTP和HTTPS两种调用方式。为了提升数据的安全性,建议通过HTTPS调用。

请求结构说明

数据交换格式为JSON,所有request/response body内容均采用UTF-8编码。

请求参数包括如下4种:

参数类型 说明
URI 用于指明操作实体,如:PUT /v1/cluster/{clusterUuid}
Query参数 URL中携带的请求参数
HEADER 通过HTTP头域传入,如:x-bce-date
RequestBody 通过JSON格式组织的请求数据体

响应结构说明

响应值分为两种形式:

响应内容 说明
HTTP STATUS CODE 如200,400,403,404等
ResponseBody JSON格式组织的响应数据体

幂等性

当调用创建接口时如果遇到了请求超时或服务器内部错误,用户可能会尝试重发请求,这时用户通过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将长期有效。

日期与时间

日期与时间的表示有多种方式。为统一起见,除非是约定俗成或者有相应规范的,凡是HTTP标准中规定的表示日期和时间字段用GMT,其他日期时间表示的地方一律采用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秒。

规范化字符串

通常一个字符串中可以包含任何Unicode字符。在编程中这种灵活性会带来不少困扰。因此引入“规范字符串”的概念。一个规范字符串只包含百分号编码字符以及URI(Uniform Resource Identifier)非保留字符(Unreserved Characters)。
RFC 3986规定URI非保留字符包括以下字符:字母(A-Z,a-z)、数字(0-9)、连字号(-)、点号(.)、下划线(_)、波浪线(~)。
将任意一个字符串转换为规范字符串的方式是:

  • 将字符串转换成UTF-8编码的字节流。
  • 保留所有URI非保留字符原样不变。
  • 对其余字节做一次RFC 3986中规定的百分号编码(Percent-Encoding),即一个%后面跟着两个表示该字节值的十六进制字母。字母一律采用大写形式。

示例:
原字符串:this is an example for 测试,
对应的规范字符串:this%20is%20an%20example%20for%20%E6%B5%8B%E8%AF%95

API服务域名

CRDB API的服务域名包括:

Region EndPoint Protocol
北京 crdb.bj.baidubce.com HTTP and HTTPS
广州 crdb.gz.baidubce.com HTTP and HTTPS
苏州 crdb.su.baidubce.com HTTP and HTTPS

公共参数

公共请求参数

通用请求参数是指每个接口都需要使用到的请求参数。

参数名 参数类型 是否必须 参数描述
Authorization String Yes 认证Access Key
If-Match String No
If-None-Match String No
x-bce-request-id String No 1)所有请求都应该唯一地对应一个ID,用于标识该请求。
2)requestId可用于问题定位、性能分析等等多个场景。所有的日志都应该带有requestId以便后续分析。
3)requestId使用UUID version 4,暂时由各服务自行生成,后续考虑统一由BFE生成
x-bce-date String No 请求时间,格式参考 时间与日期

公共返回参数

每次接口调用请求,无论成功失败,都包含x-bce-request-id HTTP头,调用成功系统同时会返回业务数据。对单一资源的查询请求会返回HTTP ETag头。

示例:

HTTP/1.1 200 OK
x-bce-request-id: 7869616F-7A68-6977-656E-406261696475
ETag: xxx-xxx-xx
Content-Type: application/json
{
    "instance":{n
        "instanceId"                : " rdsnk1h2iwrw1va ",
        "instanceName"              : "cockroach5100",
        "engine"                    : "cockroach",
        "engineVersion"             : "2.0",
        "characterSetName"          : "utf8",
        "endpoint"                  : {
            "port"    : 5100,
            "address" : " cockroach5100. rdsnk1h2iwrw1va.mysql.crdb.baidu.com"
        },
        "instanceClass"             : "db1.micro",
        "allocatedMemoryInMB"       : 256,
        "allocatedStorageInGB"      : 5,
        "usedStorageInMB"           : 1023,
        "instanceStatus"            : "creating",
        "lockMode"                  : "unlock",
        "eipStatus"                 : "available",
        "backupPolicy"              : {
            "preferredBackupDays"   : "0,1,2,4,5",
            "preferredBackupWindow" : "17:00:00Z-19:00:00Z"
        },
        "publiclyAccessible"        : true,
        "instanceCreateTime"        : "2014-06-01T12:00:00Z",
        "instanceExpireTime"        : "2014-07-01T12:00:00Z"
    }
}

返回结果

调用 API 服务后返回数据采用统一格式,返回的 HTTP 状态码为 2xx,代表调用成功;

返回 4xx 或 5xx 的 HTTP 状态码代表调用失败;

调用成功返回的数据格式为 JSON

调用成功

调用成功返回结果中包含具体的业务数据,示例如下:

{
    "instance": {
    }
}

调用失败

调用接口出错后,将不会返回结果数据。调用方可根据错误代码表来定位错误原因。 当调用出错时,HTTP 请求返回一个 4xx 或 5xx 的 HTTP 状态码,返回的消息体中是具体的错误代码及错误信息和requestId。

示例:

{
    "requestId": "7869616F-7A68-6977-656E-406261696475",
    "code": "invalidAction",
    "message": "The action or operation requested is invalid. Verify that the action is typed correctly."
}