/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 по-прежнему отражают фактический остаток Когорты.apikey:secret или secret:).
Укажите в BASE региональный хост организации — см.
Регионы.
Обход списка
ЗагрузитеLIVING_SECURITY_API_KEY из вашего менеджера секретов, как показано в кратком руководстве.
Для этого примера требуется entity:read; ключу, использованному в руководстве по первому запросу,
может потребоваться это дополнительное разрешение. Установите requests для Python или jq для примера
на shell. В обоих примерах зафиксирована версия, фильтры остаются неизменными, а перенаправления
отклоняются. Они останавливаются при ошибках и после 1000 страниц, а не сообщают о
частичном обходе как о завершённом. Тайм-аут чтения в Python ограничивает время бездействия, а не общую
длительность задания; задайте предельный срок выполнения задания в вашей интеграции.
Запрашивайте страницы, пока next_page_token не станет null. Для массового
чтения предпочтительнее использовать limit=500, чтобы охватить коллекцию за меньшее число запросов — см.
ограничения частоты запросов.
Сохраняйте фильтры неизменными при постраничной навигации
Токены страниц — это непрозрачные подписанные курсоры. Каждый токен привязан к организации, аутентифицированной служебной учётной записи, версии контракта и точному набору фильтров запроса, в ответ на который он был выдан. Изменение любого из этих параметров в процессе обхода, например добавление фильтраtype на второй странице, приводит к возврату 400 с кодом
invalid_request для параметра page_token:
400 Invalid request
Конечные точки списков отклоняют неподдерживаемые ими параметры запроса, возвращая
400
invalid_request с указанием названия параметра. Поддерживаемые фильтры см. в справочнике по каждой
конечной точке.Обработка прерванной или изменяющейся коллекции
Эти примеры не выполняют автоматические повторные попытки при ошибках. Для429 учитывайте Retry-After
и следуйте ограниченным рекомендациям по повторным попыткам. При повторной попытке чтения сохраняйте
тот же регион, служебную учётную запись, версию, фильтры и токен последней успешно обработанной
страницы. Смена учётных данных не предоставляет доступа:
при каждом запросе текущие разрешения проверяются заново.
Чтение нескольких страниц не является моментальным снимком коллекции. Строки могут изменяться
в процессе обхода. Обрабатывайте ресурсы по их стабильному id и делайте последующие
операции записи идемпотентными; после перезапуска строка может быть возвращена повторно. Если токен отклонён,
изучите ошибку page_token и исправьте запрос, прежде чем начинать заново
с первой страницы. Не отбрасывайте молча ранее обработанные данные и не помечайте
прерванный экспорт как завершённый. Для получения точных итоговых значений в отчётах используйте соответствующий
ресурс отчётности, а не считайте обход живого списка моментальным снимком.
