База знаний GetMyBot

Пагинация

Две схемы листания списков в GetMyBot API: смещение с X-Total-Count и курсор before с has_more, потолки limit и offset.

На этой странице

Списочные эндпоинты API возвращают данные постранично. В платформе исторически сложились две схемы пагинации; конкретная схема указана у эндпоинта в интерактивном справочнике.

Схема 1: смещение и X-Total-Count

Классическая пагинация по смещению. Запрос принимает query-параметры limit (размер страницы) и offset (сколько записей пропустить):

curl -H "Authorization: Bearer mbp_ВАШ_ТОКЕН" "https://ваш-домен/api/bots/BOT_ID/users?limit=50&offset=100"

Общее число записей возвращается в заголовке ответа X-Total-Count. По нему вычисляется число страниц: листайте, увеличивая offset на limit, пока offset меньше значения X-Total-Count. Тело ответа: массив элементов текущей страницы.

У смещения есть потолок

Листать «пока offset меньше X-Total-Count» можно не бесконечно. offset больше 100 000 отклоняется с 400: на любом эндпоинте, где смещение вообще принимается. Ответ прямо говорит, что делать: сузить фильтр или взять курсорную схему.

Это не защита от опечатки, а защита базы: смещение заставляет её построить и выбросить все пропущенные строки, поэтому offset=5000000 требует полного прохода по таблице ради одной страницы.

Если список длиннее 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 mbp_ВАШ_ТОКЕН" "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. Всегда сверяйтесь со страницей эндпоинта в справочнике.

Что дальше