Пагинация
Как получить длинный список по частям и не пропустить записи. Размер страницы, смещение offset и продолжение по курсору before.
На этой странице
Длинные списки, например клиенты или сообщения, API возвращает частями, страницами. Загрузка следующих страниц называется пагинацией. Так программе не нужно получать всю историю за один запрос.
Есть два способа указать продолжение: пропустить уже прочитанное число записей (смещение) или передать указатель на последнее прочитанное место (курсор). Способ для конкретного адреса API указан в справочнике.
Схема 1: смещение и X-Total-Count
Параметр limit задаёт размер страницы, а offset число записей, которые нужно пропустить. Например, limit=50&offset=100 запрашивает до 50 записей после первых 100. Эти параметры добавляются к адресу запроса после ?:
curl -H "Authorization: Bearer <ПЕРСОНАЛЬНЫЙ_ТОКЕН>" \
"https://ваш-домен/api/bots/BOT_ID/users?limit=50&offset=100"
Общее число записей возвращается в заголовке ответа X-Total-Count. После каждого ответа увеличивайте offset на число фактически полученных записей, пока offset меньше значения X-Total-Count. Тело ответа: массив элементов текущей страницы.
У смещения есть потолок
Листать «пока offset меньше X-Total-Count» можно не бесконечно. offset больше 100 000 отклоняется с 400: на любом эндпоинте, где смещение вообще принимается. Ответ прямо говорит, что делать: сузить фильтр или взять курсорную схему.
Большое смещение создаёт нагрузку на базу: ей приходится обработать пропущенные строки ради следующей страницы. Поэтому для больших списков используйте фильтры, курсор или экспорт.
Если список длиннее 100 000 записей, к концу его смещением не дойти. Варианты:
- сузить выборку фильтрами эндпоинта (период, канал, статус): обычно этого достаточно;
- перейти на курсор, если эндпоинт его поддерживает (схема 2 ниже; например списки платежей и записей коллекций умеют обе схемы);
- если нужен весь массив данных целиком: используйте экспорт соответствующего раздела, а не постраничный обход.
У размера страницы потолок свой у каждого эндпоинта
Единого максимума для limit нет: у разных списков он разный: встречаются 200, 500 и 1000. Точное значение указано на странице эндпоинта в справочнике.
Ведут себя эндпоинты при слишком большом limit тоже по-разному, и это важнее самих чисел:
- одни отклоняют запрос с
400и текстом вида «limit must be at most 500, got 5000»; - другие молча берут значение по умолчанию (обычно 100) и возвращают страницу меньше запрошенной.
Отсюда практическое правило: никогда не считайте, что вы получили страницу того размера, который просили. Смотрите на длину полученного массива, а не на свой limit, и сдвигайте offset ровно на число фактически полученных элементов. Иначе на эндпоинте со вторым поведением вы будете сдвигаться на 5000 при 100 полученных и пропустите 98 % данных, не увидев ни одной ошибки.
По той же причине не считайте пустую страницу единственным признаком конца: ориентируйтесь на X-Total-Count и на фактическое число элементов вместе.
Схема 2: курсор before и has_more
Курсорная пагинация для лент, упорядоченных по времени (например, сообщения диалога). Запрос принимает limit и необязательный курсор before: идентификатор или метку последнего уже полученного элемента:
curl -H "Authorization: Bearer <ПЕРСОНАЛЬНЫЙ_ТОКЕН>" \
"https://ваш-домен/api/bots/BOT_ID/users/USER_ID/dialog?limit=50&before=CURSOR"
Ответ содержит страницу элементов и флаг has_more. Пока has_more равно true, повторяйте запрос, передавая в before курсор последнего полученного элемента. Когда has_more станет false, вы получите последнюю страницу.
Какую схему выбирать
Вы не выбираете схему: её задаёт эндпоинт. Списки-справочники обычно используют смещение и X-Total-Count; ленты по времени: курсор before и has_more. Всегда сверяйтесь со страницей эндпоинта в справочнике.
Что дальше
- Быстрый старт API: первые запросы.
- Ошибки: коды состояния.
- Лимиты и размеры: ограничения запросов.