Пагинация API: границы страниц и полнота данных
Автор: Ai Flowi · Опубликовано
Пагинация API разбивает коллекцию на небольшие ответы и определяет, как вызывающая сторона запрашивает следующую часть. Чтобы собрать результат, сохраняйте границы каждой страницы, следуйте правилу продолжения из контракта и проверяйте явно заданное условие завершения. Успешный первый ответ подтверждает лишь результат этой страницы, а не получение всей коллекции.
Полнота определяется в рамках выбранного фильтра, порядка сортировки, прав доступа и версии коллекции. Последовательность страниц может завершиться корректно, но не включать записи, к которым у вызывающей стороны нет доступа. Если коллекция меняется во время обхода, даже непрерывная последовательность может не соответствовать единому согласованному снимку данных.
Чем пагинация со смещением отличается от курсорной пагинации?
Пагинация со смещением запрашивает позицию в упорядоченном результате, обычно вместе с размером страницы. Курсорная пагинация запрашивает позицию продолжения, представленную значением, которое предоставляет сервис. Обеим нужен контракт, описывающий порядок, завершение и поведение при изменении исходных записей.
| Способ | Что сохраняет вызывающая сторона | Существенная неопределённость |
|---|---|---|
| Смещение | Запрошенную позицию, размер, фильтр и порядок сортировки | Вставка или удаление записей до этой позиции может сдвинуть последующие записи. |
| Курсор | Полученное значение продолжения и связанный с ним запрос | Сам по себе курсор не гарантирует фиксированный снимок, бессрочную действительность или общее число записей. |
Считайте непрозрачный курсор данными, которые нужно передать обратно по указанным правилам. Не увеличивайте его, не трактуйте как номер строки и не используйте с другим фильтром, если API этого не разрешает. Страница с меньшим числом элементов или пустая страница означает конец только тогда, когда это предусмотрено предоставленным контрактом.
Учебный контракт ответа из трёх страниц
Этот вымышленный API чтения возвращает шесть синтетических идентификаторов элементов в фиксированном порядке. Только для этого учебного набора коллекция заморожена, каждая промежуточная страница содержит два элемента, а ожидаемые идентификаторы известны. Поле next_cursor содержит значение для следующего запроса; JSON-значение null явно завершает обход. Отсутствие этого поля означает недопустимый ответ, а не альтернативный сигнал завершения.
{"items":[{"id":"item-A"},{"id":"item-B"}],"next_cursor":"page-two"}
{"items":[{"id":"item-C"},{"id":"item-D"}],"next_cursor":"page-three"}
{"items":[{"id":"item-E"},{"id":"item-F"}],"next_cursor":null}Три объекта — составленные для примера тела ответов, а не ответы из рабочей среды. Начальный запрос не содержит курсора; последующие передают точное значение next_cursor из предыдущего ответа. Значения курсора в виде слов делают пример понятнее; реальный сервис может выдавать значения без понятного человеку смысла.
| Страница | Курсор запроса | Полученные идентификаторы | Возвращённое значение next_cursor | Решение в журнале |
|---|---|---|---|---|
| 1 | Отсутствует: начальный запрос | item-A, item-B | page-two | Сохранить страницу; запросить page-two. |
| 2 | page-two | item-C, item-D | page-three | Сохранить страницу; запросить page-three. |
| 3 | page-three | item-E, item-F | null | Получен маркер конца; сравнить все шесть идентификаторов с учебным набором. |
Сохраняйте для каждой строки ссылку на попытку, результат проверки ответа и время наблюдения. Курсор запроса обозначает границу страницы; отдельная ссылка на попытку позволяет различать повторы на этой границе. Храните чувствительные значения продолжения в материалах с ограниченным доступом, а не в общедоступных журналах.
Выявление повторного курсора, дубликата идентификатора и пропущенной страницы
| Ошибка | Изменённое наблюдение | Что выявляет журнал | Действие |
|---|---|---|---|
| Повторный курсор | Страница 2 снова возвращает page-two | Продолжение запрашивает уже принятую границу. | Остановить обход; отметить отсутствие продвижения. |
| Дубликат идентификатора | Страница 2 содержит item-B и item-D | item-B уже был на странице 1; item-C отсутствует. | Сохранить наблюдения обеих страниц; считать проверку уникальности идентификаторов учебного набора не пройденной. |
| Пропущенная страница | Вызывающая сторона переходит со страницы 1 сразу к page-three | Следующий запрос не соответствует значению продолжения page-two со страницы 1. | Отметить коллекцию как неполную, даже если последняя страница возвращает null. |
Незаметное удаление дубликатов идентификаторов скрывает полезные свидетельства. До любой разрешённой дедупликации сохраняйте исходное число вхождений и страницу происхождения. В этом замороженном примере дубликаты нарушают контракт; в меняющейся коллекции они также могут указывать на перемещение записей между границами. В любом случае одна дедупликация не восстановит пропущенную запись.
Известный набор из шести идентификаторов позволяет независимо проверить полноту. Реальная вызывающая сторона без ожидаемого перечня не может доказать получение всех исходных записей одним лишь подсчётом уникальных идентификаторов. Она может установить, что наблюдаемая последовательность соответствует предоставленному контракту, а затем указать ограничения полноты исходных данных или согласованности снимка.
Определите «полноту» до сбора данных
Принимайте коллекцию только после того, как каждый необходимый ответ прошёл согласованную проверку тела, все указания продолжения выполнены и получено документированное условие завершения. Не меняйте исходный запрос и предоставленную ссылку на снимок. Различайте «обход завершён» и «перечень сверён с независимым источником».
Ограничение числа запросов или срока защищает вызывающую сторону от бесконечного обхода, но достижение такого ограничения не означает успешного завершения. Зафиксируйте частичный результат и следующую необработанную границу. Если срок действия курсора истёк, следуйте правилам перезапуска сервиса; не присоединяйте перезапущенную последовательность к прежним страницам и не называйте эту смесь единым снимком.
При ошибке ответа храните последнюю принятую страницу отдельно от неудачной попытки. Вызывающая сторона, добавляющая записи до проверки тела, может включить в коллекцию недопустимую страницу. Восстановление должно сохранить как идентичность запроса, так и последнюю проверенную границу.
Пагинация в запросе AI Flowi Workflow
Статус: документировано. Поля запроса компонента описаны в документации API Request и документированы в каталоге; не проверены Ai Flowi в рабочей среде
.
пример настройки, а не зафиксированный тест
В сопоставлении полей вымышленного запроса назовите параметр строки запроса cursor и передавайте его в query_params: сначала опустите его, затем указывайте page-two и page-three только после проверки предыдущих тел ответов. Это значения учебного набора, а не варианты из каталога. Поле ответа next_cursor и параметр запроса cursor намеренно имеют разные имена; копирование ключа ответа в качестве ключа запроса нарушит контракт этой вымышленной конечной точки.
После принятия страницы 2 ожидающий запрос — page-three, а сохранённые идентификаторы — от item-A до item-D. Если следующая попытка завершится ошибкой до получения пригодного тела ответа, сохраните эти четыре идентификатора как неполную коллекцию, а page-three — как необработанную границу. Не продвигайте журнал только потому, что запрос отправлен. Если повтор позднее вернёт допустимое тело последней страницы, примите item-E и item-F один раз, затем сверьте перечень из шести идентификаторов. Это ручной разбор учебного набора, а не утверждение о встроенной автоматической пагинации.
Используйте свою учётную запись AI Flowi Workflow и получите у поставщика API необходимые учётную запись или учётные данные; использование внешних сервисов оплачивается отдельно. Приведённые выше примеры тел ответов не были получены через компонент.
Типичные ошибки и связанные термины
- Сохранение первого ответа 200 как полного экспорта.
- Завершение на пустом списке items при наличии действительного значения продолжения.
- Изменение фильтров посреди последовательности без создания новой записи о коллекции.
- Удаление повторных вхождений до проверки непрерывности страниц.
- Объявление коллекции на основе курсора снимком без предоставленной гарантии согласованности.
Не используйте собранный список для сверки, пока не определены его условие завершения, область видимости или требование согласованности. См. интеграцию по API для общего контракта интерфейса, тестирование API для проверки ответов, лимиты запросов API для квоты, расходуемой последовательными запросами, и коды состояния HTTP для значения ответа каждой страницы.