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 |
Могут возникать ошибки, общие для всех методов.