Perusteelliset käytännön oppaat

Kysy julkista APIa ja säilytä todennettava poiminta

Määritä kysely, sivutus, virheet ja raakavastaus ennen tiedon muuntamista.

Päivitetty :

Kannettava ja tabletti esittävät API-vastauksen kaaviota ja ennen tuontia tarkistettavaa riviä. Kuvitteellinen näkymä.

Tekoälyllä luotu kuvitus

Miten poiminta toistetaan liioittelematta kattavuutta?

API vastaa kyselyyn tietyllä rakenteella ja hetkellä. Se ei osoita koko tietokannan kysymistä tai muuttumattomuutta kutsujen välillä. Erota keruun kirjaus analyysistä.

  1. Valitse pääsy

    Lue viralliset ohjeet: versio, rajaus, ehdot, tunnistautuminen ja rajat. Koko tietokantaa varten etsi virallinen vienti.

  2. Aloita pienestä

    Kirjaa endpoint, menetelmä, parametrit, suodatus ja järjestys. Suosi tunnisteita äläkä julkaise avaimia tai tokeneita.

  3. Tarkista vastaus

    Säilytä HTTP-tila, aika, muoto ja virheet. Tarkista kentät ja yksiköt; HTTP 200 voi sisältää tyhjän vastauksen tai toimintavirheen.

  4. Seuraa sivutusta

    Tutki kokonaismäärä, sivut ja kursorit. Laske rivit sekä yksilölliset tunnisteet, kirjaa toistot ja pysäytysehto. Tietokanta voi muuttua keruun aikana.

  5. Säilytä alkuperäinen

    Pidä raakavastaus ja tiiviste; dokumentoi siivous ja muunnokset. Älä julkaise henkilötietoja tai salaisuuksia avoimessa lokissa.

  6. Käsittele muutos

    Noudata uusintapyyntöjen ohjeita 429-tilassa tai katkossa. Uusi poiminta on uusi havainto; vertaa myös rakennetta ja rajausta.

Pienet kyselyesimerkit

Osoitteet näyttävät syntaksin. Tarkista saatavuus, tunnistautuminen ja ehdot dokumentaatiosta.

Tietojen lukemisen työpaja

Uudelleenvarmennuksen loki, ei uusi tyhjä poiminta

DEMO-HTTP-vaihdot ovat kuvitteellisia. Osio ei ota yhteyttä palvelimeen eikä uusi pyyntöjä.

Kuvitteellisia tietoja ja merkintöjä oppimista varten: tulokset eivät ole peräisin suorista palvelukyselyistä.

Erota kopio, varmennus ja pyyntöraja

Skenaarion asiakas säilyttää area=A-esityksen ETag-tunnisteineen. Kuvitteellinen käytäntö rajaa yritykset kahteen eikä takaa palvelun saatavuutta.

  1. Säilytä ensimmäinen kopio

    Kuvitteellinen vaihto
    GET area=A → 200, runko ja ETag "demo-v1"
    Säilytetty tila
    Runko liitetty tarkkaan pyyntöön
    Skenaarion päätös
    Säilytä suodattimet, versio ja esitys yhdessä.
  2. Varmenna sama valinta

    Kuvitteellinen vaihto
    Sama pyyntö ja If-None-Match → 304 ilman runkoa
    Säilytetty tila
    Vastaava kopio on saatavilla
    Skenaarion päätös
    Käytä kopiota, älä kirjaa nollarivistä poimintaa.
  3. Muuta valintaa

    Kuvitteellinen vaihto
    Uusi pyyntö area=B
    Säilytetty tila
    A-kopio ei kuvaa B:tä
    Skenaarion päätös
    Käsittele erikseen, vaikka ETag-teksti näyttää samalta.
  4. Saavuta raja

    Kuvitteellinen vaihto
    429; Retry-After: 15
    Säilytetty tila
    Yritys epäonnistui, ei nollatulos
    Skenaarion päätös
    Odota ohjeen mukaan; kahden yrityksen rajalla pysähdy ja kirjaa.

Mikä loki erottaa keruun tilat oikein?

Avaa jokainen väite ja vertaa sen tulkintaa. Lisätarkistuksia voi silti tarvita.

304: uusi tyhjä valinta

Ei. Skenaario käyttää saman valinnan kopiota. Puuttuvasta rungosta ei tule tyhjää taulukkoa.

