GetShardIterator
Возвращает итератор сегмента потока.
Время жизни итератора истекает через 5 минут после получения.
Итератор задает позицию в сегменте, с которой будет начато чтение последовательности сообщений методом GetRecords. Позиция указывается с использованием порядкового номера сообщения в сегменте.
В запросе необходимо указать тип итератора.
Например, чтобы получить итератор для чтения последовательности начиная с сообщения с определенным порядковым номером, необходимо указать тип итератора AT_SEQUENCE_NUMBER
и номер сообщения в параметре StartingSequenceNumber
. Тип итератора AFTER_SEQUENCE_NUMBER
вернет значение для чтения последовательности начиная с сообщения, следующего за указанным в параметре StartingSequenceNumber
. Используются порядковые номера, которые возвращаются при вызовах методов PutRecord, PutRecords, GetRecords и DescribeStream.
Чтобы получить итератор для чтения последовательности начиная с определенного момента времени, нужно указать тип итератора AT_TIMESTAMP
и время в параметре Timestamp
.
Тип итератора TRIM_HORIZON
позволяет прочитать последовательность начиная с самой старой записи в сегменте, LATEST
— самые новые данные в сегменте.
При циклическом чтении сообщений из потока с помощью GetRecords
нужно использовать GetShardIterator
, чтобы получить итератор сегмента для использования в первом запросе GetRecords
. Для последующих чтений можно использовать значение NextShardIterator
, которое возвращается в ответе GetRecords
.
Слишком частые вызовы метода GetShardIterator
могут вызвать ошибку ProvisionedThroughputExceededException
.
Если сегмент перестал существовать (например, в результате обновления количества сегментов), метод возвращает итератор для последнего сообщения в сегменте.
Для GetShardIterator
есть ограничение в пять транзакций в секунду на каждый открытый сегмент.
Запрос
Запрос содержит данные в формате JSON.
{
"ShardId": "string",
"ShardIteratorType": "string",
"StartingSequenceNumber": "string",
"StreamName": "string",
"Timestamp": number
}
Параметры запроса
Параметр | Описание |
---|---|
ShardId |
Идентификатор сегмента, для которого запрашивается итератор. Тип: Строка. Размер: 1 -128 символов.Возможные значения: [a-zA-Z0-9_.-]+ .Обязательный: Да. |
ShardIteratorType |
Тип итератора сегмента. Тип: ShardIteratorType. Возможные значения:
|
StartingSequenceNumber |
Порядковый номер сообщения. Используется с типом итератора AT_SEQUENCE_NUMBER или AFTER_SEQUENCE_NUMBER .Тип: Строка. Размер: 1 -256 символов.Обязательный: Нет. |
StreamName |
Имя потока данных. Тип: Строка. Размер: 1 -128 символов.Возможные значения: строчные буквы латинского алфавита, цифры и дефисы; первый символ — буква; последний символ — не дефис. Обязательный: Нет. |
Timestamp |
Отметка времени записи сообщения, с которого будет начато последовательное чтение. Используется с типом итератора AT_TIMESTAMP .Тип: Целое число. |
Ответ
В случае успеха возвращаются HTTP-ответ с кодом 200 и данные в формате JSON.
{
"Iterator": "string"
}
Параметры ответа
Параметр | Описание |
---|---|
Iterator |
Позиция в сегменте, с которой будет начато последовательное чтение сообщений. Значение итератора определяется порядковым номером сообщения в сегменте. Тип: Строка Размер: 1 -512 символов.Обязательный: Да |
Ошибки
Параметр | Описание | Код HTTP |
---|---|---|
InvalidArgumentException |
Недопустимый аргумент. Дополнительные сведения смотрите в сообщении об ошибке. | 400 |
ProvisionedThroughputExceededException |
Недостаточно пропускной способности для выполнения запроса. | 400 |
ResourceNotFoundException |
Запрошенный ресурс не найден. | 400 |
Могут возникать ошибки, общие для всех методов.