Request Syntax Request Parameters Response Syntax Response Elements Errors See Also

GetShardIterator

Returns a shard iterator that serves as a bookmark for reading data from a specific position in an Amazon Keyspaces data stream's shard. The shard iterator specifies the shard position from which to start reading data records sequentially. You can specify whether to begin reading at the latest record, the oldest record, or at a particular sequence number within the shard.

Request Syntax


{
   "sequenceNumber": "string",
   "shardId": "string",
   "shardIteratorType": "string",
   "streamArn": "string"
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

sequenceNumber

The sequence number of the data record in the shard from which to start reading. Required if ShardIteratorType is AT_SEQUENCE_NUMBER or AFTER_SEQUENCE_NUMBER. This parameter is ignored for other iterator types.

Type: String

Length Constraints: Minimum length of 21. Maximum length of 48.

Required: No

shardId

The identifier of the shard within the stream. The shard ID uniquely identifies a subset of the stream's data records that you want to access.

Type: String

Length Constraints: Minimum length of 28. Maximum length of 65.

Required: Yes

shardIteratorType

Determines how the shard iterator is positioned. Must be one of the following:

TRIM_HORIZON - Start reading at the last untrimmed record in the shard, which is the oldest data record in the shard.
AT_SEQUENCE_NUMBER - Start reading exactly from the specified sequence number.
AFTER_SEQUENCE_NUMBER - Start reading right after the specified sequence number.
LATEST - Start reading just after the most recent record in the shard, so that you always read the most recent data.

Type: String

Valid Values: TRIM_HORIZON | LATEST | AT_SEQUENCE_NUMBER | AFTER_SEQUENCE_NUMBER

Required: Yes

streamArn

The Amazon Resource Name (ARN) of the stream for which to get the shard iterator. The ARN uniquely identifies the stream within Amazon Keyspaces.

Type: String

Length Constraints: Minimum length of 37. Maximum length of 1024.

Required: Yes

Response Syntax


{
   "shardIterator": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

shardIterator

The unique identifier for the shard iterator. This value is used in the GetRecords operation to retrieve data records from the specified shard. Each shard iterator expires 15 minutes after it is returned to the requester.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 4096.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have sufficient access permissions to perform this operation.

This exception occurs when your IAM user or role lacks the required permissions to access the Amazon Keyspaces resource or perform the requested action. Check your IAM policies and ensure they grant the necessary permissions.

HTTP Status Code: 400

InternalServerException

The Amazon Keyspaces service encountered an unexpected error while processing the request.

This internal server error is not related to your request parameters. Retry your request after a brief delay. If the issue persists, contact AWS Support with details of your request to help identify and resolve the problem.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource doesn't exist or could not be found.

This exception occurs when you attempt to access a keyspace, table, stream, or other Amazon Keyspaces resource that doesn't exist or that has been deleted. Verify that the resource identifier is correct and that the resource exists in your account.

HTTP Status Code: 400

ThrottlingException

The request rate is too high and exceeds the service's throughput limits.

This exception occurs when you send too many requests in a short period of time. Implement exponential backoff in your retry strategy to handle this exception. Reducing your request frequency or distributing requests more evenly can help avoid throughput exceptions.

HTTP Status Code: 400

ValidationException

The request validation failed because one or more input parameters failed validation.

This exception occurs when there are syntax errors in the request, field constraints are violated, or required parameters are missing. To help you fix the issue, the exception message provides details about which parameter failed and why.

HTTP Status Code: 400