Kopioi A:n tiedot B-poimintaan

Ei. Se muuttaa havaintojen rajauksen huomaamatta. Parametrit kuuluvat kirjaukseen.

Säilytä A-kopion viite ja kirjaa rajaan pysähtyminen erikseen

Kyllä. Lokista on tunnistettava käytetyt tiedot ja yritykset, jotka eivät tuottaneet uutta poimintaa.

Kuvitteellinen asiakasloki

Valinta: GET /demo?area=A
Kopio: runko säilytetty; ETag="demo-v1"
Ehto: If-None-Match="demo-v1"
Vastaus: 304; viite A-kopioon
Toinen yritys: 429; Retry-After=15 sekuntia
DEMO-käytäntö: enintään kaksi yritystä, sitten pysähdys
Uudelleenjulkaisuoikeudet: tarkista erikseen

Kahden yrityksen raja kuuluu esimerkkiin, ei RFC:ihin. Älä keksi sisältöä ilman käyttökelpoista kopiota; valmistele uusi nouto palvelun käytännön mukaan.

Sääntöjen dokumentaatio erillään kuvitteellisista esimerkeistä

Vertaa muita tilanteita ja harjoituksia

Vain yksi sivu

Tarkista kokonaismäärä ja seuraava kursori ennen kattavan luvun julkaisemista.

Puuttuva muutettiin nollaksi

Erota null, puuttuva kenttä, tyhjä lista ja nolla; ne vaikuttavat keskiarvoon.

Sama kysely, uudet luvut

Eurostat kuvaa uusimpien versioiden tietokannan. Säilytä päivätty poiminta vanhojen laskujen toistamiseksi.

Harjoitus ja ratkaisu

Tila 200 ja sovellusvirhe

Kuvitteellinen esimerkki: arvot ja asiakirjat opettavat menetelmää eivätkä kuvaa todellista organisaatiota.

Kuvitteellisen API:n sopimus edellyttää success=true-arvoa ennen käsittelyä. Tarkista HTTP-vastaus, sovelluksen tila ja tulosten olemassaolo erikseen.

Jos taulukko ylittää näytön, vieritä vaakasuunnassa; nuolinäppäimet toimivat alueen ollessa kohdistettuna.

Lähtötiedot
KohdeHavaittu tieto
HTTP-tila200
Sovelluksen tunnistinsuccess=false
Vastaanotettu viestiViesti: kiintiö täynnä
TulostaulukkoTaulukkoa ei annettu

Tarkistettavat asiat

  1. Tarkista HTTP-tila ja sovellusilmaisin erikseen.
  2. Varmista odotetun rakenteen läsnäolo.
  3. Säilytä virhe julkaisematta väärää lukumäärää.
Lue ratkaisu

Ratkaisu ja päätös

Siirto vastasi, mutta keruu epäonnistui sopimuksen mukaan. Nollamäärää ei ole osoitettu. Merkitse epäonnistuminen ja noudata uusintaohjetta; älä keksi tyhjää taulukkoa laskennan jatkamiseksi.

Jos tilanne muuttuu

Jos onnistunut vastaus sisältää aidosti tyhjän taulukon, nolla voidaan osoittaa ilmoitetulle haulle ja rajaukselle. Toista testi success=true-arvolla mutta kesken katkenneella JSON-rungolla: tila ja lippu eivät vieläkään riitä. Hylkää vajaa erä, säilytä jatkamiskohta ja varmista, etteivät osittaiset arvot korvaa viimeistä vahvistettua poimintaa.

Säilytettävä jälki

Säilytä salaisuuksista siivottu haku, tila, virhe, sopimus ja uusintatila.

Dokumentaatioviite : IETF — RFC 9110, 200 OK · Luettu

DOKUMENTOIDUT TIEDOT

Wikidata: truthy valitsee arvon aseman, ei vahvistettua totuutta

Truthy on tekninen näkymä kohde–ominaisuus-parille: ensisijaiset syrjäyttävät normaalit; muutoin normaalit valitaan. Se ei äänestä lähteistä eikä valitse uusinta päivää.

