Пагинация

Что это такое

Пагинация позволяет получать большие коллекции данных в виде ограниченных ответов. Эндпоинты со списками YCloud используют либо пагинацию по номерам страниц, либо пагинацию по курсору.

Перед началом работы

Ознакомьтесь со справочником по эндпоинту, чтобы узнать поддерживаемые параметры пагинации, фильтры, порядок сортировки и структуру ответа. Не предполагайте, что каждый эндпоинт списка использует одну и ту же стратегию.

Как это работает

Запросите одну страницу, обработайте ее элементы и продолжайте до тех пор, пока ответ не покажет, что следующей страницы нет. Сохраняйте одинаковые фильтры и параметры сортировки на протяжении всего обхода.

Запрос и ответ

Пагинация по номерам страниц

Большинство эндпоинтов списков поддерживают следующие параметры запроса:

Параметр	Описание
`page`	Номер страницы. Начинается с `1`, по умолчанию равен `1`.
`limit`	Количество результатов на странице. Диапазон от `1` до `100`, по умолчанию — `10`.
`includeTotal`	Установите значение `true`, чтобы включить общее количество подходящих элементов.

curl "https://api.ycloud.com/v2/contact/contacts?page=1&limit=100&includeTotal=true" \
  --header "X-API-Key: $YCLOUD_API_KEY"

Ответ со страницей содержит:

{
  "offset": 0,
  "limit": 100,
  "length": 2,
  "total": 2,
  "items": [{ "id": "ITEM_1" }, { "id": "ITEM_2" }]
}

Поле ответа	Значение
`items`	Объекты, возвращенные на этой странице.
`offset`	Начальная позиция с отсчетом от нуля: `(page - 1) * limit`.
`limit`	Запрошенный размер страницы.
`length`	Фактическое количество элементов, равное `items.length` и не превышающее `limit`.
`total`	Общее количество подходящих элементов; возвращается только при `includeTotal=true`. Подсчет может увеличить задержку, поэтому запрашивайте его только при необходимости.

Эндпоинты на основе смещения обычно ограничивают как page, так и limit значением 100, ограничивая обход первыми 10 000 элементами. Проверяйте ограничения каждого эндпоинта и используйте пагинацию по курсору, если она поддерживается и вам требуется больший набор результатов.

Продолжайте запрашивать следующую страницу, пока length равно limit. Остановитесь, когда length станет меньше limit.

Пагинация по курсору

Эндпоинты, возвращающие cursor.after, поддерживают пагинацию по курсору. Передавайте это значение в качестве pageAfter в следующем запросе.

curl "https://api.ycloud.com/v2/unsubscribers?limit=100&pageAfter=id%3Afoo" \
  --header "X-API-Key: $YCLOUD_API_KEY"

Ответ с курсором содержит items, limit, length и, если есть дополнительные результаты, cursor.after. Объект курсора возвращается только теми эндпоинтами, которые поддерживают пагинацию по курсору.

{
  "items": [{ "id": "ITEM_1" }],
  "limit": 1,
  "length": 1,
  "cursor": { "after": "id:foo" }
}

Передавайте возвращенный курсор в следующий запрос без изменений. Относитесь к нему как к непрозрачному значению; не изменяйте его и не сохраняйте в качестве постоянного идентификатора в приложении. Остановитесь, когда length примет значение 0 или ответ больше не будет содержать cursor.after.

Параметры пагинации и фильтрации различаются в зависимости от эндпоинта. Перед реализацией операции получения списка обратитесь к справочнику API.

Чек-лист по реализации

Указывайте явное значение limit, а не полагайтесь на значение по умолчанию.
Сохраняйте фильтры между запросами страниц.
Останавливайтесь по условию в ответе, а не по предполагаемому количеству страниц.
Обрабатывайте пустую первую страницу как успешный результат.
Добавьте ограничение на максимальное количество страниц или элементов для фоновых задач.

Начало работы

Руководства

Конечные точки

Webhooks

Что это такое

Перед началом работы

Как это работает

Запрос и ответ

Пагинация по номерам страниц

Пагинация по курсору

Чек-лист по реализации

​Что это такое

​Перед началом работы

​Как это работает

​Запрос и ответ

​Пагинация по номерам страниц

​Пагинация по курсору

​Чек-лист по реализации

Что это такое

Перед началом работы

Как это работает

Запрос и ответ

Пагинация по номерам страниц

Пагинация по курсору

Чек-лист по реализации