Skip to main content
Jokainen /v1-luettelopäätepiste palauttaa saman vastausrakenteen ja sivuttaa tulokset samalla tavalla: tokenipohjaisesti ja vain eteenpäin.

Luettelon vastausrakenne

string
Aina "list".
array
Resurssien sivu vakaassa, deterministisessä järjestyksessä.
string | null
Välitä tämä arvona page_token seuraavassa pyynnössä, jotta saat seuraavan sivun. null, kun tuloksia ei ole enää jäljellä.
boolean
Kertoo, onko tämän sivun jälkeen vielä lisää tuloksia.

Pyyntöparametrit

integer
oletus:"25"
Sivun koko. Kokonaisluku väliltä 1–500. Tämän alueen ulkopuoliset arvot palauttavat virheen 400 koodilla invalid_request.
string
Edellisen vastauksen arvo next_page_token. Jätä pois ensimmäisen sivun yhteydessä.
Siirtymäparametreja (offset), paluuta edelliselle sivulle tai tarkkoja kokonaismääriä ei ole. Jos haluat laskea kokoelman alkiot, käy kokoelma läpi.
Poikkeus: GET /v1/cohorts/{id}/members palauttaa enintään 50 riviä sivua kohden, vaikka pyytäisit suuremman arvon limit. has_more ja next_page_token kuvaavat silti Kohortin todellista jäljellä olevaa osuutta.
Todennus onnistuu kummalla tahansa Basic-tunnistetietomuodolla – katso Pikaopas (apikey:secret tai secret:). Aseta BASE organisaation alueelliseksi isännäksi – katso Alueet.

Luettelon läpikäynti

Lataa LIVING_SECURITY_API_KEY salaisuuksienhallinnastasi pikaoppaan tavoin. Tämä esimerkki edellyttää entity:read. Ensimmäisen pyynnön oppaassa käytetty avain saattaa tarvita tämän lisäoikeuden. Asenna requests Pythonia varten tai jq komentoriviesimerkkiä varten. Molemmat esimerkit kiinnittävät version, pitävät suodattimet muuttumattomina ja hylkäävät uudelleenohjaukset. Ne pysähtyvät virheisiin ja 1 000 sivun jälkeen sen sijaan, että raportoisivat osittaisen läpikäynnin valmiiksi. Pythonin lukuaikakatkaisu rajaa toimettomuusaikaa, ei työn kokonaiskestoa; aseta integraatiossasi työlle määräaika. Pyydä sivuja, kunnes next_page_token on null. Käytä mieluiten arvoa limit=500 massalukuihin, jolloin kokoelma katetaan pienemmällä pyyntömäärällä – katso käyttörajat.

Pidä suodattimet muuttumattomina sivutuksen aikana

Sivutokenit ovat läpinäkyviä, allekirjoitettuja kursoreita. Jokainen token on sidottu organisaatioon, todennettuun palvelutiliin, rajapintasopimuksen versioon ja täsmälleen sen pyynnön suodatinjoukkoon, joka sen tuotti. Jos muutat mitä tahansa näistä kesken läpikäynnin – esimerkiksi lisäät type-suodattimen toisella sivulla – saat vastauksena 400 koodilla invalid_request parametrissa page_token:
400 Invalid request
Jos haluat muuttaa suodattimia, aloita uusi läpikäynti ensimmäiseltä sivulta.
Käsittele arvoa page_token läpinäkyvänä merkkijonona: välitä se takaisin täsmälleen sellaisena kuin sait sen. Älä pura, säilytä pitkäaikaisesti tai muodosta tokeneita itse – niiden sisäinen muoto voi muuttua milloin tahansa ilman ilmoitusta.
Luettelopäätepisteet hylkäävät tukemattomat kyselyparametrit vastauksella 400 invalid_request, jossa parametri mainitaan nimeltä. Tarkista tuetut suodattimet kunkin päätepisteen viitedokumentaatiosta.

Keskeytyneen tai muuttuvan kokoelman käsittely

Nämä esimerkit eivät yritä virheitä automaattisesti uudelleen. Noudata virheen 429 yhteydessä otsaketta Retry-After ja seuraa rajattua uudelleenyrityksiä koskevaa ohjeistusta. Käytä lukua uudelleen yritettäessä samaa aluetta, palvelutiliä, versiota ja suodattimia sekä viimeisintä onnistuneesti käsiteltyä sivutokenia. Tunnistetietojen vaihtaminen ei myönnä käyttöoikeutta: jokaisessa pyynnössä tarkistetaan edelleen voimassa olevat käyttöoikeudet. Usean sivun luku ei ole kokoelman tilannekuva. Rivit voivat muuttua läpikäynnin aikana. Käsittele resursseja niiden vakaan tunnisteen id perusteella ja tee jatkokirjoituksista idempotentteja; uudelleenkäynnistys voi palauttaa saman rivin uudelleen. Jos token hylätään, tarkista virhe page_token ja korjaa pyyntö ennen kuin aloitat alusta ensimmäiseltä sivulta. Älä hylkää aiemmin käsiteltyjä tietoja huomaamatta äläkä merkitse keskeytynyttä vientiä valmiiksi. Jos tarvitset tarkat raportoinnin kokonaismäärät, käytä asianmukaista raportointiresurssia sen sijaan, että pitäisit live-luettelon läpikäyntiä tilannekuvana.