Wikidata: truthy valitsee arvon aseman, ei vahvistettua totuutta
ViiteArvo tai muotoMitä se yksilöi
PreferredRankPreferredKaikki parin ensisijaiset valitaan. Ensisijaisuus ei takaa yhtä arvoa.
NormalRankNormalNormaalit valitaan vain, jos parilla ei ole ensisijaisia. Useat normaalit voivat olla perusteltuja.
DeprecatedRankDeprecatedVanhentuneet väitteet jäävät truthyn ulkopuolelle, mutta täydet väitteet voivat säilyttää virheet ja hylätyt arvot.
wdt:Best non-deprecated rankSuora polku käyttää parhaita ei-vanhentuneita asemia ilman tarkenteita. Ajantasaisuutta, kattavuutta tai tukea ei taata.
wikibase:BestRankFull statement selectionTyyppi valitsee täydet parhaan aseman väitesolmut säilyttäen tarkenteet ja lähteet.
ScopeEntity + propertySääntö on kohde- ja ominaisuuskohtainen. Väestön ensisijaisuus ei valitse perustamisaikaa tai nimeä.

Huomioitavaa aineistossa

Jos kaikki on hylätty, älä oleta paluuta niihin. Erimielisyys ja historia vaativat täydet väitteet asemineen. Suoran kyselyn puute voi johtua suodatuksesta.

Onko wdt:-arvo varmasti uusin?

Ei. Asema ja aikamääre ovat eri mekanismeja. Tarkista ajankohta ja asemakäytäntö; ensisijaisia väitteitä voi olla useita.

Alkuperäisdokumentaatio

Dokumentaatio tarkistettu .

DOKUMENTOIDUT TIEDOT

Maailmanpankin API: erota kolme päivämäärää ja selvitä yksikkö

JSON-vastaus sisältää muutakin kuin arvon. Todellinen ote koskee Suomen väestötiheyttä vuonna 2023. Otsake ilmoittaa WDI-päivityksen päiväksi 8.10.2026; tämä poiminta haettiin 23.10. Kolme päivämäärää vastaavat eri kysymyksiin.

date2023lastupdated2026-10-08extracted2026-10-23
Maailmanpankin API: erota kolme päivämäärää ja selvitä yksikkö
ViiteArvo tai muotoMitä se yksilöi
date2023Havaintovuosi. Se ei muutu vuodeksi 2026, vaikka kysely tehtiin vuonna 2026.
lastupdated2026-10-08Lähteen otsakkeen ilmoittama päivityspäivä. Se ei yksin todista juuri tämän arvon tarkistamista.
extracted2026-10-23Paikallisen poiminnan muodostamispäivä; se ei korvaa havaintojaksoa tai lähteen päivämäärää.
unit""unit-kenttä on tyhjä. EN.POP.DNST määrittelee silti yksiköksi henkilöä/km² maata: tyhjä kenttä ei tarkoita yksiköttömyyttä.
decimal / value0 / 18.3705454665088decimal on nolla, vaikka value sisältää desimaaleja. Säilytä saatu arvo äläkä tulkitse kenttää virhemarginaaliksi.
pages / total1 / 4Neljä havaintoa mahtuu yhdelle vastaussivulle. Toinen kysely voi olla sivutettu: tarkista pages ja total ennen kuin pidät keruuta täydellisenä.

Täsmällinen kysely · tiheys

https://api.worldbank.org/v2/country/FRA;DEU;ESP;FIN/indicator/EN.POP.DNST?date=2023&format=json&per_page=100

Säilytetty otsake ja FIN-havainto

[
    {
        "page": 1,
        "pages": 1,
        "per_page": 100,
        "total": 4,
        "sourceid": "2",
        "lastupdated": "2026-10-08"
    },
    [
        {
            "indicator": {
                "id": "EN.POP.DNST",
                "value": "Population density (people per sq. km of land area)"
            },
            "country": {
                "id": "FI",
                "value": "Finland"
            },
            "countryiso3code": "FIN",
            "date": "2023",
            "value": 18.3705454665088,
            "unit": "",
            "obs_status": "",
            "decimal": 0
        }
    ]
]

Huomioitavaa aineistossa

Tämä on päivätty API-poiminta, joka ei päivity automaattisesti sivua ladattaessa. Sama maatunnus ei todista sarjojen samaa alueellista kattavuutta. Säilytä koko kysely, määritelmät ja puuttuvat arvot analyysin toistamista varten; älä muuta null-arvoa nollaksi.

Alkuperäisdokumentaatio

