接口参考

Size: px

Start display at page:

Download "接口参考"

暇邀能
4 years ago
Views:

1 数据接入服务接口参考文档版本 02 发布日期华为技术有限公司

2 版权所有华为技术有限公司 2016 保留一切权利非经本公司书面许可, 任何单位和个人不得擅自摘抄复制本文档内容的部分或全部, 并不得以任何形式传播商标声明和其他华为商标均为华为技术有限公司的商标本文档提及的其他所有商标或注册商标, 由各自的所有人拥有注意您购买的产品服务或特性等应受华为公司商业合同和条款的约束, 本文档中描述的全部或部分产品服务或特性可能不在您的购买或使用范围之内除非合同另有约定, 华为公司对本文档内容不做任何明示或默示的声明或保证由于产品版本升级或其他原因, 本文档内容会不定期进行更新除非另有约定, 本文档仅作为使用指导, 本文档中的所有陈述信息和建议不构成任何明示或暗示的担保华为技术有限公司地址 : 深圳市龙岗区坂田华为总部办公楼邮编 : 网址 : i

3 前言前言概述本文档描述了数据接入服务接口的使用和参数说明等读者对象本文档主要适用于以下工程师 : 技术服务工程师维护工程师符号约定在本文中可能出现下列标志, 它们所代表的含义如下符号说明用于警示紧急的危险情形, 若不避免, 将会导致人员死亡或严重的人身伤害用于警示潜在的危险情形, 若不避免, 可能会导致人员死亡或严重的人身伤害用于警示潜在的危险情形, 若不避免, 可能会导致中度或轻微的人身伤害用于传递设备或环境安全警示信息, 若不避免, 可能会导致设备损坏数据丢失设备性能降低或其它不可预知的结果注意不涉及人身伤害用于突出重要 / 关键信息最佳实践和小窍门等说明不是安全警示信息, 不涉及人身设备及环境伤害 ii

4 前言修改记录文档版本发布日期修改说明第二次正式发布文档内容更新如下 : 新增了 4.7 用户获取迭代器修改了如下章节 : 4.5 上传单条数据 4.6 上传多条数据 4.8 下载数据第一次正式发布 iii

5 目录目录前言... ii 1 API 接口简介消息头请求消息头响应消息头请求响应码创建流实例获取流实例列表删除流实例查看流实例监控信息上传单条数据上传多条数据用户获取迭代器下载数据 iv

6 1 API 接口简介 1 API 接口简介用户可以通过 REST API 接口方式单独或集成到业务程序进行管理和使用 DIS 接口适用范围该接口适用于华为企业云 DIS 平台接口接口特性描述 DIS 通过高度灵活的 REST API 对外开放接口, 供客户系统集成使用接口设计原则接口参数类型中 List 的表现形式为数组 IP 地址以点分格式表示, 如 : 传输协议华为企业云 DIS 接口采用 HTTPS 传输协议 HTTPS 请求方在和服务器建立连接并发出 HTTPS 请求后, 不能在该连接上再发出其他请求, 必须等待所发请求的响应, 收到响应后才可以继续发请求请求方法 REST API 支持 POST GET PUT 和 DELETE 请求方法 1

7 2 消息头 2 消息头 2.1 请求消息头 2.2 响应消息头 2

8 2 消息头 2.1 请求消息头 DIS 的请求消息头如表 2-1 所示表 2-1 请求消息头消息头名称说明 Content-Type 资源内容的类型, 例如 :application/json 类型 :String 默认值 : 无必选参数 X-Sdk-Date 请求发起端的日期和时间, 格式为 : YYYYMMDD'T'HHMMSS'Z', 例如 : T101459Z 类型 :String 默认值 : 无必选参数 Authorization 请求消息中可带的鉴权信息, 例如 :SDK-HMAC-SHA256 Credential=QRUP2R3QFNAOVAWMYHZW/ / northchina/test/sdk_request, SignedHeaders=host;x-sdk-date, Signature=9d8b56b055c0e1f7a9498d881a7cb726be91b4f0cde 1773b0b1557e987a480ce 类型 :String 默认值 : 无必选参数 Host 请求的服务信息, 例如 : :7440 类型 :String 默认值 : 无可选参数 2.2 响应消息头 DIS 的响应消息头如表 2-2 所示 3

9 2 消息头表 2-2 响应消息头消息头名称说明 Content-Type 资源内容的类型, 例如 :application/json 类型 :String 默认值 : 无 Date DAS 系统响应的时间, 例如 :Mon, 15 Jul :08:05 GMT 类型 :String 默认值 : 无 4

