Reaaliaikaisen seurannan pyyntö aikakatkaistiin? Noudata näitä uudelleenyritys-, varamenettely- ja tilasääntöjä
Kun reaaliaikainen seurantapyyntö aikakatkaistaan, käsittele lähetyksen viimeisin tila tuntemattomana – älä viivästyneenä, kadonneena tai muuttumattomana. Yritä uudelleen vain rajatun aikabudjetin puitteissa ja näytä sen jälkeen selkeästi merkitty viimeisin tunnettu päivitys tai pyydä käyttäjää tarkistamaan tilanne myöhemmin uudelleen. Pidä pyynnön lopputulos, tietojen ajantasaisuus ja paketin todellinen tila erillään koko prosessin ajan.
Tämä erottelu on tärkeä sekä asiakkaille suunnatuilla seurantaa näyttävillä sivuilla että järjestelmissä, jotka käyttävät seurantatietoja ilmoitusten tai tukiprosessien käynnistämiseen. Aikakatkaisu kertoo, ettei vastaus saapunut ajoissa. Se ei kerro, onko kuljetusyhtiöllä uusi tapahtuma, käsittelitkö ylemmän tason palvelu pyynnön tai onko paketti liikkunut.
Tunnista ensin, mikä aikakatkaistiin
Seurantapyyntö voi epäonnistua useissa kohdissa: selain voi lopettaa sovelluksesi odottamisen, sovelluksesi voi lopettaa seuranta-API:n odottamisen tai kyseinen API voi aikakatkaista ottaessaan yhteyttä toiseen palveluun. Käyttäjä saattaa nähdä kaikissa tapauksissa saman yleisen virheilmoituksen, mutta asianmukainen seuraava toimenpide on erilainen.
- Asiakaspuolen aikakatkaisu: Sovellus lopetti odottamisen. Palvelinpuolen pyyntö on silti saattanut valmistua. Tarkista omat pyyntölokisi tai tulosvarastosi ennen uuden pyynnön lähettämistä, joka voisi tehdä työn kahdesti.
- Verkko- tai yhteysvirhe: Järjestelmäsi ei saanut käyttökelpoista vastausta. Et ehkä tiedä, käsittelikö etäpalvelu pyynnön.
- HTTP 504: Yhdyskäytävä tai välityspalvelin ei saanut ajoissa vastausta ylemmän tason palvelimelta. Tämä kuvaa pyyntöpolkua, ei lähetystä.
- HTTP 408: Palvelin ei saanut täydellistä pyyntöviestiä sen ajan kuluessa, jonka se oli valmistautunut odottamaan. Se ei ole kuljetusyhtiön seurantatila.
- HTTP 200 vanhalla tapahtumalla: Pyyntö onnistui, mutta palautetut seurantatiedot voivat silti olla vanhentuneita. Onnistunut HTTP-vastaus ei takaa tietojen ajantasaisuutta.
Kirjaa nämä tulokset pyyntöjen diagnostiikkatietoina. Älä käännä mitään niistä lähetyksen tilamerkinnöiksi, kuten ”kuljetuksessa”, ”poikkeama” tai ”toimitettu”. Näiden merkintöjen tulee perustua seurantatapahtumiin tai dokumentoituun tilakenttään, ei siirtokerrokseen.
Käytä rajattua uudelleenyritystä, älä päättymätöntä silmukkaa
Vain lukuun tarkoitetussa seurantahaussa uudelleenyritys aikakatkaisun jälkeen on usein järkevää. Sen tulee silti olla rajoitettu. Toistuvat pyynnöt voivat lisätä kuormitusta vaikeuksissa olevaan palveluun, pidentää käyttäjän odotusta ja aiheuttaa päällekkäistä työtä, kun useat sovelluskerrokset yrittävät uudelleen itsenäisesti.
- Aseta kokonaismääräaika. Päätä, kuinka kauan käyttäjälle näkyvä toiminto saa kestää, mukaan lukien ensimmäinen yritys ja mahdollinen uudelleenyritys. Älä anna jokaiselle yritykselle uutta täyttä määräaikaa, joka ylittää ajan, jonka kutsuja voi odottaa.
- Tarkista, onko toiminto turvallista toistaa. Haku eroaa yleensä pyynnöstä, joka rekisteröi lähetyksen, muuttaa asetuksia tai luo resurssin. Älä toista tilaa muuttavaa pyyntöä automaattisesti, ellei palveluntarjoajan sopimus tai idempotenssin hallintasi tee siitä turvallista.
- Yritä väliaikaisen virheen jälkeen uudelleen harkiten. Käytä pientä, nimenomaista uudelleenyritysbudjettia ja viivettä, johon lisätään hajontaa, sen sijaan että monet asiakkaat lähettäisivät samanaikaisia välittömiä uudelleenyrityksiä.
- Noudata soveltuvia palvelimen ohjeita. Jos vastaus sisältää kelvollisen
Retry-After-otsakkeen, älä ajoita uudelleenyritystä sitä aikaisemmaksi. Noudata myös tiukempaa sovelluksen tai palveluntarjoajan omaa rajoitusta. - Lopeta, kun määräaika tai budjetti on käytetty. Siirry varavastaukseen ja ajoita myöhempi täsmäytys erikseen, jos työnkulku sitä tarvitsee.
Käytännöllinen rakenne voi sallia yhden käyttäjälle näkyvän uudelleenyrityksen, jos aikaa on riittävästi, ja siirtää lisäyritykset taustapäivitykseen. Tämä on esimerkki toimintaperiaatteesta, ei yleinen API-sääntö. Valitse rajat palvelutason tavoitteiden, havaitun viiveen ja palveluntarjoajan dokumentaation perusteella. Ota huomioon myös HTTP-kirjastojen, yhdyskäytävien ja työjonotyöntekijöiden tekemät uudelleenyritykset; muuten näennäisen maltillinen sovelluskäytäntö voi synnyttää monia ylemmän tason kutsuja.
HTTP 429 -vastauksessa käsittele vastausta nopeusrajoituksen merkkinä, älä syynä yrittää heti uudelleen. HTTP 503 voi ilmaista tilapäistä kyvyttömyyttä käsitellä pyyntöä, ja palvelin voi toimittaa Retry-After-otsakkeen. 504 voi olla tilapäinen, mutta se ei takaa seuraavan yrityksen onnistumista. Todennusvirheet edellyttävät yleensä tunnistetietojen tai käyttöoikeuksien tarkistamista, kun taas virheelliset pyynnöt vaativat syötteen korjaamista. Seurantatunniste, joka tuottaa ”ei löydy” -tuloksen, vaatii enemmän harkintaa: palveluntarjoajan dokumentoidusta toiminnasta ja lähetyksen vaiheesta riippuen tietueen löytyminen voi olla liian aikaista tai tunniste voi olla väärä. Älä muuta yhtä tällaista tulosta varmaksi väitteeksi siitä, ettei pakettia ole olemassa.
Valitse varatoiminto, joka säilyttää tiedossa olevat asiat
Turvallisin varatoiminto on yleensä viimeisin vahvistettu seurantatulos, jonka yhteydessä ilmoitetaan sen oma tapahtuma-aika ja rehellinen ajantasaisuusmerkintä. Pidä tämä tulos erillään nykyisen pyynnön epäonnistumisesta. Sivulla voitaisiin ilmoittaa: ”Viimeisin saatavilla oleva päivitys: Lähti käsittelylaitoksesta. Viimeksi tarkistettu: [aika]. Uudempi päivitys ei ole tilapäisesti saatavilla.” Lisää ”Viimeksi tarkistettu” vain, jos järjestelmäsi todella tallentaa sen; se ei korvaa kuljetusyhtiön tapahtuma-aikaa.
Käytä tarkinta aikaa, jonka voit perustellusti ilmoittaa. Kuljetusyhtiön tapahtuma-aika kuvaa, milloin tapahtuman ilmoitetaan tapahtuneen. Aika, jolloin järjestelmäsi vastaanotti tapahtuman, kuvaa tietojen vastaanottoa. Aika, jolloin käyttäjä avasi sivun, ei kuvaa kumpaakaan. Jos lähde ei tarjoa luotettavaa tapahtuma-aikaa tai aikavyöhykettä, älä keksi sellaista. Jos välimuistissa olevalla tuloksella ei ole tallennettua hakuhetkeä, kutsu sitä ”viimeisimmäksi saatavilla olevaksi päivitykseksi” sen sijaan, että väittäisit sen päivittyneen äskettäin.
Varatoiminnon tulee noudattaa kolmea rajaa:
- Näytä välimuistissa olevat tiedot välimuistitietoina. Älä esitä vanhempaa tapahtumaa aikakatkaistun pyynnön tuloksena.
- Älä päättele etenemistä kuluneen ajan perusteella. Paketti ei ole ”jakelussa” vain siksi, että se on ollut useita päiviä kuljetuksessa.
- Älä piilota olennaista epävarmuutta. Jos aiempaa tulosta ei ole, ilmoita seurannan olevan tilapäisesti poissa käytöstä sen sijaan, että näyttäisit keksityn oletustilan.
Muita varareittejä voivat olla aiemmin synkronoitu seurantatietovarasto, valtuutettu haku kuljetusyhtiöltä tai myöhempi taustapäivitys. Käytä niitä vain, jos ne sopivat lähetykseen, käyttöoikeuksiisi ja tietolähteen ehtoihin. Toisella lähteellä voi olla erilaiset tapahtumanimet tai raportointiviiveet, joten säilytä alkuperätiedot ja vältä ristiriitaisten tietueiden yhdistämistä ilman siihen määriteltyä sääntöä. Jos asiakas voi toimia tuloksen perusteella, tarjoa mahdollisuus yrittää uudelleen tai ottaa yhteyttä tukeen sen sijaan, että jättäisit latausilmaisimen näkyviin loputtomasti.
Pidä pyynnön tila, tietojen ajantasaisuus ja lähetyksen tila erillään
Nämä ovat kolme eri kenttää, vaikka käyttöliittymä näyttäisi ne yhdessä. Pyynnön tila kertoo, onnistuiko haku, aikakatkaistiinko se vai saatiinko virhe. Tietojen ajantasaisuus kertoo, milloin palautetut tai tallennetut tiedot havaittiin. Lähetyksen tila kertoo, mitä seurantatietolähde ilmoittaa paketista. Niiden erottaminen estää tilapäistä API-virhettä korvaamasta kelvollista toimitustapahtumaa tai vanhentunutta kuljetuksessa-tilaa muuttumasta nykyhetkeä koskevaksi väitteeksi.
Järjestelmä voi esimerkiksi sisältää aiemmassa haussa vahvistetun ”Toimitettu”-tapahtuman samalla, kun nykyinen päivitys aikakatkaistaan. Toimitustapahtuma ei katoa. Oikea yhdistetty tila on, että viimeisin saatavilla oleva lähetyksen tila on toimitettu ja uusin päivitys epäonnistui. Jos viimeisin tapahtuma taas on ”Kuljetuksessa”, aikakatkaisu ei vahvista, että paketti on edelleen juuri nyt kuljetuksessa; se vahvistaa vain, ettei uudempaa vastausta saatu.
Laadi määritelty sääntö tilanteisiin, joissa tapahtumat saapuvat epäjärjestyksessä. Vertaa tapahtumatunnisteita, aikaleimoja, lähdettä ja mahdollisuuksien mukaan palveluntarjoajan dokumentoituja tilamerkityksiä. Älä oleta, että järjestelmäsi vastaanottamien päivitysten järjestys vastaa lähetyksen tapahtumien järjestystä. Myöhässä saapuvan vanhemman tapahtuman ei myöskään pidä automaattisesti korvata uudempaa vahvistettua tilaa. Korjaukset ja poikkeukset voivat kuitenkin olla oikeutettuja, joten vältä yleissääntöä, joka pitää toimituksen jälkeisiä tilamuutoksia mahdottomina. Säilytä taustalla olevat tapahtumat ja tutki ristiriidat sen sijaan, että kirjoittaisit historian hiljaisesti uusiksi.
Jos palveluntarjoaja palauttaa HTTP 202:n, tulkitse se kyseisen päätepisteen sopimuksen mukaisesti: pyynnön hyväksyminen ei yksin tarkoita, että seurantahaku on valmis. Vastaavasti HTTP 200 vahvistaa, että HTTP-pyyntö onnistui kyseisen päätepisteen merkityksen mukaisesti; se ei todista, että kaikki seurantakentät ovat mukana tai ajan tasalla. Yhdistä palveluntarjoajakohtaiset vastauskentät vasta sen jälkeen, kun olet tarkistanut palveluntarjoajan dokumentaation.
Tee virhe näkyväksi ylläpitäjille ilman asiakkaiden huolestuttamista
Hyödyllinen toimintatietue sisältää pyynnön tunnisteen, päätepisteen tai toiminnon, yrityskertojen määrän, kuluneen ajan, aikakatkaisukerroksen, saadun HTTP-tilan sekä tiedon siitä, tuliko vastaus reaaliaikaisesta hausta vai varatoiminnosta. Seurantatiedoista tulee kirjata lähde ja olennaiset tapahtuma- tai hakuajat. Käsittele seurantanumeroita ja asiakastietoja organisaatiosi käyttö- ja säilytyssääntöjen mukaisesti; diagnostiikan hyödyllisyys ei ole syy paljastaa täydellisiä tunnisteita rajoittamattomissa lokeissa.
Tarkkaile malleja sen sijaan, että luottaisit yhteen aikakatkaisuun. Yhden kuljetusyhtiön reitin kasvava aikakatkaisuprosentti, toistuvat 429-vastaukset tai kuljetusyhtiön tapahtuma-ajan ja hakuajan kasvava ero voivat viitata eri ongelmiin. Ensimmäinen voi edellyttää palveluntarjoajan tutkimusta, toinen nopeudenhallintaa ja kolmas synkronoinnin tai tapahtumien toimituksen tarkistamista. Jos sovellus tarjoaa seurantaa esimerkiksi 17TRACK Tracking API -palvelun kautta, tarkista kyseisen palveluntarjoajan dokumentaatiosta päätepistekohtaiset vastauskentät, pyyntörajoitukset ja virheenkäsittely ennen näiden yleisten sääntöjen toteuttamista.
Asiakkaalle näytettävässä viestissä ole täsmällinen ja hillitty: ”Seurantaa ei voitu päivittää juuri nyt. Tässä on viimeisin saatavilla oleva päivitys.” Anna seuraava toimintaohje, kun siitä on hyötyä, esimerkiksi tarkistaminen myöhemmin uudelleen tai yhteydenotto tukeen, jos lähetys on myyjän tai kuljetusyhtiön ilmoittaman odotetun toimitusajan ulkopuolella. Vältä lupaamasta päivitysaikaa, jota järjestelmäsi ei voi taata.
Aikakatkaisuja kestävän seurantaprosessin julkaisun tarkistuslista
- Varmista, mikä kerros määrää kunkin aikakatkaisun ja mikä kerros hallitsee uudelleenyrityksiä.
- Aseta pyynnölle kokonaismääräaika ja erillinen, rajattu uudelleenyritysbudjetti.
- Varmista, että automaattisesti uudelleen yritettävät toiminnot ovat turvallisia toistaa.
- Noudata nopeusrajoituksia ja kelvollisia
Retry-After-ohjeita. - Tallenna pyynnön lopputulos erillään lähetyksen tilasta ja tapahtumahistoriasta.
- Merkitse varatoiminnon tiedot ja säilytä niiden lähde sekä aikaleimat, kun ne ovat saatavilla.
- Testaa välimuistittomat, vanhentuneen välimuistin, 429-, 503-, 504- ja myöhäisen vastauksen tilanteet.
- Varmista, ettei aikakatkaisu voi käynnistää virheellistä toimitusilmoitusta tai poistaa vahvistettua tapahtumaa.
Perussääntö on yksinkertainen: yritä pyyntöä uudelleen vain, kun se on turvallista ja hyödyllistä; käytä varatoimintona vain tietoja, jotka pystyt tunnistamaan; äläkä koskaan tee lähetyksen tilaa koskevaa väitettä HTTP-aikakatkaisun perusteella.
Usein kysytyt kysymykset
Pitäisikö aikakatkaistu seurantapyyntö yrittää heti uudelleen?
Ei automaattisesti. Tarkista, että toiminto on turvallista toistaa, että kokonaismääräajassa on aikaa uudelle yritykselle ja ettei mikään nopeusrajoitusohje käske odottamaan. Lyhyt, rajattu ja hajontaa käyttävä uudelleenyritys voi sopia vain lukuun tarkoitettuun hakuun; toistuvat välittömät uudelleenyritykset ovat huono oletus.
Tarkoittaako HTTP 504, että kuljetusyhtiön seurantajärjestelmä ei toimi?
Ei. Se tarkoittaa, ettei yhdyskäytävä tai välityspalvelin saanut ajoissa vastausta ylemmän tason palvelulta. Ongelma voi olla missä tahansa kyseisen pyynnön reitillä. Se ei osoita kuljetusyhtiön yleistä saatavuutta eikä paketin tilaa.
Voinko näyttää viimeksi tunnetun tilan aikakatkaisun jälkeen?
Kyllä, jos merkitset sen viimeisimmäksi saatavilla olevaksi tiedoksi etkä onnistuneeksi reaaliaikaiseksi päivitykseksi. Näytä tapahtuma-aika ja hakuaika, kun ne ovat tiedossa, ja kerro selkeästi, ettei uudempaa päivitystä voitu vahvistaa.
Pitäisikö aikakatkaisun muuttaa lähetyksen tila ”kuljetuksessa”-tilasta ”poikkeamaksi”?
Ei. Aikakatkaisu on pyyntövirhe, ei lähetyksen tapahtuma. Muuta lähetyksen tila vain, kun luotettava seurantatietolähde toimittaa tapahtuman tai tilan, joka tukee muutosta.
Mitä jos aikakatkaistu pyyntö oli luomassa tai rekisteröimässä seurantatietuetta?
Älä oleta sen epäonnistuneen. Etäjärjestelmä on voinut käsitellä sen ennen vastauksen katoamista. Tarkista olemassa oleva tulos ja käytä dokumentoitua idempotenssimekanismia tai palveluntarjoajan hyväksymää palautusmenettelyä ennen kuin lähetät sen uudelleen.
Lähteet
- RFC 9110, HTTP Semantics — HTTP-tilojen määritelmät,
Retry-Afterja pyyntöjen uudelleen yrittämistä koskevat näkökohdat. - RFC 6585, Additional HTTP Status Codes — HTTP 429:n määritelmä ja sen käyttö yhdessä
Retry-After-otsakkeen kanssa. - Amazon Builders’ Library, “Timeouts, retries, and backoff with jitter” — teknisiä ohjeita uudelleenyritysten moninkertaistumisesta, viiveestä ja hajonnasta.
- 17TRACK Tracking API documentation — viite palveluntarjoajakohtaisen API-toiminnan tarkistamiseen ennen toteutusta.


