GetShardIterator
Returns an iterator of a stream shard.
The iterator's lifetime expires 5 minutes after it is received.
The iterator sets the position in the shard to start reading the sequence of messages from using the GetRecords method. The position is set using the sequence number of the message in the shard.
The request must specify the type of iterator.
For example, to get an iterator to read a sequence starting from a message with a certain sequence number, specify the AT_SEQUENCE_NUMBER iterator type and the message number in the StartingSequenceNumber parameter. The AFTER_SEQUENCE_NUMBER iterator type returns a value for reading the sequence starting from the message following the one specified in the StartingSequenceNumber parameter. The sequence numbers used are those returned when calling the PutRecord, PutRecords, GetRecords, and DescribeStream methods.
To get an iterator for reading a sequence starting at a certain point in time, specify the AT_TIMESTAMP iterator type and the time in the Timestamp parameter.
The TRIM_HORIZON iterator type allows reading a sequence starting from the oldest record and the LATEST type from the most recent record in the shard.
When reading stream messages in a loop with GetRecords, use GetShardIterator to get the shard iterator to be used in the first GetRecords request. For subsequent reads, you can use the NextShardIterator value returned by GetRecords.
If you call the GetShardIterator method too often, a ProvisionedThroughputExceededException may be thrown.
If a shard no longer exists (for example, as a result of updating the number of shards), the method returns an iterator for the last message in the shard.
There is a limit of five transactions per second per open shard when using GetShardIterator.
Request
The request contains data in JSON format.
{
"ShardId": "string",
"ShardIteratorType": "string",
"StartingSequenceNumber": "string",
"StreamName": "string",
"Timestamp": number
}
Request parameters
| Parameter | Description |
|---|---|
ShardId |
The ID of the shard that the iterator is requested for. Type: String. Size: 1-128 characters.Possible values: [a-zA-Z0-9_.-]+.Required: Yes. |
ShardIteratorType |
The type of shard iterator. Type: ShardIteratorType. Possible values:
|
StartingSequenceNumber |
The sequence number of a message. Used with the AT_SEQUENCE_NUMBER or AFTER_SEQUENCE_NUMBER iterator type.Type: String. Size: 1-256 characters.Required: No. |
StreamName |
The name of a stream. Type: String. Size: 1-128 characters.Possible values: Lowercase Latin letters, numbers, and hyphens (the first character must be a letter and the last character can't be a hyphen). Required: No. |
Timestamp |
The timestamp of writing the message to start sequential reads from. Used with the AT_TIMESTAMP iterator type.Type: Integer. |
Response
If successful, HTTP code 200 and data in JSON format are returned.
{
"Iterator": "string"
}
Response parameters
| Parameter | Description |
|---|---|
Iterator |
The position in a shard to start sequential message reads from. The iterator value is defined by the message sequence number in a shard. Type: String Size: 1-512 characters.Required: Yes |
Errors
| Parameter | Description | HTTP code |
|---|---|---|
InvalidArgumentException |
The argument is invalid. For more information, see the error message. | 400 |
ProvisionedThroughputExceededException |
Insufficient throughput to execute the request. | 400 |
ResourceNotFoundException |
The requested resource was not found. | 400 |
Errors that are common to all methods may occur.