Skip to main content
DomovBlogVodniki6 preverjanj za preverjanje najnovejših dogodkov sledenja prevoznika, sinhroniziranih prek vašega API-ja

6 preverjanj za preverjanje najnovejših dogodkov sledenja prevoznika, sinhroniziranih prek vašega API-ja

17TRACK

Če želite preveriti, ali je vaš API sinhroniziral najnovejše dogodke sledenja prevoznika, preverite identiteto pošiljke, časovne žige dogodkov, podrobnosti dogodkov, pot dostave, vrstni red dogodkov in ažurnost glede na neodvisen pogled sledenja. Uspešen odziv API-ja ali potrditev webhooka potrjuje le en del te verige; sam po sebi ne dokazuje, da ima vaša aplikacija najnovejši dogodek prevoznika.

6 preverjanj za potrditev sinhronizacije najnovejših dogodkov sledenja prevoznika

Ta vodnik je namenjen razvijalcem in operativnim ekipam, odgovornim za prenos podatkov o sledenju v sistem za upravljanje naročil, stran, namenjeno strankam, podporno orodje ali delovni tok opozoril. Cilj je ugotoviti, kje je dogodek izginil ali se spremenil, nato pa odločiti, ali je treba ponoviti obdelavo, popraviti preslikavo ali počakati na nove informacije prevoznika.

Pred začetkom: opredelite, kaj pomeni »najnovejše«

Ločite tri čase: kdaj prevoznik navaja, da se je dogodek zgodil, kdaj ga je vaš ponudnik sledenja prejel ali razkril in kdaj ga je vaša aplikacija shranila. Ti časi se lahko razlikujejo. Prevoznik lahko objavi skeniranje po fizičnem dogodku, vaša integracija pa ga lahko obdela še pozneje. Najnovejši dogodek glede na čas nastanka zato ni nujno zapis, ki je bil prejet najpozneje.

Pred preiskavo izberite primerjalno točko. V idealnem primeru uporabite stran za sledenje prevoznika ali drug pooblaščen zapis, ki ga je zagotovil prevoznik, za isto pošiljko. Če to ni mogoče, primerjajte svojo aplikacijo s trenutnim odzivom API-ja ponudnika sledenja. Ta ožja primerjava lahko ugotovi, ali se vaša aplikacija ujema s ponudnikom; ne more pa potrditi, da ima ponudnik že vsako skeniranje prevoznika. Zabeležite, kdaj ste izvedli primerjavo, da poznejša posodobitev ne bo povzročila, da bi bil prejšnji rezultat videti nedosleden.

1. Potrdite, da se oba sistema nanašata na isto pošiljko

Začnite s številko za sledenje, prevoznikom ter morebitnim identifikatorjem računa ali pošiljke, ki ga uporablja vaša integracija. Sama številka za sledenje morda ne bo dovolj za odpravljanje težav: številka je lahko vnesena z napako, povezana z napačnim prevoznikom ali ponovno uporabljena v internem zapisu po urejanju naročila. Številka naročila in številka za sledenje imata tudi različna namena. Eno naročilo lahko vsebuje več paketov, zato lahko preverjanje najnovejšega stanja naročila prikrije zastarel paket.

  • Poiščite natančno številko za sledenje in prevoznika, poslana v API za sledenje.
  • Potrdite, kateri interni zapis pošiljke ali paketa je prejel odziv.
  • Preverite, ali je bila pošiljka po registraciji zamenjana, razdeljena, preklicana ali ponovno povezana.
  • Primerjajte prevoznika in številko v izvornem zapisu s tistima, prikazanima v vaši aplikaciji.

Če se identifikatorji ne ujemajo, razlike ne obravnavajte več kot zamude pri sinhronizaciji. Najprej popravite povezavo, nato ponovite primerjavo dogodkov. V diagnostičnih dnevnikih shranite dovolj identifikatorjev za sledenje pošiljki, vendar vanje ne vključujte občutljivih poverilnic računa.

2. Primerjajte čase dogodkov, ne da bi izgubili njihov pomen

Za vsak možni najnovejši dogodek zabeležite čas nastanka, ki ga je navedel prevoznik, njegov navedeni časovni pas ali odmik, če je na voljo, ter čase prejema in shranjevanja v vaši aplikaciji. Za primerjavo pretvorite časovne žige v skupno časovno osnovo, vendar ohranite izvirno vrednost. RFC 3339 opredeljuje obliko internetnega časovnega žiga z izrecnimi podatki o odmiku; to je uporabna referenca pri načrtovanju lastnih polj časovnih žigov. Ne zagotavlja pa, da bo prevoznik ali ponudnik za vsak dogodek posredoval časovni pas.

Prikaz samo časa, predpostavljeni lokalni časovni pas ali razčlenjevalnik, ki tiho zavrže odmik, lahko dogodek premakne na drug koledarski dan ali ga uvrsti v napačen vrstni red. Če vir navaja dvoumen lokalni čas, primerjavo označite kot negotovo, namesto da bi si izmislili natančen trenutek UTC. Prav tako ločite čas nastanka dogodka od časa odziva API-ja: odziv, pridobljen zdaj, lahko upravičeno vsebuje dogodek, ki se je zgodil prej.