10 3 请求响应码 3 请求响应码华为企业云 DIS 接口采用 HTTPS 传输协议收发请求, 请求响应码如表 1 所示 5

11 3 请求响应码表 3-1 请求响应码响应码说明 100 Continue 客户端应当继续发送请求这个临时响应用来通知客户端, 它的部分请求已经被服务器接收, 且仍未被拒绝 200 OK 请求已成功, 请求所希望的响应头或数据体将随此响应返回 201 Created 请求已经被实现, 有一个新的资源已经依据请求的需要而建立, 且其 URI 已经随 Location 头信息返回如果需要的资源无法及时建立, 应当返回 '202 Accepted' 202 Accepted 服务器已接受请求, 但尚未处理该请求可能会被拒绝, 最终可能会, 也可能不会被执行 400 Bad Request 语义有误, 当前请求无法被服务器解析除非进行修改, 否则客户端不应重复提交这个请求请求参数有误 401 Unauthorized 当前请求需要用户验证 403 Forbidden 服务器已经解析请求, 但是拒绝执行 404 Not Found 请求失败, 在服务器上未找到请求所希望得到的资源 405 Method Not Allowed 请求行中指定的请求方法不能被用于请求相应的资源 406 Not Acceptable 请求的资源的内容特性无法满足请求头中的条件, 因而无法生成响应实体 409 Conflict 由于和被请求的资源的当前状态之间存在冲突, 请求无法完成 410 Gone 被请求的资源在服务器上已经不再可用, 并且没有任何已知的转发地址 412 Precondition Failed 服务器在验证在请求的头字段中给出先决条件时, 未能满足其中的一个或多个 500 Internal Server Error 服务器遇到了一个未曾预料的状况, 导致无法完成对请求的处理 501 Not Implemented 服务器不支持当前请求所需要的某个功能 503 Service Unavailable 由于临时服务器维护或者过载, 服务器当前无法处理请求 6

12 4.1 创建流实例 4.2 获取流实例列表 4.3 删除流实例 4.4 查看流实例监控信息 4.5 上传单条数据 4.6 上传多条数据 4.7 用户获取迭代器 4.8 下载数据 7

13 4.1 创建流实例功能介绍创建一个新的流实例 URL URL 格式 POST /v1/stream/insertstream 表 4-1 URL 参数说明名称是否必选类型说明 streamname 是 String 流实例名称 streampartitions 是 Int 分区数在用户发送或者接收实时数据时, 需要指定流名称, 因此创建实例时流名称不能重复流名称由字母数字和 _ 组成, 长度为 1~50 字符分区 (Partition) 是 DIS 数据流的基本吞吐量单位, 每个 Partition 提供 1MB/ 秒数据输入和 2MB/ 秒数据输出容量取值为 1~100, 请根据业务量进行配置请求请求样例 POST Request Header: X-Sdk-Date: T024248Z Authorization: SDK-HMAC-SHA256 Credential=QRUP2R3QFNAOVAWMYHZW/ /northchina/test/ sdk_request, SignedHeaders=host;x-sdk-date, Signature=9d8b56b055c0e1f7a9498d881a7cb726be91b4f0cde1773b0b1557e987a480ce 请参见表 4-1 响应响应样例 HTTP/ OK Date: Mon, 15 Jul :08:05 GMT { 8

14 } "data": "", "totalnum": 0, "message": "", "errorcode": -1 表 4-2 响应参数说明参数名是否必选说明 data 是数据 totalnum 是数据条总数 message 是错误信息 errorcode 是错误码 -1: 数据正常 1: 数据异常响应码正常 200 OK 失败 9

15 表 4-3 请求失败响应码响应码说明 400 Bad Request 语义有误, 当前请求无法被服务器解析除非进行修改, 否则客户端不应重复提交这个请求请求参数有误 401 Unauthorized 当前请求需要用户验证 403 Forbidden 服务器已经解析请求, 但是拒绝执行 404 Not Found 请求失败, 在服务器上未找到请求所希望得到的资源 405 Method Not Allowed 请求行中指定的请求方法不能被用于请求相应的资源 406 Not Acceptable 请求的资源的内容特性无法满足请求头中的条件, 因而无法生成响应实体 409 Conflict 由于和被请求的资源的当前状态之间存在冲突, 请求无法完成 410 Gone 被请求的资源在服务器上已经不再可用, 并且没有任何已知的转发地址 412 Precondition Failed 服务器在验证在请求的头字段中给出先决条件时, 未能满足其中的一个或多个 500 Internal Server Error 服务器遇到了一个未曾预料的状况, 导致无法完成对请求的处理 501 Not Implemented 服务器不支持当前请求所需要的某个功能 503 Service Unavailable 由于临时服务器维护或者过载, 服务器当前无法处理请求 4.2 获取流实例列表功能介绍获取用户创建的所有流实例 URL URL 格式 GET /v1/stream/streams 10

