所有文档

          云数据库 RDS

          调用说明

          请求结构

          请求结构简介

          1. API 服务域名

          云数据库 RDS API 的服务域名包括:

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

          2. 通信协议

          API 调用遵循 HTTP 协议,各 Region 采用不同的域名,具体域名为 rds.{region}.baidubce.com。

          3. 请求参数

          百度智能云 API 的每个请求都需要指定两类参数:即公共请求参数以及接口请求参数。其中公共请求参数是每个接口都要用到的请求参数,而接口请求参数是各个接口所特有的,具体见各个接口的“请求参数”描述。

          请求参数包括如下4种:

          参数类型 参数说明
          URI 通常用于指明操作实体,如:POST /v{version}/instance/{instanceId}
          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 云数据库 RDS 后端生成,并自动设置到响应头域中。

          接口特殊请求参数说明

          接口请求参数与具体的接口有关,不同的接口支持的接口请求参数也不一样。

          查询实例列表为例,支持的接口请求参数如下:

          参数名称 类型 是否必须 参数位置 描述
          version string URL参数 API 版本号
          marker string Query参数 批量获取列表的查询的起始位置,是一个由系统生成的字符串
          maxKeys string Query参数 每页包含的最大数量,最大数量通常不超过1000,缺省值为1000

          其中各字段说明如下:

          字段 说明
          参数名称 该接口支持的请求参数名,用户可以在使用此接口时将其作为接口请求参数。
          类型 此接口参数的数据类型。
          是否必须 标志此参数是否是必须的,若为“是”;,则表明调用该接口必须传入此参数;若为“否”,表示可以不传入。
          参数位置 此接口参数的所属位置。
          描述 简要描述了此接口请求参数的内容。

          最终请求形式

          最终的请求由以下几部分组成:

          1. 请求域名: 如北京区域的域名为rds.bj.baidubce.com。
          2. 请求路径: 各个接口请求路径不同,详见具体接口详情。
          3. 请求方式: 支持RESTful风格的请求方式,本接口文档中涉及POST,GET,PUT,DELETE四种方式。
          4. 请求头: 包括鉴权信息在内的各个公共请求头。详细参考公共头
          5. 最终请求参数串: 包括接口路径参数(请求路径中问号后面的部分)和接口请求参数。如创建只读实例的路径参数readReplica和接口请求参数clientToken={clientToken}。
          6. 请求body体:根据接口规定的RequestBody参数结构组成的json结构体。

          示例:

          POST /v1/instance/readReplica&clientToken={be31b98c-5e41-4838-9830-9be700de5a20} HTTP/1.1
          Host: rds.bj.baidubce.com
          Content-Type: application/json
          x-bce-content-sha256: fc2af5fb07f6acdf3981dfe4f02d23a3585e93f618b81876abee98ed268cf
          x-bce-date: 2018-02-06T08:33:37Z
          Authorization: bce-auth-v1/d2f57e2b0b1611e89c59c56590fe827b/2018-02-06T08:33:37Z/3600/host;x-bce-account;x-bce-client-ip;x-bce-date;x-bce-request-id;x-bce-security-token/fc2af5fb07f6704f118641f75ea4f02d23a3585e93f618b81876f5d210fb8be4
          
          {
              "billing":{
                 "paymentTiming":"Postpaid"
              },
              "sourceInstanceId": "rds-mudjimy0jbig",
              "cpuCount":1,
              "memoryCapacity":0.25,
              "volumeCapacity":5
          }

          返回结果

          正确返回结果

          云数据库 RDS 的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
          {
          	"instanceIds": [
          	"i-T1I3OtUO"
          	]
          }

          错误返回结果

          请求发生错误时通过respone body返回详细错误信息,遵循如下格式:

          参数名 类型 说明
          code string 错误码
          message string 错误描述
          requestId string 本次请求的 requestId

          示例:

          {
          	"requestId" : "ae2225f7-1c2e-427a-a1ad-5413b762957d",
          	"code"      : "AccessDenied",
          	"message"   : "Access denied."
          }

          云数据库 RDS 错误返回码说明

          错误码 错误描述 HTTP状态码 中文解释
          InstanceNotExist Instance not exist. 403 实例不存在
          AccessDenied Access denied. 403 禁止操作
          InvalidAction Invalid Action. 400 非法操作
          InternalFailure We encountered an internal error. Please try again. 400 内部错误
          ValidationError Validation Error. 400 校验失败
          AlreadyMaxLimit Already Max Limit. 400 达到最大限额
          DbinstanceStateChange Operation not allowed. 400 云数据库 RDS 实例状态错误
          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过期
          InstanceTypeError The instance do not allow to do! 400 实例类型错误
          ReadReplicaMaxLimit Read replica number larger than 5. 400 只读实例不能超过5个
          MasterInstanceValidationError Master instance engine version validate error. 403 版本校验错误。
          ResourceInTask You have other order(s) need to payed first. 409 此实例存在未付费或正在执行中的订单
          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参数错误。

          签名认证

          云数据库 RDS 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

          签名生成算法

          有关签名生成算法的具体介绍,请参看鉴权认证机制

          其他说明

          密码加密传输规范定义

          所有涉及密码的接口参数都需要加密,禁止明文传输。密码一律采用AES-128-ECB加密算法进行加密,用SK的前16位作为密钥,用PKCS5Padding算法进行长度补全。此外,加密后生成的二进制字节流需要转成十六进制,并以字符串的形式传到服务端。

          加密过程可参考以下代码,以Python为例,进行说明:

          # -*- coding: utf-8 -*-
          
          from Crypto.Cipher import AES
          from binascii import b2a_hex, a2b_hex
          """
          若引入包Cipher后提示不存在该包,则安装pycryptodome包
          """
          
          def encrypt(secretkey, password):
              """Encrypt adminpass by AES-128-ECB/PKCS5Padding, the key is secretkey."""
              pendding = 16 - len(password) % 16
              password += chr(pendding) * (pendding)
              return b2a_hex(AES.new(secretkey[:16], AES.MODE_ECB).encrypt(password))
          
          def decrypt(secretkey, password):
              """Decrypt adminpass by AES-128-ECB/PKCS5Padding, the key is secretkey."""
              decrypted = AES.new(secretkey[:16], AES.MODE_ECB).decrypt(a2b_hex(password))
              pendding = ord(decrypted[len(decrypted) - 1])
              return decrypted[:-pendding]

          幂等性

          当调用创建接口时如果遇到了请求超时或服务器内部错误,用户可能会尝试重发请求,这时用户通过 clientToken 参数避免创建出比预期要多的资源,即保证请求的幂等性。

          幂等性基于 clientToken,clientToken 是一个长度不超过 64 位的 ASCII 字符串,通常放在 query string 里,如http://rds.bj.baidubce.com/v1/instance?clientToken=be31b98c-5e41-4838-9830-9be700de5a20

          如果用户使用同一个 clientToken 值调用创建接口,则服务端会返回相同的请求结果。因此用户在遇到错误进行重试的时候,可以通过提供相同的 clientToken 值,来确保只创建一个资源;如果用户提供了一个已经使用过的 clientToken,但其他请求参数(包括 queryString 和 requestBody)不同甚至 url Path 不同,则会返回 IdempotentParameterMismatch 的错误代码。

          clientToken 的有效期为 24 小时,以服务端最后一次收到该 clientToken 为准。也就是说,如果客户端不断发送同一个 clientToken,那么该 clientToken 将长期有效。

          日期与时间规范

          日期与时间的表示有多种方式。为统一起见,除非是约定俗成或者有相应规范的,凡需要日期时间表示的地方一律采用UTC时间,遵循ISO 8601,并做以下约束:

          1. 表示日期一律采用YYYY-MM-DD方式,例如2014-06-01表示2014年6月1日
          2. 表示时间一律采用hh:mm:ss方式,并在最后加一个大写字母Z表示UTC时间。例如23:00:10Z表示UTC时间23点0分10秒。
          3. 凡涉及日期和时间合并表示时,在两者中间加大写字母T,例如2014-06-01T23:00:10Z表示UTC时间2014年6月1日23点0分10秒。

          排版约定

          排版格式 含义
          < > 变量
          [ ] 可选项
          { } 必选项
          | 互斥关系
          等宽字体 Courier New 屏幕输出
          上一篇
          API概览
          下一篇
          SampleCode