[Документация Yandex Cloud](../../../index.md) > [Yandex Data Streams](../../index.md) > [HTTP API, совместимый с Amazon Kinesis Data Streams](../index.md) > Методы > GetShardIterator

# GetShardIterator

Возвращает итератор [сегмента](../../concepts/glossary.md#shard) потока.

Время жизни итератора истекает через 5 минут после получения.

Итератор задает позицию в сегменте, с которой будет начато чтение последовательности [сообщений](../../concepts/glossary.md#message) методом [GetRecords](getrecords.md). Позиция указывается с использованием [порядкового номера](../../concepts/glossary.md#sequence-number) сообщения в сегменте.

В запросе необходимо указать тип итератора.

Например, чтобы получить итератор для чтения последовательности начиная с сообщения с определенным порядковым номером, необходимо указать тип итератора `AT_SEQUENCE_NUMBER` и номер сообщения в параметре `StartingSequenceNumber`. Тип итератора `AFTER_SEQUENCE_NUMBER` вернет значение для чтения последовательности начиная с сообщения, следующего за указанным в параметре `StartingSequenceNumber`. Используются порядковые номера, которые возвращаются при вызовах методов [PutRecord](putrecord.md), [PutRecords](putrecords.md), [GetRecords](getrecords.md) и [DescribeStream](deletestream.md).

Чтобы получить итератор для чтения последовательности начиная с определенного момента времени, нужно указать тип итератора `AT_TIMESTAMP` и время в параметре `Timestamp`.

Тип итератора `TRIM_HORIZON` позволяет прочитать последовательность начиная с самой старой записи в сегменте, `LATEST` — самые новые данные в сегменте.

При циклическом чтении сообщений из потока с помощью `GetRecords` нужно использовать `GetShardIterator`, чтобы получить итератор сегмента для использования в первом запросе `GetRecords`. Для последующих чтений можно использовать значение `NextShardIterator`, которое возвращается в ответе `GetRecords`.

Слишком частые вызовы метода `GetShardIterator` могут вызвать ошибку `ProvisionedThroughputExceededException`.

Если сегмент перестал существовать (например, в результате обновления [количества сегментов](updateshardcount.md)), метод возвращает итератор для последнего сообщения в сегменте.

Для `GetShardIterator` есть ограничение в пять транзакций в секунду на каждый открытый сегмент.

## Запрос {#request}

Запрос содержит данные в формате JSON.

```json
{
  "ShardId": "string",
  "ShardIteratorType": "string",
  "StartingSequenceNumber": "string",
  "StreamName": "string",
  "Timestamp": number
}
```

### Параметры запроса {#request-options}

Параметр | Описание
----- | -----
`ShardId` | Идентификатор сегмента, для которого запрашивается итератор.<br/><br/>**Тип**: Строка.<br/>**Размер**: `1`-`128` символов.<br/>**Возможные значения**: `[a-zA-Z0-9_.-]+`.<br/>**Обязательный**: Да.
`ShardIteratorType` | Тип итератора сегмента.<br/><br/>**Тип**: ShardIteratorType.<br/>**Возможные значения**:<ul><li>`AT_SEQUENCE_NUMBER` — указывает на сообщение с заданным в `StartingSequenceNumber` номером;</li><li>`AFTER_SEQUENCE_NUMBER` — указывает на сообщение, следующее за заданным в `StartingSequenceNumber`;</li><li>`AT_TIMESTAMP` — указывает на сообщение, для которого установлено время;</li><li>`TRIM_HORIZON` — указывает на самое старое сообщение в сегменте;</li><li>`LATEST` — указывает на самое новое сообщение в сегменте.</li></ul>**Обязательный**: Да.
`StartingSequenceNumber` | Порядковый номер сообщения.<br/>Используется с типом итератора `AT_SEQUENCE_NUMBER` или `AFTER_SEQUENCE_NUMBER`.<br/><br/>**Тип**: Строка.<br/>**Размер**: `1`-`256` символов.<br/>**Обязательный**: Нет.
`StreamName` | Имя потока данных.<br/><br/>**Тип**: Строка.<br/>**Размер**: `1`-`128` символов.<br/>**Возможные значения**: строчные буквы латинского алфавита, цифры и дефисы; первый символ — буква; последний символ — не дефис.<br/>**Обязательный**: Нет.
`Timestamp` | Отметка времени записи сообщения, с которого будет начато последовательное чтение.<br/>Используется с типом итератора `AT_TIMESTAMP`.<br/><br/>**Тип**: Целое число.

## Ответ {#response}

В случае успеха возвращаются HTTP-ответ с кодом 200 и данные в формате JSON.

```json
{
  "Iterator": "string"
}
```

### Параметры ответа {#response-options}

Параметр | Описание
----- | -----
`Iterator` | Позиция в сегменте, с которой будет начато последовательное чтение сообщений. Значение итератора определяется порядковым номером сообщения в сегменте.<br/><br/>**Тип**: Строка<br/>**Размер**: `1`-`512` символов.<br/>**Обязательный**: Да

## Ошибки {#errors}

Параметр | Описание | Код HTTP
----- | ----- | -----
`InvalidArgumentException` | Недопустимый аргумент. Дополнительные сведения смотрите в сообщении об ошибке. | 400
`ProvisionedThroughputExceededException` | Недостаточно пропускной способности для выполнения запроса. | 400
`ResourceNotFoundException` | Запрошенный ресурс не найден. | 400

Могут возникать [ошибки](../common-errors.md), общие для всех методов.