更新时间:2022-10-20 GMT+08:00

获取数据游标

功能介绍

本接口用于获取数据游标。

URI

GET /v2/{project_id}/cursors

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

项目ID。

表2 Query参数

参数

是否必选

参数类型

描述

stream-name

String

已创建的通道名称。

partition-id

String

通道的分区标识符。

可定义为如下两种样式:

  • shardId-0000000000

  • 0

比如一个通道有三个分区,那么分区标识符分别为0, 1, 2,或者shardId-0000000000, shardId-0000000001, shardId-0000000002

cursor-type

String

游标类型。

  • AT_SEQUENCE_NUMBER:从特定序列号(即starting-sequence-number定义的序列号)所在的记录开始读取数据。此类型为默认游标类型。

  • AFTER_SEQUENCE_NUMBER:从特定序列号(即starting-sequence-number定义的序列号)后的记录开始读取数据。

  • TRIM_HORIZON:从最早被存储至分区的有效记录开始读取。例如,某租户使用DIS的通道,分别上传了三条数据A1,A2,A3。N天后(设定A1已过期,A2和A3仍在有效期范围内),该租户需要下载此三条数据,并选择了TRIM_HORIZON这种下载方式。那么用户可下载的数据将从A2开始读取。

  • LATEST:从分区中的最新记录开始读取,此设置可以保证你总是读到分区中最新记录。

  • AT_TIMESTAMP:从特定时间戳(即timestamp定义的时间戳)开始读取。

枚举值:

  • AT_SEQUENCE_NUMBER

  • AFTER_SEQUENCE_NUMBER

  • TRIM_HORIZON

  • LATEST

  • AT_TIMESTAMP

starting-sequence-number

String

序列号。序列号是每个记录的唯一标识符。序列号由DIS在数据生产者调用PutRecords操作以添加数据到DIS数据通道时DIS服务自动分配的。同一分区键的序列号通常会随时间变化增加。PutRecords请求之间的时间段越长,序列号越大。

序列号与游标类型AT_SEQUENCE_NUMBER和AFTER_SEQUENCE_NUMBER强相关,二者共同确定读取数据的位置。

取值范围:0~9223372036854775807。

timestamp

Long

开始读取数据记录的时间戳,与游标类型AT_TIMESTAMP强相关,二者共同确定读取数据的位置。

说明:

此时间戳精确到毫秒。

stream-id

String

通道的唯一标识符。在获取被授权通道的迭代器器时必选。

请求参数

表3 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

String

用户Token。

通过调用IAM服务获取用户Token接口获取(响应消息头中X-Subject-Token的值)。

响应参数

状态码: 200

表4 响应Body参数

参数

参数类型

描述

partition_cursor

String

数据游标。

取值范围:1~512个字符。

说明:

数据游标有效期为5分钟。

最小长度:1

最大长度:512

请求示例

获取数据游标

GET https://{Endpoint}/v2/{project_id}/cursors

响应示例

状态码: 200

正常返回

{
  "partition_cursor" : "eyJnZXRJdGVyYXRvclBhcmFtIjp7InN0cmVhbS1uYW1lIjoianpjIiwicGFydGl0aW9uLWlkIjoiMCIsImN1cnNvci10eXBlIjoiQVRfU0VRVUVOQ0VfTlVNQkVSIiwic3RhcnRpbmctc2VxdWVuY2UtbnVtYmVyIjoiMTAifSwiZ2VuZXJhdGVUaW1lc3RhbXAiOjE1MDYxNTk1NjM0MDV9"
}

状态码

状态码

描述

200

正常返回

错误码

请参见错误码