16 表 4-4 URL 参数说明名称是否必选类型说明 pageindex 是 Int 当前查询页码 pagetotal 是 Int 分页查询每页返回的最大实例数量 sortby 是 String 返回的流列表排序类型 StreamName: 按流名称排序 CreateTimeStr: 按创建日期排序 StreamPartitions: 按分区数量排序 order 是 String 流列表的排序方式 asc: 升序 desc: 降序请求请求样例 GET Request Header: X-Sdk-Date: T024248Z Authorization: SDK-HMAC-SHA256 Credential=QRUP2R3QFNAOVAWMYHZW/ /northchina/test/ sdk_request, SignedHeaders=host;x-sdk-date, Signature=9d8b56b055c0e1f7a9498d881a7cb726be91b4f0cde1773b0b1557e987a480ce 请参见表 4-4 响应响应样例 HTTP/ OK Date: Mon, 15 Jul :08:05 GMT { "data": [ { "streamid": "1078bcaf-d aa4a-4c2bec402de5", "streamname": "jzct", "userid": "e4c6ab7f41c648dfad3e2336a9ee6724", "username": "xiechuanqiao", "streampartitions": 2, "state": 0, "deletestate": 0, "createtime": , "createtimestr": "2016/07/26 10:29:35", "updatetime": null, "updatetimestr": null } ], "totalnum": 1, "message": "", 11

17 } "errorcode": -1 表 4-5 响应参数说明参数名是否必选说明 data 是 List data,data 为对象列表结构体, 请参见表 4-6 totalnum 是数据条总数 message 否错误信息 errorcode 是错误码 -1: 数据正常 1: 数据异常 12

18 表 4-6 data 参数说明参数名是否必选说明 streamid 否流实例 ID streamname 否流实例名称 userid 否用户 ID username 否用户名 streampartitions 否分区数 state 否流实例状态在用户发送或者接收实时数据时, 需要指定流名称, 因此创建实例时流名称不能重复流名称由字母数字和 _ 组成, 长度为 1~50 字符分区 (Partition) 是 DIS 数据流的基本吞吐量单位, 每个 Partition 提供 1MB/ 秒数据输入和 2MB/ 秒数据输出容量取值为 1~100, 请根据业务量进行配置 0: 正常 1: 已删除 deletestate 否记录用户是否删除了此条数据 0: 未删除 1: 已删除 createtime 否创建时间 createtimestr 否创建时间字符串 updatetime 否更新时间 updatetimestr 否更新时间字符串响应码正常 200 OK 失败请参见表删除流实例功能介绍在上传下载数据完成后或者实例运行异常无法提供服务时, 可删除流实例 13

19 URL URL 格式 POST /v1/stream/deletestream 表 4-7 URL 参数说明名称是否必选类型说明 streamid 是 String 流实例 ID 请求请求样例 PUT Request Header: X-Sdk-Date: T024248Z Authorization: SDK-HMAC-SHA256 Credential=QRUP2R3QFNAOVAWMYHZW/ /northchina/test/ sdk_request, SignedHeaders=host;x-sdk-date, Signature=9d8b56b055c0e1f7a9498d881a7cb726be91b4f0cde1773b0b1557e987a480ce 请参见表 4-7 响应响应样例 HTTP/ OK Date: Mon, 15 Jul :08:05 GMT { "data": "", "totalnum": 0, "message": "", "errorcode": -1 } 表 4-8 响应参数说明参数名是否必选说明 data 否数据 totalnum 否数据条总数 message 否错误信息 errorcode 否错误码 -1: 数据正常 1: 数据异常 14

20 响应码正常 200 OK 失败请参见表查看流实例监控信息功能介绍查看用户创建的流实例的监控信息 URL URL 格式 GET /v1/monitor/getmonitorinfo 表 4-9 URL 参数说明名称是否必选类型说明 streamname 是 String 流实例名称 partitionindex 是 Int 分区编号 starttime 是 String 开始时间 endtime 是 String 结束时间在用户发送或者接收实时数据时, 需要指定流名称, 因此创建实例时流名称不能重复流名称由字母数字和 _ 组成, 长度为 1~50 字符请求请求样例 GET starttime= &endtime= &streamname=jzct&partitionindex=0 Request Header: X-Sdk-Date: T024248Z Authorization: SDK-HMAC-SHA256 Credential=QRUP2R3QFNAOVAWMYHZW/ /northchina/test/ sdk_request, SignedHeaders=host;x-sdk-date, Signature=9d8b56b055c0e1f7a9498d881a7cb726be91b4f0cde1773b0b1557e987a480ce 请参见表

