Siuntimo API pristatymo būsena: būsenos kodai, žiniatinklio kabliukai ir įspėjimai apie išimtis

Pristatymo API pristatymo būsena apibūdina siuntos eigą, o ne tai, ar API užklausa buvo sėkminga. Norėdami sukurti patikimą sekimą, atskirkite HTTP atsako kodus nuo siuntų būsenų, apdorokite žiniatinklio kablius nemanydami, kad jie bus gauti vieną kartą ar nustatyta tvarka, o veiksmų reikalaujančias išimtis paverskite įspėjimais su aiškiai priskirtais atsakingais asmenimis. Inžinerijos ir elektroninės prekybos operacijų komandoms tikslas – siuntos įrašas, kuris išliktų patikimas, kai vežėjo atnaujinimai vėluoja, dubliuojasi ar yra pataisomi.

Šiame vadove paaiškinama, kaip struktūrizuoti tokį įrašą, apdoroti gaunamus sekimo įvykius ir atskirti pristatymo problemą nuo sekimo integracijos problemos.

Atskirkite HTTP kodus, API rezultatus ir siuntų būsenas

Frazė „būsenos kodas“ gali reikšti tris skirtingus sluoksnius. Juos supainiojus sukuriamos klaidinančios ataskaitų suvestinės ir siunčiami nereikalingi pranešimai klientams.

HTTP semantikos standartas apibrėžia HTTP atsakų reikšmes. Pavyzdžiui, 202 Accepted reiškia, kad užklausa priimta apdoroti, tačiau apdorojimas nebūtinai baigtas. Tai nėra įrodymas, kad vežėjas priėmė siuntą.

Taip pat nepavykusi sekimo užklausa neįrodo, kad siunta nustojo judėti. Jūsų programa gali laikinai prarasti matomumą, nors fizinis pristatymas vyksta įprastai. Stebėkite šiuos sluoksnius atskirai.

Sukurkite būsenų modelį neprarasdami vežėjo pateiktos informacijos

Nėra universalaus skaitinio pristatymo būsenos kodo, kurį naudotų kiekvienas pristatymo API ir vežėjas. Vienos integracijos reikšmė neturėtų būti aiškinama pagal kito teikėjo atvaizdavimą. Naudokite konkrečios įdiegtos API versijos dokumentaciją.

Praktiškas vidinis modelis sujungia nedidelį normalizuotų būsenų rinkinį su pirminiu vežėjo įvykiu. Normalizavimas užtikrina nuoseklias ataskaitas, o pirminis įvykis išsaugo tyrimui reikalingą išsamumą.

Šios etiketės yra siūlomas taikomosios programos modelis, o ne oficialus 17TRACK kodų sąrašas. Išsaugokite teikėjo būsenos kodą, antrinę būseną, aprašą, įvykio laiką, laiko juostos informaciją, vietą ir gavimo laiką, jei jie prieinami. Taip pat išsaugokite susiejimo versiją, kad vėlesnius susiejimo pakeitimus būtų galima audituoti.

Kelių vežėjų diegimui 17TRACK Tracking API yra tinkama integracijos parinktis. Naudokite jos official API documentation, kad nustatytumėte diegimo sutartį, o ne kopijuokite iliustracines etiketes į konkrečiam teikėjui skirtus laukus. Prieš kurdami adapterį patvirtinkite taikomas būsenų apibrėžtis, žiniatinklio kablių konfigūraciją, autentifikavimo reikalavimus ir atsako semantiką.

Sukurkite žiniatinklio kablių apdorojimą remdamiesi patikimu gavimu

Žiniatinklio kablys yra į jūsų galinį tašką siunčiama HTTP užklausa, skirta pranešti apie įvykį. Jis gali sumažinti pakartotinio apklausimo poreikį, tačiau neturėtų būti laikomas greito, nustatyta tvarka vykstančio ar tiksliai vieną kartą atliekamo pristatymo garantija. Sukurkite gaviklį taip, kad jis toleruotų pakartotinius bandymus, sutrikimus ir netikėtus duomenis, nebent teikėjas aiškiai garantuoja kitaip.

