doc-exports/docs/dis/api-ref/dis_02_0020.html

Obtaining Data Cursors

Function

This API is used to obtain data cursors.

Calling Method

For details, see Calling APIs.

URI

GET /v2/{project_id}/cursors

Table 1 Path Parameters

Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID

Table 2 Query Parameters

Parameter	Mandatory	Type	Description
stream-name	Yes	String	Name of the stream
partition-id	Yes	String	Partition identifier of the stream.Two partition ID formats are available:- shardId-0000000000- 0For example, if a stream has three partitions, the partition IDs are 0, 1, and 2, or shardId-0000000000, shardId-0000000001, and shardId-0000000002.
cursor-type	No	String	Cursor type.- AT_SEQUENCE_NUMBER: Data is read from the position denoted by a specific sequence number (that is defined by starting-sequence-number). This type is the default cursor type.- AFTER_SEQUENCE_NUMBER: Data is read right after the position denoted by a specific sequence number (that is defined by starting-sequence-number).- TRIM_HORIZON: Data is read from the earliest valid record stored in the partition. For example, a tenant used a DIS stream to upload three pieces of data A1, A2, and A3. Assuming that A1 expires but A2 and A3 are still valid after a period of time, if the tenant specifies TRIM_HORIZON for downloading data, only A2 and A3 can be downloaded.- LATEST: Data is read just after the most recent record in the partition. This setting ensures that you always read the most recent data in the partition.- AT_TIMESTAMP: Data is read from the position denoted by a specific timestamp. Enumeration values: AT_SEQUENCE_NUMBER AFTER_SEQUENCE_NUMBER TRIM_HORIZON LATEST AT_TIMESTAMP
starting-sequence-number	No	String	Sequence number. A sequence number is the unique identifier of each record. DIS automatically allocates a sequence number when the data producer calls the PutRecords operation to add data to the DIS stream. The sequence number of the same partition key usually changes with time. A longer interval between PutRecords requests results in a larger sequence number.The sequence number is closely related to cursor types AT_SEQUENCE_NUMBER and AFTER_SEQUENCE_NUMBER. The two parameters determine the location of the data to be accessed.Value range: 0 to 9223372036854775807
timestamp	No	Long	Timestamp when the data record starts to be read, which is closely related to cursor type AT_TIMESTAMP. The two parameters determine the position of the data to be read. Note: This timestamp is accurate to milliseconds.

Request Parameters

Table 3 Request header parameters

Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. It can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter	Type	Description
partition_cursor	String	Data cursor Value: 1 to 512 characters. Note: The validity period of a cursor is 5 minutes. Minimum: 1 Maximum: 512

Example Requests

Obtaining Data Cursors

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

Example Responses

Status code: 200

Normal response

{
  "partition_cursor" : "eyJnZXRJdGVyYXRvclBhcmFtIjp7InN0cmVhbS1uYW1lIjoianpjIiwicGFydGl0aW9uLWlkIjoiMCIsImN1cnNvci10eXBlIjoiQVRfU0VRVUVOQ0VfTlVNQkVSIiwic3RhcnRpbmctc2VxdWVuY2UtbnVtYmVyIjoiMTAifSwiZ2VuZXJhdGVUaW1lc3RhbXAiOjE1MDYxNTk1NjM0MDV9"
}

Status Codes

Status Code	Description
200	Normal response

Error Codes

See Error Codes.

Parent topic: Data Management