全部产品
表格存储

使用表格存储的 API

更新时间:2017-06-07 13:26:11   分享:   

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

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

当前表格存储的 API 版本

API Version: 2014-08-08

HTTP 消息

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

HTTP Request

HTTP Request URL

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

  1. 外网访问 URL:http://<instance>.<region>.ots.aliyuncs.com/<operation>
  2. 内网访问 URL:http://<instance>.<region>.ots-internal.aliyuncs.com/<operation>
  • instance:实例名称。实例由用户创建,可以在表格存储控制台查看云账户下拥有的实例信息。大小写不敏感。

  • region:阿里云服务地域。表格存储服务会部署在多个地理位置不同的阿里云服务地域内。创建实例时需要制定阿里云地域,可以在表格存储控制台查看实例所在的阿里云服务地域名称。大小写不敏感。

  • operation:表格存储操作名称。可以在 API 操作总览一章查看所有的表格存储操作名。大小写敏感。

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

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

HTTP Request Header

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

  • x-ots-date:请求发出时间。日期格式采用 rfc822 标准,并使用 UTC 时间,格式为“%a, %d %b %Y %H:%M:%S GMT”。

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

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

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

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

  • 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. http://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 消息定义,请参见 TableStore ProtocolBuffer 消息定义

HTTP Response

HTTP Response Header

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

  • x-ots-date:请求发出时间,日期格式采用 rfc822 标准,并使用 UTC 时间,格式为“%a, %d %b %Y %H:%M:%S GMT”。

  • 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'

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

    与上面请求中所用到的函数相同。

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

    1. http://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 为“29j2NtzlUr8hjP8b”,AccessKeySecret 为“8AKqXmNBkl85QK70cAOuH4bBd3gS0J”。

  1. POST /ListTable HTTP/1.0
  2. x-ots-date: Tue, 12 Aug 2014 10:23:03 GMT
  3. x-ots-apiversion:2014-08-08
  4. x-ots-accesskeyid: 29j2NtzlUr8hjP8b
  5. x-ots-contentmd5: 1B2M2Y8AsgTpgAmY7PhCfg==
  6. x-ots-instancename: naketest

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

  1. stringToSign = '/ListTable\nPOST\n\nx-ots-accesskeyid:29j2NtzlUr8hjP8b\nx-ots-apiversion:2014-08-08\nx-ots-contentmd5:1B2M2Y8AsgTpgAmY7PhCfg==\nx-ots-date:Tue, 12 Aug 2014 10:23:03 GMT\nx-ots-instancename:naketest\n'
  2. signature = base64(HmacSha1('8AKqXmNBkl85QK70cAOuH4bBd3gS0J', stringToSign))
  3. = '4xap392B7EBpN+RmlHgNowjoG1w='

响应签名示例

假设用户的 AccessKeyID 为“29j2NtzlUr8hjP8b”,AccessKeySecret 为“AKqXmNBkl85QK70cAOuH4bBd3gS0J”。

  1. /ListTable
  2. x-ots-contentmd5: 1B2M2Y8AsgTpgAmY7PhCfg==
  3. x-ots-requestid: 0005006c-0e81-db74-4a34-ce0a5df229a1
  4. x-ots-contenttype: protocol buffer
  5. x-ots-date:Tue, 12 Aug 2014 10:23:03 GMT

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

  1. stringToSign = 'x-ots-contentmd5:1B2M2Y8AsgTpgAmY7PhCfg==\nx-ots-contenttype:protocol buffer\nx-ots-date:Tue, 12 Aug 2014 10:23:03 GMT\nx-ots-requestid:0005006c-0e81-db74-4a34-ce0a5df229a1\n/ListTable'
  2. authorization = 'OTS ' + AccessKeyID + ':' + base64(HmacSha1('8AKqXmNBkl85QK70cAOuH4bBd3gS0J', stringToSign))
  3. = 'OTS 29j2NtzlUr8hjP8b:Y24MHhVti5UhSCW5qsUSDvT9SOk='
本文导读目录
本文导读目录
以上内容是否对您有帮助?