1. Autentifikuokite užklausą. Taikykite teikėjo dokumentuotą tikrinimo metodą. Jei palaikomi parašai, patikrinkite juos naudodami nurodytą algoritmą ir neapdorotus užklausos baitus. Neišgalvokite parašo antraštės ir nemanykite, kad kiekviena paslauga naudoja HMAC.
2. Patikrinkite duomenis. Patikrinkite privalomus laukus, tipus, duomenų dydį ir sąsają su siunta, kurią valdo jūsų paskyra. Nežinomus pasirenkamus laukus tvarkykite taip, kad be reikalo nebūtų pažeistas suderinamumas ateityje.
3. Išsaugokite prieš patvirtindami gavimą. Priimtą įvykį išsaugokite arba įdėkite į patvarią eilę prieš siųsdami dokumentuotą sėkmingą atsaką. Jei išsaugoti nepavyksta, nepatvirtinkite, kad įvykis saugiai gautas.
4. Apdorokite asinchroniškai. Kai praktiška, būsenų susiejimą, užsakymų atnaujinimus ir sprendimus dėl pranešimų vykdykite ne užklausos tvarkyklėje.
5. Šalutinius veiksmus atlikite idempotentiškai. Pakartotinis įvykis neturėtų sukurti kito pagalbos bilieto ar išsiųsti kitos to paties pranešimo kopijos klientui.

Tikslus patvirtinimo kodas, skirtasis laikas, pakartojimų grafikas ir pakartotinio paleidimo elgsena priklauso nuo teikėjo. Aiškiai patikrinkite šią informaciją. Bendras nurodymas „grąžinkite 200“ nepakeičia žiniatinklio kablio sutarties.

Naudokite HTTPS ir nelaikykite kredencialų URL bei įprastuose žurnaluose. Taikykite prieigos kontrolę saugomiems duomenims, nes sekimo duomenyse gali būti asmeninės informacijos. OWASP REST Security Cheat Sheet pateikia atitinkamas transporto apsaugos, įvesties tikrinimo ir galinių taškų saugumo gaires.

Dubliuokite įvykius jų neslopindami, kad nebūtų prarasti tikri atnaujinimai

Jei įmanoma, pirmenybę teikite dokumentuotam, stabiliam įvykio identifikatoriui. Kitu atveju sukurkite dublikatų šalinimo raktą iš kruopščiai parinkto siuntos tapatybės, įvykio laiko, įvykio kodo ir vietos derinio. Išbandykite šį metodą su tikrais duomenimis: du teisėti įvykiai gali turėti tą pačią laiko žymą, o tas pats įvykis gali būti gautas su šiek tiek kitokiu aprašomuoju tekstu.

Įvykių priėmimui ir tolesniems veiksmams naudokite atskirus dublikatų šalinimo valdiklius. Būsenos atnaujinimą gali reikėti išsaugoti dar kartą kaip pataisymą, o kliento pranešimas turėtų likti nuslopintas. Kiekvienam pranešimui ar bilieto veiksmui suteikite atskirą patvarią tapatybę.

Įvykio laiką laikykite atskirai nuo gavimo laiko

Tarkime, kad vežama siunta pasiekia jūsų sistemą po įvykio „ruošiama pristatyti“, tačiau jos vežėjo laiko žyma yra ankstesnė. Išsaugokite ją istorijoje, bet automatiškai nekeiskite dabartinės būsenos atgal į „vežama“.

Vien laiko žymų tvarkos nepakanka kiekvienu atveju. Trūkstamos laiko juostos, pataisyti nuskaitymai ir prieštaringi šaltiniai reikalauja aiškių taisyklių. Išsaugokite laiko žymų tikslumą ir poslinkius, registruokite, kada jūsų sistema gavo kiekvieną įvykį, ir, jei įmanoma, naudokite dokumentuotą teikėjo sekos informaciją. Nenustatykite griežtos tik į priekį einančių būsenų sekos: pristatymo bandymai, peradresavimai, grąžinimai ir pataisymai gali sukurti teisėtus perėjimus, kurie atrodo kaip grįžimas atgal.

Paverskite išimtis atsakingais veiksmais

Išimties įspėjime turėtų būti paaiškinta, kas įvyko, kokių veiksmų reikia ir kas atsakingas už kitą žingsnį. Bendras pranešimas „siuntos išimtis“ verčia veiklos darbuotojus kartoti tą patį tyrimą ir gali suneraminti klientus, jiems nepadėdamas.

Pradėkite nuo nedidelės nukreipimo politikos:

