全部产品
存储与CDN 数据库 安全 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网
表格存储

使用表格存储的 API

更新时间:2017-11-14 16:25:48

应用程序可以使用阿里云官方发布的表格存储 SDK 来访问表格存储,也可以通过 POST 方法发送 HTTP 请求来访问表格存储。

以下将介绍 HTTP 请求结构和数据格式,以及如何构造 HTTP 请求和解析 HTTP 请求的返回结果。最后介绍表格存储请求返回的错误状态码。Java,Python,C++,Go,Node.JS和C# 语言的开发者可使用官方SDK。如果需要使用其他语言访问表格存储,可以根据本章内容使用 HTTP 消息与表格存储进行交互,也可以自行编写 SDK。

当前表格存储的 API 版本

API Version: 2015-12-31

HTTP 消息

表格存储接收应用程序的 HTTP 请求,执行相应的逻辑并以 HTTP 消息返回处理后的结果数据。HTTP 请求和响应中的数据通过 ProtocolBuffer 协议格式进行组织,关于 ProtocolBuffer 协议的更多内容,请参见表格存储 ProtocolBuffer 消息定义。下面分别介绍 HTTP 请求的 header 和 body, 以及响应的具体格式。

HTTP Request

HTTP Request URL

访问表格存储的 URL 由以下方式构成:

  1. 外网访问 URL:https://<instance>.<region>.ots.aliyuncs.com/<operation>
  2. 内网访问 URL:https://<instance>.<region>.ots-internal.aliyuncs.com/<operation>

参数说明如下:

参数 说明 大小写
instance 实例名称。实例由用户创建,可以在表格存储控制台查看云账户下拥有的实例信息。 不敏感
region 阿里云服务地域。表格存储服务会部署在多个地理位置不同的阿里云服务地域内。创建实例时需要指定阿里云地域,可以在表格存储控制台查看实例所在的地域名称。 不敏感
operation 表格存储操作名称。可以在 API 操作总览查看所有的表格存储操作名。 敏感

例如,华东 1 地域,实例名称为 myInstance 的 ListTable 请求的目标 URL,如下所示:

  1. https://myInstance.cn-hangzhou.ots.aliyuncs.com/ListTable

HTTP Request Header

表格存储规定 HTTP 请求的 Header 必须包含以下信息:

  • x-ots-date:请求发出时间。使用 UTC 时间,格式为 %Y-%m-%dT%H:%M:%S.000Z

  • x-ots-apiversion:API 的版本号。版本号是一个日期字符串,本文档对应的 API 版本号为 2015-12-31

  • x-ots-accesskeyid:用户unmarkTextString的 AccessKeyID。

  • x-ots-instancename:实例名称。

  • x-ots-contentmd5:对 HTTP body 中计算出的 MD5,使用 base64 进行编码。

  • x-ots-ststoken:如果使用了STS token,则需要指定该header,值为token。

  • User-Agent:用户代理,自定义标识符,建议格式:aliyun-tablestore-sdk-{语言}/版本(操作系统名称/操作系统版本/计算机类型;语言版本)

  • x-ots-signature:请求的签名。签名计算方式如下:

    1. Signature = base64(HmacSha1(AccessKeySecret, StringToSign));
    2. StringToSign = CanonicalURI + '\n' + HTTPRequestMethod + '\n\n' + CanonicalHeaders
    3. CanonicalHeaders = LowerCase (HeaderName1) + ':' + Trim(HeaderValue1) + '\n' + ... + LowerCase (HeaderNameN) + ':' + Trim(HeaderValueN) + '\n'

    上述伪代码中使用到的函数的说明:

    函数 说明
    HmacSha1 Hmac-Sha1 加密算法。计算表格存储请求签名时,将 StringToSign 作为消息,AccessKeySecret 作为密钥。
    base64 base64 编码算法。
    LowerCase 将字符串中的字母全部变成小写。
    Trim 去除字符串首尾处的空白字符。
  • CanonicalURI:HTTP URL 中的路径部分。如下面示例中,CanonicalURI 为 /ListTable

    1. https://myInstance.cn-hangzhou.ots.aliyuncs.com/ListTable
  • HTTPRequestMethod:HTTP 请求方法。如 GET、POST 或 PUT 等,表格存储的 HTTP API 只支持 POST 方法。

    注意:POST 需要大写。

  • CanonicalHeaders:CanonicalHeaders 是表格存储 HTTP header 按照以下规则构造的字符串(不包括 x-ots-signature 头):

    • 需要包含且只包含所有以x-ots-开头的表格存储标准头。

    • header 项名称全部小写,值必须经过 trim 去除空格。

    • header 项按照名字的字典序从小到大排序。

    • header 项的名称和值之间以:相隔。

    • 每个 header 之间以换行符相隔。

表格存储会对 HTTP 请求进行以下验证:

  • 验证 x-ots-contentmd5 头的值与 HTTP Body 中所含数据计算出的 MD5 是否一致。

  • 验证请求头中包含的签名是否正确。

  • 验证 x-ots-date 包含的时间与服务器时间相差小于 15 分钟。

若认证未通过,表格存储会直接返回身份认证错误。

HTTP Request Body

表格存储规定 HTTP 请求的 Body 部分是表格存储定义的 ProtocolBuffer 消息序列化之后的字符串,Body 长度不超过 2 MB。