Dokumentaatio tarkistettu .

DOKUMENTOIDUT TIEDOT

Lomakeparametrit: säilytä välilyönnit, plusmerkit ja toistuvat nimet

Parametriluettelo on järjestetty nimi–arvo-parien jono. Sama nimi voi toistua. Työkalu soveltaa application/x-www-form-urlencoded-muotoa URLSearchParamsilla kahteen yksiriviseen arvoon ja jäsentää tuloksen; lomaketta ei lähetetä.

tag → C++ & IAtag → ététag=C%2B%2B+%26+IA&tag=%C3%A9t%C3%A9getAll("tag") → ["C++ & IA", "été"]
Lomakeparametrit: säilytä välilyönnit, plusmerkit ja toistuvat nimet
ViiteArvo tai muotoMitä se yksilöi
U+0020+U+0020-välilyönti sarjallistuu tässä muodossa plusmerkiksi. Sääntö ei koske yleisesti URL-osoitteen kaikkia osia.
+%2BArvoon kuuluva plusmerkki muuttuu muotoon %2B. Suoraan jo koodattuun merkkijonoon liitetyn C++-arvon plusmerkit tulkittaisiin välilyönneiksi.
&%26Arvon sisäinen & muuttuu muotoon %26 eikä aloita uutta parametria.
=%3DArvon sisäinen = muuttuu muotoon %3D; nimen ja arvon rakenteellinen erotin säilyy =-merkkinä.
été%C3%A9t%C3%A9Muut kuin ASCII-merkit koodataan UTF-8:sta. Prosenttijonot esittävät tavuja, eivät näkyvien kirjainten määrää.
append / get / getAll / setordered pairsappend säilyttää uuden esiintymän. get palauttaa ensimmäisen arvon ja getAll kaikki arvot järjestyksessä. set korvaa ensimmäisen ja poistaa saman nimen muut esiintymät.

Tutki kahta samannimistä parametria

Kaksi esimerkkiarvoa lasketaan tällä sivulla.

Kaksi paria säilytetty järjestyksessä.

Sarjallistus

tag=C%2B%2B+%26+IA&tag=%C3%A9t%C3%A9

getAll-metodilla luetut arvot

["C++ & IA","été"]

get-metodin ensimmäinen arvo

"C++ & IA"

Huomioitavaa aineistossa

Koodaus ei ole salausta eikä HTML:n puhdistusta. Esimerkki ei mallinna lomakekenttien valintaa, multipart-tiedostoja tai lomakkeen rivinvaihtojen normalisointia. Palvelimen on määriteltävä toistuvien parametrien käsittely; liian varhainen muunnos olioksi voi kadottaa arvoja.

Alkuperäisdokumentaatio

Dokumentaatio tarkistettu .

Säilytettävä näyttö

  • Palvelu, versio ja salaisuudettomat parametrit.
  • Aika, tila, muoto, sivut ja pysäytys.
  • Raakavastaus, tunnisteet ja tiiviste.
  • Muunnokset, yksiköt ja rajoitukset.

Viralliset lähteet

Liittyvät lähdesivut

Aiheeseen liittyvät protokollat

Tarkistukset ennen johtopäätöstä

  • Voiko valinnan toistaa ilman salaisuutta?
  • Huomioiko luku sivut ja toistot?
  • Erottuvatko raakavastaukset siivotusta tiedosta?

Usein kysytyt kysymykset

Osoittaako HTTP 200 kattavuuden?

Ei. Tarkista sisältö, suodatus, kokonaismäärä ja sivutus.

Pitääkö kerätä koko tietokanta?

Ei. Valitse hyödyllinen rajaus ja dokumentoi se.

Takaako tiiviste luvut?

Se vertaa säilytettyjä tavuja. Menetelmä ja laatu vaativat omat tarkistuksensa.

Kuinka palauttaa keskeytetty kokoelma?

Pidä viimeinen vaihe vahvistettu, asetukset ja viittaukset jatko. Palautus on tarkistettava kaksoistuminen ja mahdolliset muutokset tietoja sen sijaan, että oletetaan yksinkertainen lisääminen vastauksia.

DOKUMENTOIDUT TIEDOT

HTTP-kirjoitus: tarkista versio ennen asiakirjan korvaamista