• Adreso arba prieigos problema: Nukreipkite į klientų aptarnavimą, kad problema būtų patikrinta ir išsiaiškinta vežėjo siūloma taisymo procedūra. Nežadėkite pakeisti adreso, kol nepatvirtinta, kad tai įmanoma.
• Reikalingas atsiėmimas: Praneškite gavėjui, kai šaltinis pateikia tinkamą atsiėmimo instrukciją. Išsaugokite patvirtintą terminą.
• Reikia muitinės veiksmų: Priskirkite atvejį pagal tai, kas turi pateikti prašomus dokumentus ar informaciją. Vien su muitine susijęs įvykis nereiškia, kad reikia mokėti.
• Nesėkmingas pristatymo bandymas: Prieš patardami dėl pakartotinio pristatymo ar atsiėmimo patikrinkite nurodytą kitą veiksmą.
• Grąžinama siuntėjui: Pradėkite veiklos peržiūrą. Negrąžinkite pinigų automatiškai vien dėl bendros sekimo etiketės, nebent jūsų politika tai aiškiai leidžia.
• Vežėjo praneštas praradimas arba žala: Nukreipkite į žalų nagrinėjimo atsakingą asmenį ir išsaugokite įvykio įrodymus. Žalų sprendimus laikykite atskirai nuo bendro vėlavimų nustatymo.

Kiekviename įspėjime turėtų būti siuntos identifikatorius, užsakymo nuoroda, įvykio priežastis, šaltinio laiko žyma, naujausia žinoma būsena, priskirtas atsakingas asmuo ir kitas veiksmas. Įtraukite nuorodą į atitinkamą vidinį įrašą, o ne atskleiskite nereikalingą klientų informaciją bendruose pranešimų kanaluose.

„Nėra atnaujinimo“ laikykite atskira būsena

Siunta, kurios nuskaitymas neseniai neatnaujintas, nebūtinai prarasta. Ji gali būti tarp kontrolės punktų, laukti pirmojo fizinio nuskaitymo arba būti paveikta matomumo spragos.

Neaktyvumo ribas apibrėžkite pagal paslaugą, maršrutą, pristatymo etapą ir verslo įsipareigojimą, o ne taikykite vieną universalų laikmatį. Atskirkite siuntą, kuriai niekada nebuvo atliktas priėmimo nuskaitymas, nuo siuntos, kurios atnaujinimai nutrūko jai patekus į tinklą. Jei istorinių įrodymų nedaug, naudokite ribą tyrimui pradėti, o ne praradimui paskelbti.

Slopinkite pasikartojančius įspėjimus, kol nepakitęs atvejis lieka atviras. Eskaluokite, kai atsiranda naujų įrodymų, praleidžiamas sutartas tolesnis veiksmas arba klientui įsipareigotas pristatymo terminas reikalauja įsikišimo.

Integracijos būklę stebėkite atskirai nuo pristatymo rezultatų

API stebėjimas parodo, ar jūsų sekimo integracija veikia. Pristatymo stebėjimas parodo, kas vyksta su siuntomis. Veikiantis galinis taškas gali gauti pasenusius vežėjo duomenis, o nepasiekiamas galinis taškas gali praleisti įprastai judančių siuntų atnaujinimus.

• Užklausų būklė: Stebėkite autentifikavimo klaidas, skirtąjį laiką, dažnio ribojimo atsakus, serverio klaidas ir taikomojo lygmens atmetimus.
• Žiniatinklio kablių būklė: Stebėkite tikrinimo klaidas, patvirtinimo delsą, išsaugojimo klaidas, pasikartojančius pristatymus ir apdorojimo klaidas.
• Apdorojimo būklė: Stebėkite eilės amžių, neapdorotus įvykius, susiejimo klaidas ir pranešimų klaidas.
• Sekimo aktualumas: Matuokite laiką nuo paskutinio šaltinio įvykio atskirai nuo laiko nuo paskutinio sėkmingo priėmimo.
• Veiklos rezultatai: Stebėkite neišspręstas išimtis, laiką iki atsakomybės priskyrimo ir pavėluotus tolesnius veiksmus.

Atlikdami pakartotines užklausas vadovaukitės teikėjo dažnio ribojimo ir pakartojimų gairėmis. Venkite aklai kartoti operacijų, kurios gali sukurti pasikartojančias registracijas ar kitus šalutinius veiksmus; jei įmanoma, naudokite dokumentuotus idempotentiškumo mechanizmus.

Jei palaikoma, naudokite sutikrinimo procesą naujausiam sekimo įrašui gauti po sutrikimų ar įtariamų praleistų įvykių. Nustatykite jo dažnį neviršydami sutartinių ir dažnio ribų. Žiniatinklio kabliai ir sutikrinimas atlieka skirtingas funkcijas: vienas pateikia pakeitimus, o kitas padeda aptikti ir ištaisyti spragas.

