• Data Ingestion Service

dis
  1. Help Center
  2. Data Ingestion Service
  3. API Reference
  4. API Description
  5. Obtaining a Cursor

Obtaining a Cursor

Function

This API is used to obtain a cursor. A cursor specifies the partition position from which to start reading data records sequentially.

URL

  • URL format

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

  • Parameter description

    None

Request

  • Example request
    GET https://{endpoint}:{port}/v2/6352bba7aaab443aa1d9943efc586a68/cursors?stream-name=lzc08&partition-id=0&cursor-type=AT_SEQUENCE_NUMBER&starting-sequence-number=l1   
    Request Header:    
    Content-Type: application/json  
    X-Sdk-Date: 20180820T024248Z    
    Authorization: SDK-HMAC-SHA256  
    Credential=QRUP2R3QFNAOVAWMYHZW/20180820/eu-de/test/sdk_request,    
    SignedHeaders=host;x-sdk-date,  
    Signature=9d8b56b055c0e1f7a9498d881a7cb726be91b4f0cde1773b0b1557e987a480ce    
  • 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, underscores (_), and hyphens (-) are allowed.

    Only letters, digits, hyphens (-), and underscores (_) are allowed.

    partition-id

    Yes

    String

    ID of the partition to get the cursor for.

    Value range: 0 to 2147483647

    cursor-type

    No

    String

    Cursor type.

    • AT_SEQUENCE_NUMBER: The consumer application starts reading from the position denoted by a specific sequence number. This is the default cursor type.
    • AFTER_SEQUENCE_NUMBER: The consumer application starts reading right after the position denoted by a specific sequence number.
    • TRIM_HORIZON: The consumer application starts reading at the last untrimmed record in the partition in the system, which is the oldest data record in the partition.
    • LATEST: The consumer application start reading right after the most recent record in the partition.
    • AT_TIMESTAMP: The consumer application starts reading from a specific 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.

    Value range: 0 to 9223372036854775807

    timestamp

    No

    Long

    Timestamp when the data record starts to be read. This parameter is used together with AT_TIMESTAMP.

    NOTE:
    • If the starting-sequence-number parameter is transferred, it is used preferentially. If the starting-sequence-number parameter is not transferred, the timestamp parameter will be used.
    • 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.