Skip to main content
Każdy punkt końcowy listy /v1 zwraca tę samą kopertę i stosuje ten sam sposób paginacji: oparty na tokenach, tylko do przodu.

Koperta listy

string
Zawsze "list".
array
Strona zasobów w stałej, deterministycznej kolejności.
string | null
Przekaż tę wartość jako page_token w następnym żądaniu, aby pobrać kolejną stronę. null, gdy nie ma już więcej wyników.
boolean
Informuje, czy poza bieżącą stroną istnieją kolejne wyniki.

Parametry żądania

integer
domyślnie:"25"
Rozmiar strony. Liczba całkowita z zakresu od 1 do 500. Wartości spoza tego zakresu powodują zwrócenie 400 z kodem invalid_request.
string
Wartość next_page_token z poprzedniej odpowiedzi. Pomiń ją przy pobieraniu pierwszej strony.
Nie ma parametrów przesunięcia (offset), przechodzenia do poprzedniej strony ani dokładnych łącznych liczności. Aby policzyć elementy kolekcji, należy ją przejść w całości.
Wyjątek: GET /v1/cohorts/{id}/members zwraca co najwyżej 50 wierszy na stronę, nawet jeśli zażądano wyższej wartości limit. has_more i next_page_token nadal odzwierciedlają rzeczywistą pozostałą część Kohorty.
Uwierzytelnianie można przeprowadzić za pomocą dowolnej z dwóch postaci poświadczeń Basic — zobacz Szybki start (apikey:secret lub secret:). Ustaw BASE na regionalny host organizacji — zobacz Regiony.

Przechodzenie przez listę

Wczytaj LIVING_SECURITY_API_KEY z menedżera sekretów, tak jak w szybkim starcie. Ten przykład wymaga entity:read; klucz użyty w przewodniku dotyczącym pierwszego żądania może wymagać tego dodatkowego uprawnienia. Zainstaluj requests dla przykładu w Pythonie lub jq dla przykładu w powłoce. Oba przykłady przypinają wersję, nie zmieniają filtrów i odrzucają przekierowania. Zatrzymują się po błędach oraz po 1000 stronach, zamiast zgłaszać częściowe przejście jako zakończone. Limit czasu odczytu w Pythonie ogranicza czas bezczynności, a nie łączny czas trwania zadania; w swojej integracji ustaw limit czasu dla całego zadania. Pobieraj kolejne strony, aż next_page_token przyjmie wartość null. Do odczytów zbiorczych preferuj limit=500, aby objąć kolekcję mniejszą liczbą żądań — zobacz limity żądań.

Zachowaj stałe filtry podczas paginacji

Tokeny stron to nieprzezroczyste, podpisane kursory. Każdy token jest powiązany z organizacją, uwierzytelnionym kontem usługi, wersją kontraktu oraz dokładnym zestawem filtrów żądania, które go wygenerowało. Zmiana któregokolwiek z tych elementów w trakcie przechodzenia — na przykład dodanie filtra type na drugiej stronie — powoduje zwrócenie 400 z kodem invalid_request dla parametru page_token:
400 Invalid request
Aby zmienić filtry, rozpocznij nowe przejście od pierwszej strony.
Traktuj page_token jako nieprzezroczysty ciąg znaków: przekazuj go z powrotem dokładnie w otrzymanej postaci. Nie dekoduj go, nie przechowuj długoterminowo ani nie konstruuj tokenów — ich wewnętrzny format może ulec zmianie w dowolnym momencie bez powiadomienia.
Punkty końcowe list odrzucają nieobsługiwane parametry zapytania, zwracając 400 invalid_request ze wskazaniem nazwy parametru. Obsługiwane filtry sprawdź w dokumentacji referencyjnej każdego punktu końcowego.

Obsługa przerwanej lub zmieniającej się kolekcji

Te przykłady nie ponawiają błędów automatycznie. W przypadku 429 uwzględnij Retry-After i postępuj zgodnie z ograniczonymi wskazówkami dotyczącymi ponawiania. Podczas ponawiania odczytu zachowaj ten sam region, konto usługi, wersję, filtry oraz token ostatniej pomyślnie przetworzonej strony. Zmiana poświadczeń nie przyznaje dostępu: każde żądanie nadal sprawdza bieżące uprawnienia. Odczyt obejmujący wiele stron nie jest migawką kolekcji. Wiersze mogą się zmieniać w trakcie jej przechodzenia. Przetwarzaj zasoby według ich stałego id i zapewnij idempotentność zapisów w systemach docelowych; po ponownym uruchomieniu wiersz może zostać zwrócony ponownie. Jeśli token zostanie odrzucony, sprawdź błąd page_token i popraw żądanie, zanim rozpoczniesz od pierwszej strony. Nie odrzucaj po cichu wcześniej przetworzonych danych ani nie oznaczaj przerwanego eksportu jako zakończonego. Aby uzyskać dokładne sumy raportowe, użyj odpowiedniego zasobu raportowego zamiast traktować przechodzenie przez aktywną listę jak migawkę.