云数据库 TableStorage

    API调用方式

    API调用遵循HTTP协议,各Region采用不同的域名,具体域名为bts.{region}.baidubce.com。 数据交换格式为JSON,所有request/response body内容均采用UTF-8编码。

    注意:使用API接口前,请根据用户实际情况进入“实名认证”页面进行“企业认证”或者“个人认证”,详细的操作步骤请参见实名认证

    API认证机制

    所有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和同样的认证机制生成认证字符串,并与用户请求中包含的认证字符串进行比对。如果认证字符串相同,系统认为用户拥有指定的操作权限,并执行相关操作;如果认证字符串不同,系统将忽略该操作并返回错误码。

    鉴权认证机制的详细内容请参见鉴权认证机制

    请求参数

    请求参数包括如下4种:

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

    返回值说明

    返回值分为两种形式:

    返回内容 说明
    HTTP Status Code 如200,400,403,404等
    Response Body JSON格式组织的响应数据体

    版本

    直接定义在URL path中的首位,形如/v{version},如/v1

    资源层级

    层级 资源
    1 Instance
    2 Table
    3 Row

    功能映射

    Verb Path Description
    GET /v{version}/instances ListInstances,列出该账户下创建的所有实例
    GET /v{version}/instance/{instanceName} ShowInstance,显示该实例的详细信息
    GET /v{version}/instance/{instanceName}/tables ListTables,列出该实例下所有的Table
    GET /v{version}/instance/{instanceName}/table/{tableName} ShowTable,显示该Table的详细信息
    GET /v{version}/instance/{instanceName}/table/{tableName}/rows BatchGetRow/Scan,批量读取或范围扫描若干行数据
    GET /v{version}/instance/{instanceName}/table/{tableName}/row/{rowkey} GetRow,读取具体某一行数据
    PUT /v{version}/instance/{instanceName} CreateInstance,创建一个实例
    PUT /v{version}/instance/{instanceName}/table/{tableName} CreateTable/UpdateTable,在指定的Instance下创建一张表,或更新所指定的表
    PUT /v{version}/instance/{instanceName}/table/{tableName}/row/{rowkey} PutRow, 向指定的表中写入一行数据
    PUT /v{version}/instance/{instanceName}/table/{tableName}/rows BatchPutRow, 批量写入若干行数据
    DELETE /v{version}/instance/{instanceName} DropInstance,删除一个实例
    DELETE /v{version}/instance/{instanceName}/table/{tableName} DropTable,删除一张表
    DELETE /v{version}/instance/{instanceName}/table/{tableName}/row/{rowkey} DeleteRow, 删除某个表中指定的一行,可在body中指定要删除的属性列
    DELETE /v{version}/instance/{instanceName}/table/{tableName}/rows BatchDeleteRow, 批量删除若干行数据,可在body中指定要删除的属性列

    说明

    • URL路径中任意分隔符“/”支持任意数量连续,如/v1///instance等价于/v1/instance。
    • URL路径中结尾的“/”,可有可无,即/v1/instance/等价于/v1/instance。

    请求头域

    Header 必须 说明
    Authorization 认证相关bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}
    Host 固定bts.{region}.baidubce.com
    Content-Type 固定为application/json
    Content-Length 实际请求body大小
    x-bce-date 表示日期的字符串,如果用户使用了标准的Date域,该头域可以不填。当两者同时存在时,以x-bce-date为准。
    统一使用UTC时间,日期和时间之间加字母T,结尾加字母Z表示UTC时间,如:2014-06-01T23:00:10Z。
    服务端收到请求会判断本机时间与该时间差值,若大于30分钟,则抛弃本次请求,响应InvalidDate。
    Date 同x-bce-date头,二者必须存在其一
    x-bce-if-none-match 与ETag配合使用实现缓存,同HTTP标准If-None-Match语义
    x-bce-if-match 与ETag配合使用实现缓存,同HTTP标准If-Match语义

    响应头域

    Header 必须 说明
    Content-Type 固定application/json; charset=utf-8
    Content-Length 返回body大小
    ETag 与x-bce-if-match/x-bce-if-none-match配合使用实现缓存
    x-bce-request-id 对应请求的requestId,由服务端生成,反馈问题或提工单时需提供

    错误码

    HTTP状态码 错误码(Code) 描述
    200 - 请求处理成功
    201 - 资源创建成功
    202 - 请求被接受,具体任务异步处理
    204 - 请求成功处理,响应body为空json
    206 - 返回部分资源,用户需要继续请求,如scan请求
    304 - 命中ETag缓存
    400 InvalidURI HTTP URI不合法,比如传递的云数据库 TableStorage 不识别的资源
    400 InvalidHeader HTTP Request Header缺失字段或字段值不合法
    400 InvalidParam request body传递的参数值不合法
    400 MalformedJSON json格式非法,无法解析的json
    400 InappropriateJSON json格式合法,但是缺失必须参数
    401 AuthenticationFailed 认证失败
    403 AccessDenied 请求被拒绝
    403 ReachMaxInstanceCount 触发单账户可建立instance上限20个
    403 ReachMaxTableCount 触发单instance下可建立表数目128个
    403 InstanceCreating 实例创建中,请稍候
    403 AccountOverdue 账号欠费,请充值后访问
    404 ResourceNotFound 通用的资源未找到
    404 InstanceNotExist 实例不存在
    404 TableNotExist 表不存在
    404 RowNotExist 行不存在
    404 ColumnNotExist 列不存在
    405 MethodNotAllowed 不支持的HTTP方法
    408 RequestTimeout 请求从客户端发出到server端接收处理超过30分钟
    409 InstanceAlreadyExist 实例已经存在
    409 TableAlreadyExist 表已经存在
    413 PayloadTooLarge 请求实体过大
    500 InternalError server内部错误
    503 ServerBusy 服务过载

    错误信息格式

    当用户访问云数据库 TableStorage 出现错误时,会返回给用户相应的错误码和错误信息。 用户需要在访问异常时打印或记录返回的requestId和错误信息,便于用户定位问题,或者提工单。

    系统返回错误信息格式如下:

    {
        "code": "NoSuchKey",
        "message": "The resource you requested does not exist",
        "requestId": " 4db2b34d-654d-4d8a-b49b-3049ca786409"
    }
    一篇
    服务域名
    一篇
    临时授权访问