阿里云DataHub--客户端使用HTTP请求--常见问题-及最佳实践-JAVA版

参考官方DataHub API规范：

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

以下 “接口规范”~~~”签名计算原理说明“~~~“写入数据” 原封不动的摘自官网API介绍.

...重点常见问题及 DEMO程序...

一. 接口规范

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	详细错误描述信息

错误响应示例：

 
 HTTP/1.1403
 x-datahub-request-id:2018050817492199d6650a00000039
Content-Type: application/json
Content-Length: xxx
{
"ErrorCode":"Unauthorized",
"ErrorMessage":"Authroize failed"
}

5. 限制描述

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

二、Authorization字段计算的方法

 
Authorization="DATAHUB "+AccessId+":"+Signature
Signature= base64(hmac-sha1(AccessKey,
HTTPMethod+"\n"
+Content-Type+"\n"
+Date+"\n"
+CanonicalizedDataHubHeaders+"\n"
+CanonicalizedResource))

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。构造方法如下：

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

CanonicalizedResource构造方法

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

将CanonicalizedResource置成空字符串 “”；
放入要访问的DataHub资源，如某个topic： /projects/test_project/topics/test_topic
如果请求的资源包含额外的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>/topics/<TopicName>/shards HTTP/1.1
2. x-datahub-client-version: 1.1
3. Date: Tue, 08 May 2018 09:47:48 GMT
4. Authorization: AuthorizationString
5. Content-Type: applicaton/json
6. Conent-Length: xxx
8. {
9. "Action": "pub",
10. "Records": [
11. {
12. "ShardId": "0",
13. "Attributes": {
14. "attr1": "value1",
15. "attr2": "value2"
16. },
17. "Data": ["A","B","3","4"]
18. }
19. ]
20. }

 
 // BLOB
 {
 "Action": "pub",
 "Record": [
 {
 "ShardId": "0",
 "Attributes": {
 "attr1": "value1",
 "attr2": "value2"
 },
 "Data": "Base64String"
 }
 ]
 }

响应示例
1. HTTP/1.1 200 OK
2. x-datahub-request-id: 2018050817492199d6650a00000039
3. Content-Type: applicaton/json
4. Conent-Length: xxx
6. {
7. "FailedRecordCount": 1,
8. "FailedRecords": [
9. {
10. "Index": 0,
11. "ErrorCode": "errorCode",
12. "ErrorMessage": "errorMsg"
13. }
14. ]
15. }

-------------------------------------------------------------------------- 华丽的分割线--------------------------------------------------------------------------

签名算法：参考阿里官方给出的JAVA版工具类 UrlUtil.java SignatureUtils.java，可以直接使用。

https://www.alibabacloud.com/help/zh/doc-detail/28618.htm

官方提供的Java SDK 方式对Java版本要求最低JDK1.8，我这里是一个基于JDK1.6的老项目无法满足；故而使用HTTP API的方式；

-------------------------------------------------------------------------- 华丽的分割线--------------------------------------------------------------------------

常见问题：

1. Unauthorized “The signature is Time-Expired.”

　客户端与服务器端时间不一致，两端时间差不能超过15分钟，另外可能存在时区不一致的情况,当时我的客户端应用默认是东八区的服务器比我晚了8小时,还是我们用抓包工具发现的问题。

2. Unauthorized “Invalid date format .”

　　用于计算签名或发送请求头的Date字段时间格式不对，这里必须使用GMT格式字符串 "EEE, dd MMM yyyy HH:mm:ss 'GMT'"

3. Unauthorized “Authorize failed .”

　　授权失败，这个只能服务器端分析日志来帮客户端定位问题了。我当时是在计算签名的时候使用转义后的\n 而导致了这样的问题

4. InvalidParameter “Parse body failed,Offset 1 ”

　　解析报文体的时候，位置一的字符不合法；因为官方只支持双引号的字符串，若使用单引号传数据会报类似这样的错误.

5. InvalidParameter “Parse body failed,Offset 118 ”

　　解析报文体的时候，位置118处的字符是中文；只需要在发送数据的实体里面加上UTF-8编码即可.

最佳实践DEMO源码：