Kaksi muokkaajaa voi lukea saman version ja lähettää eri korjaukset. Esiehto antaa palvelimelle keinon hylätä vanhaan esitykseen perustuva kirjoitus. Tapaukset ovat kuvitteellisia: v1 ja v2 ovat opetusmerkintöjä, eivät havaintoja palvelusta.

GET → "v1"ETag: "v2"PUT → 412If-Match: "v1" ≠ ETag: "v2"

Luku → samanaikainen muutos → kirjoituksen hylkäys: kuvitteellinen esimerkki.

HTTP-kirjoitus: tarkista versio ennen asiakirjan korvaamista
ViiteArvo tai muotoMitä se yksilöi
PUT · If-Match: "v1"ETag: "v2" → 412Asiakirja muuttui lukemisen jälkeen. Tämän PUT-pyynnön vahva vertailu epäonnistuu: nykyistä versiota ei pidä korvata. Lue se uudelleen ja tarkista erot.
PUT · If-Match: "v2"ETag: "v2" → ✓Vahvat tunnisteet täsmäävät, joten tämä esiehto sallii käsittelyn jatkamisen. Se ei takaa tilakoodia 200 tai muiden tarkistusten onnistumista.
PUT · If-Match: W/"v2"ETag: "v2" → 412Tunnisteen teksti täsmää, mutta toinen on heikko. If-Match edellyttää vahvaa vertailua ja epäonnistuu. W/-etuliitteen poistaminen ei luo vahvaa validaattoria.
PUT · If-None-Match: *Olemassa → 412 / Puuttuu → ✓Kirjoituksessa tähti edellyttää, ettei nykyistä esitystä ole. Jos esitys on olemassa, ehto on epätosi; muuten käsittely voi jatkua.
GET · If-None-Match: W/"v2"ETag: "v2" → 304GET- ja HEAD-pyynnöissä If-None-Match käyttää heikkoa vertailua. Täsmääminen johtaa vastaukseen 304: käytetään säilytettyä kopiota ilman uutta runkoa.
428Precondition RequiredPalvelin vaatii ehdollisen pyynnön. Puuttuva esiehto eroaa koodista 412, jossa annettu ehto on epätosi. Vastausta 428 ei saa tallentaa välimuistiin.

Kokeile esiehtoa

Muuta menetelmää, tilaa ja ehtoa. Anna tunniste lainausmerkeissä, pilkuin erotettu lista tai pelkkä *. Tarkistus tapahtuu selaimessasi. Kun ehtona on * tai esitys puuttuu, nykyistä ETag-arvoa ei käytetä.

412: ehto ei täyty. Pyydettyä toimintoa ei saa tehdä.

Paikallinen opetussimulaatio: API-pyyntöjä ei lähetetä eikä tietoja tallenneta.

Huomioitavaa aineistossa

Harjoitus arvioi yhden esiehdon ennen toimintoa. Pyyntö oletetaan muuten hyväksyttäväksi, ja jo onnistuneesti suoritetun toiminnon erityistapaus on rajattu pois. Tunnistautuminen, oikeudet, asiakirjan tarkistus ja toimintalogiikka on silti tarkistettava. API:n on tarkistettava ehto ja tehtävä muutos atomisesti, jotta päivityksiä ei katoa.

Alkuperäisdokumentaatio

Dokumentaatio tarkistettu .

SYVENTÄVÄ LUKEMINEN / KÄYTÄNTÖ

Tallenna toistettava kysely

API tarjoaa hyödyllisiä tietoja, mutta tulos riippuu asetuksista ja sivuista. Keräyksen on säilytettävä täydellinen pyyntö ja edellytykset vastauksen ymmärtämiseksi.

Päivitetty .

Ensisijaiset tarkistukset

Valitse URL, asetukset, tila, muoto ja sivu. Tarkista suodattimet, volyymirajat ja palautetut virheet ilman salaisuuksia päiväkirjoissa.

Tulkinnan sudenkuopat

Menestyksekäs vastaus voi sisältää vain yhden tuloksen sivun. Toista kysely myöhemmin voi antaa toisen tilan, jos tiedot ovat muuttuneet.

Säilytettävä työasiakirja

Keräyslehti yhdistää kyselyn, päivämäärän, säilytetyn vastauksen, kattavuuden ja rajan. Se kertoo, miten kierrätys voidaan tarkistaa tai tarkistaa.