Skip to main content
Каждая конечная точка списка /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 по-прежнему отражают фактический остаток Когорты.
Выполните аутентификацию с помощью любого из двух вариантов учётных данных Basic — см. Краткое руководство (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
Чтобы изменить фильтры, начните новый обход с первой страницы.
Обращайтесь с page_token как с непрозрачной строкой: передавайте её обратно в точности в том виде, в котором она получена. Не декодируйте токены, не храните их длительное время и не создавайте их самостоятельно — их внутренний формат может измениться в любой момент без предупреждения.
Конечные точки списков отклоняют неподдерживаемые ими параметры запроса, возвращая 400 invalid_request с указанием названия параметра. Поддерживаемые фильтры см. в справочнике по каждой конечной точке.

Обработка прерванной или изменяющейся коллекции

Эти примеры не выполняют автоматические повторные попытки при ошибках. Для 429 учитывайте Retry-After и следуйте ограниченным рекомендациям по повторным попыткам. При повторной попытке чтения сохраняйте тот же регион, служебную учётную запись, версию, фильтры и токен последней успешно обработанной страницы. Смена учётных данных не предоставляет доступа: при каждом запросе текущие разрешения проверяются заново. Чтение нескольких страниц не является моментальным снимком коллекции. Строки могут изменяться в процессе обхода. Обрабатывайте ресурсы по их стабильному id и делайте последующие операции записи идемпотентными; после перезапуска строка может быть возвращена повторно. Если токен отклонён, изучите ошибку page_token и исправьте запрос, прежде чем начинать заново с первой страницы. Не отбрасывайте молча ранее обработанные данные и не помечайте прерванный экспорт как завершённый. Для получения точных итоговых значений в отчётах используйте соответствующий ресурс отчётности, а не считайте обход живого списка моментальным снимком.