Function

This API is used to obtain a data cursor.

There are five cursor types available:

• AT_SEQUENCE_NUMBER
• AFTER_SEQUENCE_NUMBER
• TRIM_HORIZON
• LATEST
• AT_TIMESTAMP

To download streaming data, you need to determine the position where the data is obtained from the partition, that is, to obtain the cursor. After the start position is determined, the data is obtained cyclically.

URI

• URI format

  GET /v2/{project_id}/cursors{?stream-name,stream-id,partition-id,cursor-type,starting-sequence-number}

• Parameter description

  None

Request

• Example request

  GET https://{endpoint}/v2/{project_id}/cursors?stream-name=lzc08&stream-id=i9eOJp4sTYRApsWwJDS&partition-id=0&cursor-type=AT_SEQUENCE_NUMBER&starting-sequence-number=l1        

• Parameter description

  Table 1 Parameter description

  Parameter	Mandatory	Type	Description
  stream-name	Yes	String	Name of the stream created on the management console. Value range: Only letters, digits, hyphens (-), and underscores (_) are allowed. The value must be 1 to 64 characters long.
  stream_id	No	String	Unique ID of the stream. If no stream is found based on stream_name and stream_id is not empty, stream_id is used to search for the stream.
  partition-id	Yes	String	Partition ID of a stream. Two partition ID formats are available: shardId-0000000000 0
  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 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 records that are stored in the partition. For example, a tenant uses a DIS stream to upload three pieces of data A1, A2, and A3. N days later, A1 has expired and A2 and A3 are still in the validity period. In this case, if the tenant uses TRIM_HORIZON to download the data, only A2 and A3 are downloadable. 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 (that is defined by timestamp).
  starting-sequence-number	No	String	Sequence number of an individual data record. Each data record has a sequence number that is unique within its partition. The sequence number is assigned by DIS when a data producer calls PutRecords to add data to a DIS stream. Sequence numbers for the same partition key generally increase over time; the longer the time period between write requests (PutRecords requests), the larger the sequence numbers become. 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 accessed. It is closely related to cursor type AT_TIMESTAMP. The two parameters determine the location of the data to be accessed. NOTE: This timestamp is accurate to milliseconds.

Response

• Example response

  {
   "partition_cursor": "eyJnZXRJdGVyYXRvclBhcmFtIjp7InN0cmVhbS1uYW1lIjoianpjIiwicGFydGl0aW9uLWlkIjoiMCIsImN1cnNvci10eXBlIjoiQVRfU0VRVUVOQ0VfTlVNQkVSIiwic3RhcnRpbmctc2VxdWVuY2UtbnVtYmVyIjoiMTAifSwiZ2VuZXJhdGVUaW1lc3RhbXAiOjE1MDYxNTk1NjM0MDV9"
  }

• Parameter description

  Table 2 Response parameter description

  Parameter	Type	Description
  partition_cursor	String	Cursor of the partition used to specify the position in the partition from which to start reading data records sequentially. Value: 1 to 512 characters NOTE: The validity period of a cursor is 5 minutes.

Status Code

• Normal

  200 OK

• Failed

  For more information, see Error Codes.