Zapišite čas, ko ste preverili pogled prevoznika ali ponudnika. Če je vir objavil novo skeniranje po vaši zahtevi API-ja, razlika med pogledoma ne dokazuje, da prejšnja zahteva ni uspela.

3. Preverite vsebino dogodka, ne le glavnega stanja

Opis, lokacijo, stanje ali kodo prevoznika ter vse pomembne podatke o dostavi najnovejšega dogodka primerjajte z izvornim zapisom. Normalizirano stanje, kot je »v tranzitu«, lahko povzame več različnih skeniranj. Če vaša aplikacija shranjuje samo povzetek, je lahko videti nespremenjen, čeprav je prispel nov dogodek.

Preglejte neobdelani odziv API-ja ali ohranjeno telo webhooka, kjer to dovoljujejo vaša pravila ravnanja s podatki. Nato sledite dogodku skozi razčlenjevanje, preslikavo polj, trajno shranjevanje in prikaz. Poiščite polja z vrednostjo null, ki jih prepišejo privzete vrednosti, nepričakovane kode stanj, ki se uvrstijo v splošno kategorijo, skrajšano besedilo ali uporabniški vmesnik, ki prikazuje samo izbrane vrste dogodkov. Neskladje oznake stanja se razlikuje od manjkajočega dogodka: kaže na logiko pretvorbe ali prikaza, ne na dostavo.

Dostave ne sklepajte samo zato, ker se lokacija ali stanje zdita končna. Potrdite konkreten dogodek in polja, od katerih je odvisen vaš delovni tok. Nasprotno pa nespremenjeno splošno stanje ni dokaz, da se je sinhronizacija ustavila; novo prejeto skeniranje se lahko preslika v isto kategorijo. Diagnostični zapis mora ohraniti tako izvorni dogodek kot vrednost, prikazano uporabnikom.

4. Izsledite, kako je dogodek dosegel vašo aplikacijo

Če uporabljate webhooke, preverite dnevnik prejemov za ustrezno pošiljko in dogodek. Preverite, ali je vaša končna točka sprejela zahtevo, ali je sporočilo prestalo preverjanje in ali je bila nadaljnja obdelava končana. Uspešen odziv HTTP vaše končne točke ne dokazuje, da je poznejši delavec čakalne vrste shranil dogodek. Če je obdelava asinhrona, preglejte tako dohodno zahtevo kot rezultat opravila.

Če uporabljate anketiranje API-ja, preverite zadnjo dokončano zahtevo, identifikator pošiljke v tej zahtevi, njen odziv ter vso logiko straničenja ali pridobivanja, ki jo uporablja vaša integracija. Uspešni zahtevi lahko še vedno sledi neuspešen zapis v zbirko podatkov ali branje zastarelega predpomnilnika. Z ustrezno dokumentacijo ponudnika preverite dejanska polja odziva, zahteve za preverjanje pristnosti in vedenje dostave za svojo integracijo, namesto da predpostavite, da vsi API-ji za sledenje uporabljajo enak dogovor. Za integracijo 17TRACK sta ustrezni začetni točki njegova stran API-ja za sledenje in dokumentacija API-ja; potrdite dokumentirano vedenje za končno točko in metodo, ki ju uporabljate.

Obdelavo dogodkov zasnujte tako, da jo je varno ponavljati. Ponovni poskus ne sme ustvariti podvojenih skeniranj, večkrat poslati istega obvestila stranki ali zamenjati novejšega shranjenega stanja s starejšo vsebino. Ustrezen ključ za podvajanje je odvisen od polj, ki jih vaš ponudnik dejansko posreduje. Izbrani ključ preizkusite z različnimi dogodki, ki imajo po naključju enako stanje ali časovni žig; ti dogodki se ne smejo združiti samo zato, ker so videti podobni.

5. Preverite pravila vrstnega reda in prehodov stanj

Zabeležene dogodke razvrstite po jasno opredeljenem pravilu in nato preglejte rezultat. Številne aplikacije morajo razlikovati med »najnovejšim dogodkom, ki se je zgodil« in »najnovejšim dogodkom, ki smo ga prejeli«. Zakasnjeno prejšnje skeniranje lahko prispe po novejšem skeniranju. Če vaša zbirka podatkov preprosto določi zadnje obdelano sporočilo kot trenutno stanje pošiljke, lahko to zakasnjeno skeniranje prikazano stanje pomakne nazaj.

Shranjeno zgodovino primerjajte z izvorno zgodovino, ne le z enim poljem stanja. Vprašajte se, ali je bil novo prejeti zapis dodan, zavržen kot dvojnik ali dovoljen za posodobitev trenutnega stanja. Preverite vsa pravila, ki dajejo nekaterim dogodkom prednost pred drugimi. Takšno pravilo je lahko namerno, vendar ne sme skriti osnovnega dogodka ali nakazovati, da je prevoznik razveljavil mejnik, če je aplikacija le pozno prejela starejše skeniranje.

