如何使用表格存储的 API-问答-阿里云开发者社区-阿里云

开发者社区> 问答> 正文

如何使用表格存储的 API

云栖大讲堂 2017-10-25 13:32:13 2130
应用程序可以使用阿里云官方发布的表格存储 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'


  • 上述伪代码中使用到的函数的说明:
    函数说明
    HmacSha1Hmac-Sha1 加密算法。计算表格存储请求签名时,将 StringToSign 作为消息,AccessKeySecret 作为密钥。
    base64base64 编码算法。
    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='

存储 算法 JavaScript API 定位技术 开发工具 C# 开发者 数据格式
分享到
取消 提交回答
全部回答(0)
开发与运维
使用钉钉扫一扫加入圈子
+ 订阅

集结各类场景实战经验,助你开发运维畅行无忧

推荐文章
相似问题