21 响应响应样例 HTTP/ OK Date: Mon, 15 Jul :08:05 GMT { } "data": { }, "totalnum": 1, "message": "", "errorcode": -1 表 4-10 响应参数说明参数名是否必选说明 data 否数据 totalnum 否数据条总数 message 否错误信息 errorcode 否错误码 -1: 数据正常 1: 数据异常响应码正常 200 OK 失败请参见表上传单条数据功能介绍上传单条数据到 DIS 实例中 URL 请求 URL 格式 PUT /v1/gw/push 无请求样例 16

22 PUT Request Header: X-Sdk-Date: T024248Z Authorization: SDK-HMAC-SHA256 Credential=QRUP2R3QFNAOVAWMYHZW/ /northchina/test/ sdk_request, SignedHeaders=host;x-sdk-date, Signature=9d8b56b055c0e1f7a9498d881a7cb726be91b4f0cde1773b0b1557e987a480ce Request Body: { } "StreamName": "lzc88", "PartitionKey": "0", "Data": "MTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTE=", "SequenceNumberForOrdering": " " 表 4-11 请求参数说明名称是否必选类型说明 StreamName 是 String Console 控制台已创建流实例的名称 PartitionKey 是 String 流分区值 SequenceNumberFor Ordering 否 String 序列号, 默认从 0 开始 Data 是 ByteBuff er 需要上传的数据响应响应样例 HTTP/ OK Date: Mon, 15 Jul :08:05 GMT "-1" 表 4-12 响应参数说明参数名是否必选说明 -1 是表示操作成功是表示参数错误是表示数据为空是表示流不存在是表示数据字节数超过流控 17

23 响应码正常 200 OK 失败表 4-13 请求失败响应码响应码说明 400 Bad Request 语义有误, 当前请求无法被服务器解析除非进行修改, 否则客户端不应重复提交这个请求请求参数有误 401 Unauthorized 当前请求需要用户验证 403 Forbidden 服务器已经解析请求, 但是拒绝执行 404 Not Found 请求失败, 在服务器上未找到请求所希望得到的资源 405 Method Not Allowed 请求行中指定的请求方法不能被用于请求相应的资源 406 Not Acceptable 请求的资源的内容特性无法满足请求头中的条件, 因而无法生成响应实体 409 Conflict 由于和被请求的资源的当前状态之间存在冲突, 请求无法完成 410 Gone 被请求的资源在服务器上已经不再可用, 并且没有任何已知的转发地址 412 Precondition Failed 服务器在验证在请求的头字段中给出先决条件时, 未能满足其中的一个或多个 500 Internal Server Error 服务器遇到了一个未曾预料的状况, 导致无法完成对请求的处理 501 Not Implemented 服务器不支持当前请求所需要的某个功能 503 Service Unavailable 由于临时服务器维护或者过载, 服务器当前无法处理请求 4.6 上传多条数据功能介绍上传多条数据到 DIS 实例中 URL URL 格式 PUT /v1/gw/pushes 18

24 表 4-14 请求参数说明名称是否必选类型说明 StreamName 是 String Console 控制台已创建流实例的名称 Records 是 PutRecords RequestEnt ry List record, 请参见表 4-15 表 4-15 PutRecordsRequestEntry 参数说明名称是否必选类型说明 Data 是 ByteBuffer 需要上传的数据 ExplicitHashKe y 否 String 流分区实际值 PartitionKey 是 String 流分区值请求请求样例 PUT Request Header: X-Sdk-Date: T024248Z Authorization: SDK-HMAC-SHA256 Credential=QRUP2R3QFNAOVAWMYHZW/ /northchina/test/ sdk_request, SignedHeaders=host;x-sdk-date, Signature=9d8b56b055c0e1f7a9498d881a7cb726be91b4f0cde1773b0b1557e987a480ce Request Body { } "StreamName": "lzc08", "Records": [ { "Data": "MTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTE=", "ExplicitHashKey": 0, "PartitionKey": "0" } ] 请参见表 4-14 响应响应样例 HTTP/ OK 19