Za praktični preizkus v neprodukcijskem okolju vzemite pošiljko z več kot enim dogodkom in njena sporočila predvajajte v drugačnem vrstnem redu prihoda. Potrdite, da zgodovina dogodkov ostane nespremenjena in da stanje, namenjeno strankam, sledi vašemu dokumentiranemu pravilu. Tako odkrijete napake v vrstnem redu, ki jih običajni preizkus v pravilnem zaporedju ne more razkriti.

6. Izmerite ažurnost in uskladite izjeme

Na koncu primerjajte, kaj je vsak sloj vedel v isti opazovalni točki: pogled prevoznika, odziv ponudnika sledenja, dohodni webhook ali rezultat anketiranja, zapis v zbirki podatkov in izhod, namenjen strankam. Označite prvi sloj, na katerem pričakovani dogodek izgine. Ta meja je uporabnejša od splošnega poročila, da »sledenje zamuja«.

Izmerite tako starost najnovejšega dogodka, ki ga je prijavil prevoznik, kot čas od zadnjega uspešnega preverjanja ali prejema podatkov vaše integracije. Odgovarjata na različni vprašanji. Paket morda nima novega skeniranja prevoznika, čeprav vaša integracija deluje pravilno; po drugi strani lahko prevoznik prikazuje novo skeniranje, medtem ko je bila vaša zadnja uspešna zahteva izvedena že zdavnaj. Uporabite pragove opozoril, ki odražajo vaše operativne zahteve in opaženo vedenje. Strankam ne obljubljajte stalnega intervala posodobitev, razen če ga podpirajo vaši dogovori s prevoznikom in ponudnikom.

Vzpostavite majhno čakalno vrsto za usklajevanje pošiljk, katerih zapisi se razlikujejo od izbranega primerjalnega vira. Vključite identifikatorje, manjkajoči ali neusklajeni dogodek, pomembne časovne žige, prvi neuspešni sloj in naslednji ukrep. Dogodek, ki je prisoten v odzivu ponudnika, vendar manjka v vaši zbirki podatkov, na primer zahteva preiskavo integracije. Dogodek, ki je prisoten v vaši zbirki podatkov, vendar manjka na strani za sledenje, zahteva preverjanje prikaza ali predpomnjenja. Če prevoznik sam ne prikazuje novega skeniranja, ga dodatna zahteva API-ja ne more ustvariti.

Operativni preizkus je preprost: ali lahko prepoznate isto pošiljko, poiščete njen najnovejši znani izvorni dogodek in temu dogodku sledite vse do pogleda, namenjenega uporabniku, ne da bi spremenili njegov pomen? Če ne, šest preverjanj zoži težavo na določeno mejo in vaši ekipi ponudi utemeljen naslednji korak.

Pogosta vprašanja

Ali uspešen odziv webhooka pomeni, da je najnovejši dogodek sinhroniziran?

Ne. Kaže, da je vaša končna točka na zahtevo vrnila uspešen odziv. Potrdite, da so bili uspešni tudi preverjanje, obdelava čakalne vrste, shranjevanje v zbirko podatkov in prikaz. Preverite vsebino, da ugotovite, kateri dogodek je zahteva vsebovala.

Zakaj stran prevoznika prikazuje novejše skeniranje kot moj odziv API-ja?

Najprej potrdite, da gledate isti paket in da sta bili obe opažanji izvedeni ob primerljivih časih. Objava prevoznika ter prejem ali razkritje dogodka s strani ponudnika sledenja se lahko zgodita ob različnih časih. Če razlika ostane, uporabite dokumentacijo ponudnika in njegov podporni postopek za preiskavo konkretne pošiljke, namesto da predpostavite zagotovljeno posodobitev.

Ali naj za izbiro najnovejšega stanja uporabim časovni žig dogodka ali čas, ko ga je moj sistem prejel?

Uporabite dokumentirano pravilo, primerno za vaš delovni tok, in ohranite obe vrednosti. Časovni žig dogodka opisuje, kdaj se je prijavljena dejavnost zgodila; čas prejema opisuje, kdaj je vaš sistem zanjo izvedel. Nobeno polje samo po sebi ne razreši vsakega primera, zlasti kadar so izvorni časi dvoumni ali pozna skeniranja prispejo pozneje.

Kaj če je stanje API-ja nespremenjeno, seznam dogodkov pa ima nov vnos?

To je lahko pričakovano, če se več dogodkov prevoznika preslika v eno normalizirano stanje. Primerjajte podrobnosti dogodka in preverite, ali je vaša aplikacija shranila ter prikazuje nov vnos, kjer je to ustrezno. Manjkajoči dogodek in nespremenjena povzetna oznaka obravnavajte kot različni težavi.

Viri