阿里云DataHub客户端如何使用HTTP请求：常见问题解答和最佳实践

参考官方DataHub API规范：

https://help.aliyun.com/document_detail/99302.html?spm=a2c4g.11186623.6.549.74374f52zTkMPO

一. 接口规范

1.公共请求Header

名字	描述
x-datahub-client-version	API版本信息
x-datahub-security-token	Security Token，如果存在
Date	标准GMT时间，格式: EEE, dd MMM yyyy HH:mm:ss z
Authorization	签名信息
Content-Type	传输数据序列化协议

2. 公共返回Header

名字	描述
Content-Type	传输数据序列化协议
Content-Length	传输数据长度
x-datahub-request-id	全局唯一请求ID

3. 错误码

名字	描述	备注
InvalidParameter	参数错误
InvalidCursor	Cursor无效
NoSuchXXX	资源不存在
XXXAlreadyExist	资源已存在
Unauthorized	认证失败	AccessKey信息错误，用户时间戳不对等
NoPermission	鉴权失败	RAM权限错误
OperationDenied	禁止操作	操作禁止，比如删除有topic存在的project
LimitExceeded	流控受限	服务端QPS、流量等限制
InvalidShardOperation	Shard分裂或合并，变成Sealed
MalformedRecord	数据格式不正确
OffsetReseted	点位重置
OffsetSessionChanged	SubId被其他用户open占用
SubscriptionOffline	订阅下线
InternalServerError	系统内部错误
其他	其他非可重试异常，后续可能会被回收

4. 统一错误返回格式

名字	描述
ErrorCode	错误码
ErrorMessage	详细错误描述信息

错误响应示例：

5. 限制描述

名字	描述
ProjectName	长度：[3, 32]，仅包含字母、数字和’_’, 以字母开头，不区分大小写
TopicName	长度：[3, 128]，仅包含字母、数字和’_’, 以字母开头，不区分大小写

二、Authorization字段计算的方法

• AccessKey 表示签名所需的密钥。
• HTTPMethod 表示HTTP 请求的Method，主要有PUT、GET、POST、HEAD、DELETE等。
• \n 表示换行符。
• Content-Type 表示请求内容的类型，一般固定为“application/json”。
• Date 表示此次操作的时间，且必须为GMT格式，如“Sun, 22 Nov 2015 08:16:38 GMT”。
• CanonicalizedDataHubHeaders 表示以 x-datahub- 为前缀的HTTP Header的字典序排列。
• CanonicalizedResource 表示用户想要访问的DataHub资源的Url，若包含param，必须按字典序。

CanonicalizedDataHubHeaders构造方法

所有以 x-datahub- 为前缀的HTTP Header被称为 CanonicalizedDataHubHeaders。构造方法如下：

1. 将所有以 x-datahub- 为前缀的HTTP请求头的名字转换成小写 。如X-DATAHUB-Client-Version:1.1需要转换成x-datahub-client-version:1.1。
2. 如果请求是以STS获得的AccessKeyId和AccessKeySecret发送时，还需要将获得的security-token值以x-datahub-security-token:token的形式加入到签名字符串中。
3. 将上一步得到的所有HTTP请求头按照名字的字典序进行升序排列。
4. 删除请求头和内容之间分隔符两端出现的任何空格。如x-datahub-client-versionn : 1.1转换成：x-datahub-client-version:1.1。
5. 将每一个头和内容用 \n 分隔符分隔拼成最后的CanonicalizedDataHubHeaders。

CanonicalizedResource构造方法

用户发送请求中想访问的DataHub目标资源被称为CanonicalizedResource。构造方法如下：

1. 将CanonicalizedResource置成空字符串 “”；
2. 放入要访问的DataHub资源，如某个topic： /projects/test_project/topics/test_topic
3. 如果请求的资源包含额外的url参数，按照字典序，从小到大排列并以 & 为分隔符生成参数字符串。在CanonicalizedResource字符串尾添加 ？和参数字符串。此时的CanonicalizedResource如：/projects/test_project/topics/test_topic/connectors/sink_odps?donetime

计算签名头规则

• 签名的字符串必须为 UTF-8 格式。含有中文字符的签名字符串必须先进行 UTF-8 编码，再与AccessKey计算最终签名。
• 签名的方法用RFC 2104中定义的HMAC-SHA1方法，其中Key为 AccessKey 。
• 以 x-datahub- 开头的header在签名验证前需要符合以下规范：
  • header的名字需要变成小写。
  • header按字典序自小到大排序。
  • 分割header name和value的冒号前后不能有空格。
  • 每个Header之后都有一个换行符“\n”，如果没有Header，CanonicalizedDataHubHeaders就设置为空。

签名示例

假如AccessKeyId是”44CF9590006BF252F707”，AccessKeySecret是”OtxrzxIsfpFjA7SwPzILwy8Bw21TLhquhboDYROV”

请求	签名字符串计算公式	签名字符串
POST /projects/test_project/topics/test_topic HTTP/1.1 Host: http://dh-cn-hangzhou.aliyuncs.com User-Agent: customer x-datahub-client-version: 1.1 Content-Type: application/json Date: Thu, 10 Jan 2019 07:28:29 GMT	Signature = base64(hmac-sha1(AccessKey,HTTPMethod + “\n” + Content-Type + “\n” + Date + “\n” + CanonicalizedDataHubHeaders+ CanonicalizedResource))	POST\napplication/json\nThu, 10 Jan 2019 07:28:29 GMT\nx-datahub-client-version:1.1\n/projects/test_project/topics/test_topic

写入数据 - 不按shard写入

请求

• 请求语法

   

  1. POST /projects/<ProjectName>/topics/<TopicName>/shards HTTP/1.1

• 请求元素

名称	类型	描述
Action	String	Action为: pub
ShardId	String	ShardId
Attributes	Map<string, string="">	用户属性字段
Data		如果为BLOB类型，Data为数据Base64编码后数据；如果为TUPLE数据，为String类型数组

响应

• 响应语法

   

  1. HTTP/1.1 200 OK

• 响应元素

名称	类型	描述
FailedRecordCount	Int	失败条数
FailedRecords	Array	失败详情

示例

• 请求示例

   

  1. POST /projects/<ProjectName

  上一篇： [Android systrace系列] 抓取开机过程systrace

  下一篇： 转录组分析 | 使用trim-galore去除低质量的reads和adaptor

  推荐阅读

  • 阿里云DataHub客户端如何使用HTTP请求：常见问题解答和最佳实践