25 Date: Mon, 15 Jul :08:05 GMT "-1" 表 4-16 响应参数说明参数名是否必选说明 -1 是表示操作成功是表示参数错误是表示数据为空是表示流不存在是表示数据字节数超过流控响应码正常 200 OK 失败请参见表用户获取迭代器功能介绍用户获取迭代器, 根据迭代器获取一次数据和下一个迭代器 URL 请求 URL 格式 POST /v1/gw/getsharditerator 无请求样例 POST Request Header: X-Sdk-Date: T024248Z Authorization: SDK-HMAC-SHA256 Credential=QRUP2R3QFNAOVAWMYHZW/ /northchina/test/sdk_request, SignedHeaders=host;x-sdk-date, Signature=9d8b56b055c0e1f7a9498d881a7cb726be91b4f0cde1773b0b1557e987a480ce Request Body { "StreamName": "lzc08", "ShardId": "0", 20

26 "ShardIteratorType": "AT_SEQUENCE_NUMBER", "StartingSequenceNumber": "0", "TimeStamp": "0" } 表 4-17 请求参数说明名称是否必选类型说明 StreamName 是 String Console 控制台已创建流实例的名称 ShardId 是 String 流分区值 ShardIteratorTy pe StartingSequenc enumber 否 String 迭代类型否 String 序列号序列号是每个记录的唯一标识符序列号由 DIS 在数据生产者调用 PutRecord 操作以添加数据到 DIS 数据流时分配同一分区键的序列号通常会随时间变化增加 PutRecord 或 PutRecords 请求之间的时间段越长, 序列号越大 TimeStamp 否 long 时间戳响应响应样例 HTTP/ OK Date: Mon, 15 Jul :08:05 GMT "iterator":" a3a38" 表 4-18 要素说明名称参数类型说明 Iterator GetShardIterat orresult 响应数据具体内容请参见表 4-19 表 4-19 GetShardIteratorResult 参数说明名称参数类型说明 ShardIterator String 迭代器 21

27 响应码正常 200 OK 失败请参见表下载数据功能介绍从 DIS 实例中下载数据 URL 请求 URL 格式 POST /v1/gw/getrecords 无请求样例 POST Request Header: X-Sdk-Date: T024248Z Authorization: SDK-HMAC-SHA256 Credential=QRUP2R3QFNAOVAWMYHZW/ /northchina/test/ sdk_request, SignedHeaders=host;x-sdk-date, Signature=9d8b56b055c0e1f7a9498d881a7cb726be91b4f0cde1773b0b1557e987a480ce Request Body: { "ShardIterator": " a3a38", "Limit": "100" } 22

28 表 4-20 请求参数说明名称是否必选类型说明 ShardIterator 是 String 迭代器 StreamName 是 String 流实例名称 PartitionId 是 String 流分区值 PartitionIteratorType 否 String 分区迭代类型在用户发送或者接收实时数据时, 需要指定流名称, 因此创建实例时流名称不能重复流名称由字母数字和 _ 组成, 长度为 1~50 字符 StartingSequenceNu mber 否 String 序列号序列号是每个记录的唯一标识符序列号由 DIS 在数据生产者调用 PutRecord 操作以添加数据到 DIS 数据流时分配同一分区键的序列号通常会随时间变化增加 PutRecord 或 PutRecords 请求之间的时间段越长, 序列号越大 TimeStamp 否 long 时间戳 Limit 是 Int 每个请求获取 Record 的最大数量取值范围 :1~10000 响应响应样例 HTTP/ OK Date: Mon, 15 Jul :08:05 GMT { " Records ":[ "data":"a", "partitionkey":0, "sequencenumber ":0, "approximatearrivaltimestamp":0], " NextShardIterator ":" a3a38", " MillisBehindLatest ":0 } 23

29 表 4-21 响应参数说明参数名类型说明 Record NextShardIterato r MillisBehindLate st GetRecordsR esult String long list record,record 为对象结构体, 请参见表 4-22 下一个迭代器时间戳表 4-22 GetRecordsResult 参数说明参数名类型说明 Data Byte 数据 PartitionKey Int 下载数据的实际分区 ID SequenceNumber Int 预留参数, 暂时不使用 ApproximateArrival Timestamp long 时间戳响应码正常 200 OK 失败请参见表

API参考

API参考文档版本 03 发布日期 2018-06-20 华为技术有限公司版权所有华为技术有限公司 2018 保留一切权利非经本公司书面许可, 任何单位和个人不得擅自摘抄复制本文档内容的部分或全部, 并不得以任何形式传播商标声明和其他华为商标均为华为技术有限公司的商标本文档提及的其他所有商标或注册商标, 由各自的所有人拥有注意您购买的产品服务或特性等应受华为公司商业合同和条款的约束, 本文档中描述的全部或部分产品