关于表格存储请求的 ProtocolBuffer 消息定义,请参见 表格存储 ProtocolBuffer 消息定义

HTTP Response

HTTP Response Header

表格存储规定 HTTP 响应的 Header 包含以下信息:

  • x-ots-date:请求发出时间,使用 UTC 时间,格式为%Y-%m-%dT%H:%M:%S.000Z,比如当前北京时间是2017-09-21 16:05:52,那么这里的x-ots-date应该是2017-09-21T08:05:52.000Z。

  • x-ots-requestid:本次请求的请求 ID。

  • x-ots-contenttype:响应的内容类型。固定为protocol buffer的字符串。

  • x-ots-contentmd5:根据响应内容计算出的 MD5 值,使用 base64 编码。

  • Authorization:响应的签名。只有请求的签名被表格存储验证通过的条件下,响应才会包含签名。签名计算方式如下:

    1. Authorization = 'OTS ' + AccessKeyID + ':' + base64(HmacSha1(AccessKeySecret, stringToSign))
    2. StringToSign = CanonicalHeaders + CanonicalURI
    3. CanonicalHeaders = LowerCase (HeaderName1) + ':' + Trim(HeaderValue1) + '\n' + ... + LowerCase (HeaderNameN) + ':' + Trim(HeaderValueN) + '\n'

    上述伪代码中使用到的函数的说明,与之前 HTTP Request Header 一节中所用到的函数相同。

  • CanonicalURI:HTTP URL 中的路径部分。如下面示例中,CanonicalURI 为 /ListTable

    1. https://myInstance.cn-hangzhou.ots.aliyuncs.com/ListTable
  • CanonicalHeaders:CanonicalHeaders 是表格存储 HTTP header 按照以下规则构造的字符串(不包括 x-ots-signature 头):

    • 需要包含且只包含所有以x-ots-开头的表格存储标准头。

    • header 项名称全部小写,值必须经过 trim 去除空格。

    • header 项按照名字的字典序从小到大排序。

    • header 项的名称和值之间以:相隔。

    • 每个 header 之间以换行符相隔。

客户端应该对表格存储响应进行以下验证:

  • 验证响应头中包含的签名是否正确。

  • 验证 x-ots-date 包含的时间与客户端时间是否相差 15 分钟(正负 15 分钟)。

  • 验证 x-ots-contentmd5 头的值与响应数据计算出的 MD5 是否一致。

如验证不通过,用户应该在代码中拒绝这个响应所包含的数据,该响应有可能不是表格存储服务返回的。

HTTP Response Content

表格存储规定 HTTP 响应的内容是表格存储定义的 ProtocolBuffer 消息序列化之后的字符串,Body 长度不超过 2 MB。每一个表格存储请求消息对应一个表格存储响应消息,应用程序将响应内容反序列化之后,读取表格存储操作的结果。

签名示例

下面提供了两个请求和响应的签名验证示例,用户可以在实现签名算法后用下面的例子测试算法的实现是否正确。

请求签名示例

假设用户的 AccessKeyID 为 LTAIhGbDGGOYJDZt,AccessKeySecret 为 DomcqbBGOyYNWue3DlVArEUBeSlpE

  1. POST /ListTable HTTP/1.0
  2. x-ots-date: 2017-09-21T08:32:07.000Z
  3. x-ots-apiversion:2015-12-31
  4. x-ots-accesskeyid: LTAIhGbDGGOYJDZt
  5. x-ots-contentmd5: 1B2M2Y8AsgTpgAmY7PhCfg==
  6. x-ots-instancename: first

那么用户请求的签名结果如下:

  1. stringToSign = '/ListTable\nPOST\n\nx-ots-accesskeyid:LTAIhGbDGGOYJDZt\nx-ots-apiversion:2015-12-31\nx-ots-contentmd5:1B2M2Y8AsgTpgAmY7PhCfg==\nx-ots-date:2017-09-21T08:32:07.000Z\nx-ots-instancename:first\n'
  2. signature = base64(HmacSha1('DomcqbBGOyYNWue3DlVArEUBeSlpE', stringToSign))
  3. = FjtBHd8FeB021PwTQI+XI/VMM24=

响应签名示例

假设用户的 AccessKeyID 为 LTAIhGbDGGOYJDZt,AccessKeySecret 为 DomcqbBGOyYNWue3DlVArEUBeSlpE

  1. /ListTable
  2. x-ots-contentmd5: 1B2M2Y8AsgTpgAmY7PhCfg==
  3. x-ots-requestid: 000559ae-ed86-f416-0d88-990a09ec9ed2
  4. x-ots-contenttype: protocol buffer
  5. x-ots-date:2017-09-21T08:32:07.815799Z

那么表格存储响应的签名结果如下:

  1. stringToSign = 'x-ots-contentmd5:1B2M2Y8AsgTpgAmY7PhCfg==\nx-ots-contenttype:protocol buffer\nx-ots-date:2017-09-21T08:32:07.815799Z\nx-ots-requestid:000559ae-ed86-f416-0d88-990a09ec9ed2\n/ListTable'
  2. authorization = 'OTS ' + AccessKeyID + ':' + base64(HmacSha1('DomcqbBGOyYNWue3DlVArEUBeSlpE', stringToSign))
  3. = 'OTS LTAIhGbDGGOYJDZt:LTktOlJYRenAGIpMn41zIab0ut0='
本文导读目录