Skip to main content
Ogni endpoint di elenco /v1 restituisce lo stesso envelope ed esegue la paginazione nello stesso modo: basata su token e solo in avanti.

L’envelope di elenco

string
Sempre "list".
array
La pagina di risorse, in un ordine stabile e deterministico.
string | null
Passare questo valore come page_token nella richiesta successiva per ottenere la pagina seguente. null quando non ci sono altri risultati.
boolean
Indica se esistono ulteriori risultati oltre questa pagina.

Parametri della richiesta

integer
predefinito:"25"
Dimensione della pagina. Un numero intero compreso tra 1 e 500. I valori al di fuori di tale intervallo restituiscono un 400 con codice invalid_request.
string
Il valore next_page_token della risposta precedente. Omettere per la prima pagina.
Non sono presenti parametri di offset, né la possibilità di tornare alla pagina precedente, né conteggi totali esatti. Per contare una raccolta, è necessario scorrerla.
Eccezione: GET /v1/cohorts/{id}/members restituisce al massimo 50 righe per pagina, anche se si richiede un valore limit più alto. has_more e next_page_token riflettono comunque il resto effettivo della Coorte.
Eseguire l’autenticazione con una qualsiasi delle due forme di credenziali Basic: vedere Guida introduttiva (apikey:secret o secret:). Impostare BASE sull’host regionale dell’organizzazione: vedere Regioni.

Scorrere un elenco

Caricare LIVING_SECURITY_API_KEY dal proprio secret manager come nella guida introduttiva. Questo esempio richiede entity:read; la chiave utilizzata per la guida alla prima richiesta potrebbe richiedere questa autorizzazione aggiuntiva. Installare requests per Python o jq per l’esempio shell. Entrambi gli esempi fissano una versione, mantengono invariati i filtri e rifiutano i reindirizzamenti. Si interrompono in caso di errori e dopo 1.000 pagine, anziché segnalare come completo un scorrimento parziale. Il timeout di lettura di Python limita l’inattività, non la durata totale del processo; impostare una scadenza del processo nella propria integrazione. Richiedere le pagine finché next_page_token non è null. Preferire limit=500 per le letture in blocco, in modo da coprire la raccolta con meno richieste: vedere limiti di frequenza.

Mantenere stabili i filtri durante la paginazione

I token di pagina sono cursori opachi e firmati. Ogni token è associato all’organizzazione, all’account di servizio autenticato, alla versione del contratto e all’esatto insieme di filtri della richiesta che lo ha generato. La modifica di uno di questi elementi durante lo scorrimento, ad esempio l’aggiunta di un filtro type alla seconda pagina, restituisce un 400 con codice invalid_request sul parametro page_token:
400 Invalid request
Per modificare i filtri, avviare un nuovo scorrimento dalla prima pagina.
Trattare page_token come una stringa opaca: restituirla esattamente come ricevuta. Non decodificare i token, non conservarli a lungo termine e non costruirli: il loro formato interno può cambiare in qualsiasi momento senza preavviso.
Gli endpoint di elenco rifiutano i parametri di query che non supportano con un 400 invalid_request che indica il nome del parametro. Consultare il riferimento di ciascun endpoint per i filtri supportati.

Gestire una raccolta interrotta o soggetta a modifiche

Questi esempi non ripetono automaticamente gli errori. Per 429, rispettare Retry-After e seguire le indicazioni sui tentativi ripetuti con limiti definiti. Mantenere la stessa regione, lo stesso account di servizio, la stessa versione, gli stessi filtri e l’ultimo token di pagina elaborato con successo quando si ripete una lettura. Cambiare le credenziali non concede l’accesso: ogni richiesta verifica comunque le autorizzazioni correnti. Una lettura su più pagine non è un’istantanea della raccolta. Le righe possono cambiare mentre le si scorre. Elaborare le risorse in base al loro id stabile e rendere idempotenti le scritture a valle; un riavvio può restituire nuovamente una riga. Se un token viene rifiutato, esaminare l’errore page_token e correggere la richiesta prima di ricominciare dalla prima pagina. Non scartare silenziosamente i dati già elaborati e non contrassegnare come completa un’esportazione interrotta. Per totali di reportistica esatti, utilizzare la risorsa di reportistica appropriata anziché considerare uno scorrimento di un elenco in tempo reale come un’istantanea.