如何使用表格存储的 API

应用程序可以使用阿里云官方发布的表格存储 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 由以下方式构成： 外网访问 URL：http://<instance>.<region>.ots.aliyuncs.com/<operation>
内网访问 URL：http://<instance>.<region>.ots-internal.aliyuncs.com/<operation>

参数说明如下：

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

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

1. [backcolor=transparent]http[backcolor=transparent]:[backcolor=transparent]//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：请求的签名。签名计算方式如下：Signature = base64(HmacSha1(AccessKeySecret, StringToSign));
•   StringToSign = CanonicalURI + '\n' + HTTPRequestMethod + '\n\n' + CanonicalHeaders
•   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： http://myInstance.cn-hangzhou.ots.aliyuncs.com/ListTable
• 
  
• 
  HTTPRequestMethod：HTTP 请求方法。如 GET、POST 或 PUT 等，表格存储的 HTTP API 只支持 POST 方法。

  
  [backcolor=transparent]注意：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：响应的签名。只有请求的签名被表格存储验证通过的条件下，响应才会包含签名。签名计算方式如下:Authorization = 'OTS ' + AccessKeyID + ':' + base64(HmacSha1(AccessKeySecret, stringToSign))
• StringToSign = CanonicalHeaders + CanonicalURI
• CanonicalHeaders = LowerCase (HeaderName1) + ':' + Trim(HeaderValue1) + '\n' + ... + LowerCase (HeaderNameN) + ':' + Trim(HeaderValueN) + '\n'
• 
  
  上述伪代码中使用到的函数的说明，与之前 HTTP Request Header 一节中所用到的函数相同。
• 
  CanonicalURI：HTTP URL 中的路径部分。如下面示例中，CanonicalURI 为 /ListTable：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 为 LTAIhGbDGGOYJDZt，AccessKeySecret 为 DomcqbBGOyYNWue3DlVArEUBeSlpE。 POST /ListTable HTTP/1.0
x-ots-date: 2017-09-21T08:32:07.000Z
x-ots-apiversion:2015-12-31
x-ots-accesskeyid: LTAIhGbDGGOYJDZt
x-ots-contentmd5: 1B2M2Y8AsgTpgAmY7PhCfg==
x-ots-instancename: first

那么用户请求的签名结果如下： 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'
signature = base64(HmacSha1('DomcqbBGOyYNWue3DlVArEUBeSlpE', stringToSign))
  = FjtBHd8FeB021PwTQI+XI/VMM24=


响应签名示例


假设用户的 AccessKeyID 为 LTAIhGbDGGOYJDZt，AccessKeySecret 为 DomcqbBGOyYNWue3DlVArEUBeSlpE。 /ListTable
x-ots-contentmd5: 1B2M2Y8AsgTpgAmY7PhCfg==
x-ots-requestid: 000559ae-ed86-f416-0d88-990a09ec9ed2
x-ots-contenttype: protocol buffer
x-ots-date:2017-09-21T08:32:07.815799Z

那么表格存储响应的签名结果如下： 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'
authorization = 'OTS ' + AccessKeyID +  ':' + base64(HmacSha1('DomcqbBGOyYNWue3DlVArEUBeSlpE', stringToSign))
  = 'OTS LTAIhGbDGGOYJDZt:LTktOlJYRenAGIpMn41zIab0ut0='