6 patikros, skirtos patikrinti naujausius vežėjo sekimo įvykius, sinchronizuotus per jūsų API
Norėdami patikrinti, ar jūsų API sinchronizavo naujausius vežėjo sekimo įvykius, pagal nepriklausomą sekimo rodinį patikrinkite siuntos tapatybę, įvykių laiko žymas, įvykių informaciją, pristatymo kelią, įvykių eilės tvarką ir naujumą. Sėkmingas API atsakymas arba žiniatinklio sąsajos patvirtinimas patvirtina tik vieną šios grandinės dalį; vien tai neįrodo, kad jūsų programa gavo naujausią vežėjo įvykį.

Šis vadovas skirtas kūrėjams ir operacijų komandoms, atsakingoms už sekimo duomenų perkėlimą į užsakymų valdymo sistemą, klientams skirtą puslapį, pagalbos įrankį ar įspėjimų darbo eigą. Tikslas – nustatyti, kur įvykis dingo arba pasikeitė, ir nuspręsti, ar reikia pakartoti apdorojimą, pataisyti susiejimą, ar palaukti naujos vežėjo informacijos.
Prieš pradedant: apibrėžkite, ką reiškia „naujausias“
Laikykite atskirai tris laikus: kada vežėjas nurodo, kad įvyko įvykis, kada jūsų sekimo paslaugų teikėjas jį gavo arba pateikė, ir kada jūsų programa jį išsaugojo. Šie laikai gali skirtis. Vežėjas gali paskelbti nuskaitymą praėjus tam tikram laikui po fizinio įvykio, o jūsų integracija gali jį apdoroti dar vėliau. Todėl naujausias įvykis pagal įvykimo laiką nebūtinai yra vėliausiai gautas įrašas.
Prieš pradėdami tyrimą pasirinkite palyginimo tašką. Geriausia naudoti vežėjo sekimo puslapį arba kitą įgaliotą vežėjo pateiktą įrašą apie tą pačią siuntą. Jei tai neįmanoma, palyginkite savo programą su dabartiniu sekimo paslaugų teikėjo API atsakymu. Šis siauresnis palyginimas gali parodyti, ar jūsų programa sutampa su teikėju, tačiau negali patvirtinti, kad teikėjas jau turi kiekvieną vežėjo nuskaitymą. Užrašykite, kada atlikote palyginimą, kad vėlesnis atnaujinimas nepadarytų ankstesnio rezultato atrodančio nenuoseklaus.
1. Patvirtinkite, kad abi sistemos nurodo tą pačią siuntą
Pradėkite nuo sekimo numerio, vežėjo ir bet kurio paskyros arba siuntos identifikatoriaus, naudojamo jūsų integracijoje. Vien sekimo numerių gali nepakakti trikčių diagnostikai: numeris galėjo būti įvestas su klaida, susietas su netinkamu vežėju arba pakartotinai panaudotas vidiniame įraše po užsakymo redagavimo. Užsakymo numeris ir sekimo numeris taip pat atlieka skirtingas funkcijas. Vienas užsakymas gali turėti kelis siuntinius, todėl tikrinant naujausią užsakymo būseną gali būti nepastebėtas pasenęs siuntinys.
- Raskite tikslų sekimo numerį ir vežėją, pateiktus sekimo API.
- Patvirtinkite, kuriam vidiniam siuntos ar siuntinio įrašui buvo priskirtas atsakymas.
- Patikrinkite, ar po registracijos siunta nebuvo pakeista, padalyta, atšaukta arba susieta iš naujo.
- Palyginkite vežėją ir numerį šaltinio įraše su tais, kurie rodomi jūsų programoje.
Jei identifikatoriai nesutampa, nelaikykite šio skirtumo sinchronizavimo delsa. Pirmiausia pataisykite susiejimą, tada pakartokite įvykių palyginimą. Diagnostikos žurnaluose saugokite pakankamai identifikatorių, kad būtų galima atsekti siuntą, tačiau į juos neįrašykite slaptų paskyros prisijungimo duomenų.
2. Palyginkite įvykių laikus neprarasdami jų reikšmės
Kiekvienam galimam naujausiam įvykiui užfiksuokite vežėjo nurodytą įvykio laiką, nurodytą laiko juostą arba poslinkį, jei jie pateikti, ir jūsų programos gavimo bei išsaugojimo laikus. Palyginimui konvertuokite laiko žymas į bendrą laiko bazę, tačiau išsaugokite pradinę reikšmę. RFC 3339 apibrėžia interneto laiko žymos formatą su aiškia poslinkio informacija; tai naudingas atskaitos taškas kuriant savo laiko žymų laukus. Tačiau jis negarantuoja, kad vežėjas ar teikėjas pateiks laiko juostą kiekvienam įvykiui.
Tik laiko rodinys, numanoma vietinė zona arba analizatorius, tyliai pašalinantis poslinkį, gali perkelti įvykį į kitą kalendorinę dieną arba nustatyti neteisingą jo eilę. Kai šaltinis pateikia dviprasmišką vietinį laiką, pažymėkite palyginimą kaip neaiškų, o ne išgalvokite tikslų UTC momentą. Taip pat atskirkite įvykio laiką nuo API atsakymo laiko: dabar gautame atsakyme teisėtai gali būti anksčiau įvykęs įvykis.
Užrašykite laiką, kada patikrinote vežėjo arba teikėjo rodinį. Jei šaltinis paskelbė naują nuskaitymą po jūsų API užklausos, skirtumas tarp dviejų rodinių neįrodo, kad ankstesnė užklausa nepavyko.
3. Tikrinkite įvykio duomenis, o ne tik pagrindinę būseną
Palyginkite naujausio įvykio aprašą, vietą, vežėjo būseną arba kodą ir visus svarbius pristatymo laukus su pirminiu įrašu. Normalizuota būsena, pavyzdžiui, „gabenama“, gali apibendrinti kelis skirtingus nuskaitymus. Jei jūsų programa išsaugo tik santrauką, gali atrodyti, kad niekas nepasikeitė, nors gautas naujas įvykis.
Peržiūrėkite neapdorotą API atsakymą arba išsaugotą žiniatinklio sąsajos turinį, jei tai leidžia jūsų duomenų tvarkymo taisyklės. Tada sekite įvykį per analizę, laukų susiejimą, išsaugojimą ir pateikimą. Ieškokite laukų, kuriuose null reikšmės pakeičiamos numatytosiomis, netikėtų būsenos kodų, patenkančių į bendrą kategoriją, sutrumpinto teksto arba naudotojo sąsajos, rodančios tik pasirinktus įvykių tipus. Būsenos etiketės neatitikimas skiriasi nuo trūkstamo įvykio: jis rodo transformavimo arba rodymo logikos, o ne pristatymo problemą.
Neišvadinkite pristatymo vien todėl, kad vieta ar būsena skamba galutinai. Patvirtinkite konkretų įvykį ir laukus, kuriais remiasi jūsų darbo eiga. Ir atvirkščiai, nepakitusi aukšto lygio būsena neįrodo, kad sinchronizavimas sustojo; naujai gautas nuskaitymas galėjo būti susietas su ta pačia kategorija. Diagnostikos įraše turėtų būti išsaugotas ir pirminis įvykis, ir naudotojams rodoma reikšmė.
4. Atsekite, kaip įvykis pasiekė jūsų programą
Jei naudojate žiniatinklio sąsajas, patikrinkite atitinkamos siuntos ir įvykio gavimo žurnalą. Įsitikinkite, kad jūsų galinis taškas priėmė užklausą, pranešimas praėjo patikrą ir tolesnis apdorojimas baigėsi. HTTP sėkmės atsakymas iš jūsų galinio taško neįrodo, kad vėlesnis eilės darbuotojas išsaugojo įvykį. Jei apdorojimas yra asinchroninis, patikrinkite ir gaunamą užklausą, ir užduoties rezultatą.
Jei apklausiate API, patikrinkite paskutinę užbaigtą užklausą, joje naudotą siuntos identifikatorių, atsakymą ir bet kokią jūsų integracijos naudojamą puslapiavimo arba gavimo logiką. Po sėkmingos užklausos vis tiek gali nepavykti įrašyti į duomenų bazę arba gali būti nuskaityta pasenusi talpykla. Naudodamiesi teikėjo taikoma dokumentacija patikrinkite faktinius atsakymo laukus, autentifikavimo reikalavimus ir jūsų integracijos pristatymo veikimą, o ne manykite, kad visi sekimo API naudoja tą pačią sutartį. Jei naudojate 17TRACK integraciją, svarbiausi pradžios taškai yra jos sekimo API puslapis ir API dokumentacija; patvirtinkite dokumentuose aprašytą jūsų naudojamo galinio taško ir metodo veikimą.
Užtikrinkite, kad įvykių apdorojimą būtų saugu kartoti. Pakartotinis bandymas neturėtų sukurti pasikartojančių nuskaitymų, pakartotinai siųsti to paties kliento pranešimo arba pakeisti naujesnės išsaugotos būsenos senesniu naudinguoju kroviniu. Tinkamas pasikartojimo raktas priklauso nuo laukų, kuriuos iš tikrųjų pateikia jūsų teikėjas. Išbandykite pasirinktą raktą su skirtingais įvykiais, kurie turi tą pačią būseną arba laiko žymą; tokie įvykiai neturėtų būti sujungiami vien todėl, kad atrodo panašūs.
5. Patikrinkite eiliškumo ir būsenos perėjimo taisykles
Surikiuokite užregistruotus įvykius pagal aiškiai apibrėžtą taisyklę, tada patikrinkite rezultatą. Daugeliui programų reikia atskirti „paskutinį įvykusį įvykį“ nuo „paskutinio gauto įvykio“. Ankstesnis nuskaitymas gali būti gautas po naujesnio nuskaitymo. Jei duomenų bazė dabartinę siuntos būseną tiesiog nustato pagal paskutinę apdorotą žinutę, pavėluotas nuskaitymas gali grąžinti rodoma būseną atgal.
Palyginkite savo išsaugotą istoriją su pirminio šaltinio istorija, o ne tik vieną būsenos lauką. Paklauskite, ar naujai gautas įrašas buvo pridėtas, atmestas kaip pasikartojantis arba leistas atnaujinti dabartinę būseną. Patikrinkite visas taisykles, suteikiančias tam tikriems įvykiams pirmenybę prieš kitus. Tokia taisyklė gali būti tyčinė, tačiau ji neturėtų paslėpti pagrindinio įvykio ar sudaryti įspūdžio, kad vežėjas atšaukė etapą, jei programa tiesiog vėlai gavo senesnį nuskaitymą.
Praktiniam bandymui pasirinkite siuntą, turinčią daugiau nei vieną įvykį, ir neprodukcinėje aplinkoje pakartokite jos žinutes kita gavimo tvarka. Patvirtinkite, kad įvykių istorija lieka nepakitusi ir kad klientams rodoma būsena atitinka jūsų dokumentuotą taisyklę. Taip atskleisite eiliškumo klaidas, kurių įprastas bandymas teisinga seka neparodo.
6. Išmatuokite naujumą ir suderinkite išimtis
Galiausiai palyginkite, ką kiekvienas sluoksnis žinojo tuo pačiu stebėjimo momentu: vežėjo rodinį, sekimo teikėjo atsakymą, gaunamą žiniatinklio sąsajos pranešimą arba apklausos rezultatą, duomenų bazės įrašą ir klientui rodomą rezultatą. Pažymėkite pirmą sluoksnį, kuriame tikėtinas įvykis dingsta. Ši riba yra naudingesnė nei bendras pranešimas, kad „sekimas vėluoja“.
Išmatuokite ir naujausio vežėjo pranešto įvykio amžių, ir laiką nuo tada, kai jūsų integracija paskutinį kartą sėkmingai patikrino arba gavo duomenis. Jie atsako į skirtingus klausimus. Siunta gali neturėti naujo vežėjo nuskaitymo, nors jūsų integracija veikia tinkamai; kita vertus, vežėjas gali rodyti naują nuskaitymą, o jūsų paskutinė sėkminga užklausa gali būti sena. Naudokite įspėjimų ribas, atitinkančias jūsų veiklos reikalavimus ir pastebėtą elgseną. Nežadėkite klientams fiksuoto atnaujinimo intervalo, nebent jūsų susitarimai su vežėju ir teikėju tai palaiko.
Sukurkite nedidelę suderinimo eilę siuntoms, kurių įrašai skiriasi nuo pasirinkto palyginimo šaltinio. Įtraukite identifikatorius, trūkstamą arba nesutampantį įvykį, svarbias laiko žymas, pirmąjį nesėkmės sluoksnį ir kitą veiksmą. Pavyzdžiui, teikėjo atsakyme esantis, bet duomenų bazėje nesantis įvykis reikalauja integracijos tyrimo. Duomenų bazėje esantis, bet sekimo puslapyje trūkstamas įvykis reikalauja rodymo arba talpyklos patikros. Jei pats vežėjas nerodo naujo nuskaitymo, kita API užklausa jo sukurti negali.
Veiklos patikrinimas yra paprastas: ar galite nustatyti tą pačią siuntą, rasti naujausią žinomą pirminio šaltinio įvykį ir sekti jį iki naudotojui rodomo rodinio nepakeisdami jo reikšmės? Jei ne, šie šeši patikrinimai susiaurina problemą iki konkrečios ribos ir suteikia jūsų komandai pagrįstą kitą žingsnį.
DUK
Ar sėkmingas žiniatinklio sąsajos atsakymas reiškia, kad naujausias įvykis sinchronizuotas?
Ne. Tai rodo, kad jūsų galinis taškas grąžino sėkmingą atsakymą į užklausą. Patvirtinkite, kad taip pat sėkmingai atlikta patikra, eilės apdorojimas, išsaugojimas duomenų bazėje ir rodymas. Patikrinkite naudingąjį krovinį, kad nustatytumėte, kokį įvykį apėmė užklausa.
Kodėl vežėjo puslapyje rodomas naujesnis nuskaitymas nei mano API atsakyme?
Pirmiausia patvirtinkite, kad žiūrite tą patį siuntinį ir kad abu stebėjimai atlikti panašiu metu. Vežėjo įvykio paskelbimas ir sekimo teikėjo jo gavimas arba pateikimas gali įvykti skirtingu metu. Jei skirtumas išlieka, naudodamiesi teikėjo dokumentacija ir pagalbos procesu ištirkite konkrečią siuntą, o ne manykite, kad atnaujinimas garantuojamas.
Ar naujausiai būsenai pasirinkti turėčiau naudoti įvykio laiko žymą ar laiką, kada ją gavo mano sistema?
Naudokite jūsų darbo eigai tinkamą dokumentuotą taisyklę ir išsaugokite abi reikšmes. Įvykio laiko žyma nurodo, kada įvyko pranešta veikla; gavimo laikas nurodo, kada jūsų sistema apie ją sužinojo. Nė vienas laukas atskirai neišsprendžia visų atvejų, ypač kai šaltinio laikai dviprasmiški arba ankstesni nuskaitymai gaunami pavėluotai.
Kas, jei API būsena nepasikeitė, bet įvykių sąraše atsirado naujas įrašas?
Tai gali būti tikėtina, jei keli vežėjo įvykiai susiejami su viena normalizuota būsena. Palyginkite įvykių informaciją ir patikrinkite, ar jūsų programa išsaugojo bei tinkamai rodo naują įrašą. Trūkstamą įvykį ir nepakitusią santraukos etiketę laikykite skirtingomis problemomis.
Šaltiniai
- 17TRACK sekimo API — produkto nuoroda sekimo API integracijoms.
- 17TRACK API dokumentacija — atskaitos taškas tikrinant taikomą integracijos sutartį.
- RFC 3339: data ir laikas internete: laiko žymos — laiko žymos ir UTC poslinkio formato nuoroda.


