/v1 повертає однакову обгортку й використовує однакову
пагінацію: на основі токенів, лише вперед.
Обгортка списку
string
Завжди
"list".array
Сторінка ресурсів у стабільному, детермінованому порядку.
string | null
Передайте це значення як
page_token у наступному запиті, щоб отримати наступну сторінку.
null, якщо результатів більше немає.boolean
Чи існують результати за межами цієї сторінки.
Параметри запиту
integer
за замовчуванням:"25"
Розмір сторінки. Ціле число від 1 до 500. Значення поза цим діапазоном повертають
400 із кодом invalid_request.string
next_page_token з попередньої відповіді. Для першої сторінки пропустіть його.Виняток:
GET /v1/cohorts/{id}/members повертає щонайбільше 50 рядків на
сторінку, навіть якщо ви запитуєте більше значення limit. has_more і
next_page_token усе одно відображають справжній залишок Cohort.apikey:secret або secret:).
Установіть для BASE регіональний хост організації — див.
Regions.
Обхід списку
ЗавантажтеLIVING_SECURITY_API_KEY зі свого сховища секретів, як у кроках швидкого старту.
Для цього прикладу потрібен entity:read; ключу, який використовувався в посібнику з першого запиту,
може знадобитися цей додатковий дозвіл. Установіть requests для Python або jq для прикладу
в оболонці. В обох прикладах зафіксовано версію, фільтри залишаються незмінними, а
перенаправлення відхиляються. Вони зупиняються у разі помилок і після 1 000 сторінок, а не
повідомляють про неповний обхід як про завершений. Тайм-аут читання в Python обмежує
час бездіяльності, а не загальну тривалість завдання; установіть у своїй інтеграції
граничний термін виконання завдання.
Запитуйте сторінки, доки next_page_token не матиме значення null. Для масового
читання віддавайте перевагу limit=500, щоб охопити колекцію меншою кількістю запитів — див.
rate limits.
Зберігайте фільтри стабільними під час пагінації
Токени сторінок — це непрозорі підписані курсори. Кожен токен прив’язаний до організації, автентифікованого службового облікового запису, версії контракту та точного набору фільтрів запиту, що його створив. Зміна будь-якого з цих елементів під час обходу — наприклад, додавання фільтраtype на другій сторінці — повертає 400 із кодом
invalid_request для параметра page_token:
400 Invalid request
Кінцеві точки списків відхиляють непідтримувані параметри запиту, повертаючи
400
invalid_request із назвою параметра. Підтримувані фільтри дивіться в довідці
кожної кінцевої точки.Обробка перерваної або змінюваної колекції
Ці приклади не повторюють запити автоматично у разі помилок. Для429 дотримуйтеся Retry-After
і настанов щодо обмежених повторів. Під час повторення читання зберігайте
той самий регіон, службовий обліковий запис, версію, фільтри та токен
останньої успішно опрацьованої сторінки. Зміна облікових даних не надає доступу:
кожен запит і надалі перевіряє поточні дозволи.
Читання кількох сторінок не є знімком колекції. Рядки можуть змінюватися, поки
ви її обходите. Обробляйте ресурси за їхнім стабільним id і робіть подальші
записи ідемпотентними; після перезапуску рядок може повернутися знову. Якщо токен відхилено,
перегляньте помилку page_token і виправте запит, перш ніж перезапускати з
першої сторінки. Не відкидайте мовчки раніше оброблені дані та не позначайте
перерваний експорт як завершений. Для точних підсумків звітності використовуйте відповідний
ресурс звітності замість того, щоб розглядати обхід живого списку як знімок.
