/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.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.apikey:secret o secret:).
Impostare BASE sull’host regionale dell’organizzazione: vedere
Regioni.
Scorrere un elenco
CaricareLIVING_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 filtrotype alla seconda pagina, restituisce un 400 con codice
invalid_request sul parametro page_token:
400 Invalid request
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. Per429, 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.