Prieš įjungdami klientų pranešimus išbandykite gedimų atvejus

Pradėkite nuo apdorojimo, skirto tik vidiniam naudojimui, ir patikrinkite reprezentatyvias siuntas prieš leisdami būsenų pakeitimams siųsti pranešimus klientams. Išbandykite ne tik įprastą eigą nuo „vežama“ iki „pristatyta“.

• Pasikartojantis žiniatinklio kablys sukuria vieną numatytą kliento pranešimą.
• Vėlai gautas senesnis įvykis neteisingai nepakeičia dabartinės būsenos.
• Nežinoma būsena išsaugoma ir pažymima, o ne tyliai susiejama su „pristatyta“.
• Nesėkmingas patvarus įrašymas nesukuria sėkmingo patvirtinimo.
• Laikinas tolesnės sistemos sutrikimas palieka įvykius prieinamus pakartotiniam bandymui.
• Po pristatyto įvykio gautas pataisymas lieka audituojamas.
• Kelių siuntų užsakymas netampa visiškai pristatytu, kai pristatyta tik viena siunta.
• API sutrikimas įspėja inžinerijos komandą, automatiškai nepranešdamas klientams, kad jų siuntos vėluoja.

Išleidimo kriterijus turėtų būti veiklos nuoseklumas: siuntos įrašas, pranešimas klientui ir pagalbos veiksmas turi atitikti tuos pačius pagrindinius įrodymus. Vien sėkmingas žiniatinklio kablio atsakas neįrodo, kad pristatymo patirtis veikia.

DUK

Ar HTTP 200 reiškia, kad paketas pristatytas?

Ne. Jis nurodo HTTP lygmens užklausos sėkmę. API verslo rezultatą ir siuntos būsenos laukus skaitykite atskirai. Žiniatinklio kablio atveju sėkmingas patvirtinimas susijęs su pranešimo gavimu, o ne su fiziniu siuntos pristatymu.

Ar sekimo atnaujinimams turėčiau naudoti žiniatinklio kablius, ar apklausą?

Naudokite žiniatinklio kablius įvykiais pagrįstiems atnaujinimams, kai teikėjas juos palaiko. Jei palaikoma ir veiklos požiūriu pagrįsta, pridėkite ribotą sutikrinimo apklausą spragoms atkurti. Vien apklausa gali būti tinkama, kai žiniatinklio kabliai nepasiekiami, tačiau jos dažnis turi atitikti teikėjo ribas ir jūsų aktualumo reikalavimus.

Kodėl sekimo būsena gali pasikeisti po būsenos „pristatyta“?

Šaltinis gali pataisyti įvykį arba jūsų integracija gali gauti pavėluotą ar prieštaringą informaciją. Išsaugokite istoriją ir įvertinkite naujesnius įrodymus, o ne laikykite „pristatyta“ techniškai nekintama. Nurodytas pristatymas ir kliento patvirtinimas, kad siunta gauta, taip pat yra skirtingi faktai.

Kaip greitai turėtų būti siunčiamas išimties įspėjimas?

Skubumą nustatykite pagal reikalingą veiksmą ir patvirtintą terminą. Problema, dėl kurios reikia gavėjo veiksmų, turi būti tvarkoma kitaip nei informacinis vėlavimas. Apdorojimo greitis negali kompensuoti vėlai paskelbto vežėjo įvykio, todėl išsaugokite ir šaltinio, ir gavimo laiko žymas.

Ar klientai turėtų matyti neapdorotą vežėjo būseną?

Paprastai klientams naudingesnis aiškus paaiškinimas ir pagrįstas kitas veiksmas nei nepaaiškintas kodas. Neapdorotą informaciją išsaugokite pagalbos ir audito tikslais. Niekada nesupaprastinkite būsenos į stipresnį pažadą, nei leidžia pagrindinis įvykis.

Šaltiniai

• RFC 9110: HTTP Semantics — HTTP būsenos kodų reikšmių, įskaitant 200 ir 202, nuoroda.
• OWASP REST Security Cheat Sheet — API ir žiniatinklio kablių galiniams taškams aktualios saugumo gairės.
• 17TRACK Tracking API — oficiali aptariamos sekimo integracijos parinkties produkto nuoroda.
• 17TRACK API Documentation — oficiali teikėjo integracijos reikalavimų nuoroda; šiame vadove pateiktos iliustracinės schemos ir darbo eigos rekomendacijos nepakeičia šios sutarties.