Stebėjimo API klaidų tvarkymas: kaip valdyti netinkamus stebėjimo numerius, užklausų dažnio ribojimus ir pakartotinius bandymus

Spręskite sekimo API klaidas atskirdami netinkamą įvestį, laikinus sutrikimus, užklausų dažnio ribojimus ir siuntų būsenų rezultatus. Atmeskite arba pataisykite netinkamus sekimo numerius, užuot pakartotinai siuntę juos nepakeistus, koordinuokite užklausų apimtį, kai taikomas ribojimas, ir pakartokite laikinai nepavykusias užklausas naudodami ribotą eksponentinį laukimo laiką su atsitiktiniu vėlinimu. Prieš kartodami registraciją ar kitą įrašymo užklausą nustatykite, ar pirmasis bandymas buvo sėkmingas.

Kūrėjams, jungiantiems sekimo duomenis su užsakymų valdymo sistema, sandėlio platforma ar klientams skirtu sekimo puslapiu, tikslas nėra vien sumažinti nepavykusių užklausų skaičių. Tikslas – užtikrinti patikimą siuntų matomumą be pasikartojančių registracijų, pakartotinių užklausų šuolių, klaidinančių pristatymo pranešimų ar nereikalingų užklausų palaikymo tarnybai.

Prieš pasirinkdami atsaką suklasifikuokite sutrikimą

Sekimo integracijoje reikia įvertinti kelis atskirus rezultatus: ar tinklo užklausa buvo užbaigta, ar API priėmė operaciją, ar kiekvienas prašytas sekimo elementas buvo apdorotas sėkmingai ir ar yra siuntos įvykių. Laikant visus keturis aspektus viena sėkmės arba nesėkmės vėliavėle, sukuriama išvengiamų klaidų.

Sėkmingas HTTP atsakas nebūtinai reiškia, kad kiekvienas paketo elementas buvo apdorotas sėkmingai. Atvirkščiai, sėkmingai apdorota paieška, kai nėra sekimo įvykių, nebūtinai reiškia API klaidą. Patikrinkite atsako turinį ir pritaikykite dokumentacijoje nurodytą teikėjo kiekvieno rezultato reikšmę.

HTTP būsenos kodai yra pradinis taškas, o ne visas konkrečiam teikėjui taikomų sprendimų medis. RFC 9110 apibrėžia HTTP semantiką, o RFC 6585 apibrėžia 429 Too Many Requests. Jūsų integracija taip pat turėtų interpretuoti dokumentacijoje nurodytus taikomųjų programų klaidų kodus ir elementų lygmens rezultatus.

Netinkami sekimo numeriai: atskirkite blogą įvestį nuo trūkstamų įvykių

„Netinkamas sekimo numeris“ gali reikšti skirtingas problemas: netinkamai suformuotą identifikatorių, nepalaikomą kurjerio ir numerio derinį, trūkstamą privalomą kurjerio lauką ar kitą konkrečiam teikėjui būdingą patvirtinimo klaidą. Nemanykite, kad numeris netinkamas vien todėl, kad negrąžinami sekimo įvykiai.

Patvirtinkite nepažeisdami identifikatoriaus

• Saugokite sekimo numerius kaip eilutes. Skaitmeninis saugojimas gali pašalinti pradinius nulius arba pakeisti ilgus identifikatorius.
• Išsaugokite pradinę įvestį. Laikykite atskirą normalizuotą reikšmę, kad pakeitimus būtų galima audituoti.
• Normalizuokite atsargiai. Jei reikia, pašalinkite aplinkinius tarpus, tačiau vidinius simbolius šalinkite arba raidžių registrą keiskite tik tada, kai tai leidžia dokumentuotos taisyklės.
• Vietoje patikrinkite privalomus laukus. Prieš siųsdami užklausas aptikite tuščius numerius, trūkstamus kurjerių identifikatorius ir netinkamą užklausos struktūrą.
• Venkite universalaus sekimo numerio reguliariojo reiškinio. Vienam kurjeriui sukurta taisyklė gali atmesti kito kurjerio galiojančius identifikatorius.
• Patvirtinkite, kas yra lauke. Užsakymo numeris, sandėlio nuoroda ir kurjerio sekimo numeris nėra tarpusavyje keičiami, nebent galinis taškas juos aiškiai palaiko.

Jei API aiškiai atmeta įvestį, nukreipkite ją taisyti, o ne į automatinio pakartojimo ciklą. Pateikite naudingą priežastį, pavyzdžiui, „reikalingas kurjerio identifikatorius“, užuot kiekvieną patvirtinimo problemą sumažinę iki „sekimas nepavyko“.

Traktuokite „nėra įvykių“ kaip atskirą būseną

Siunta gali turėti sekimo identifikatorių dar prieš atsirandant naudingiems judėjimo įvykiams. Tinkamas atsakas priklauso nuo dokumentuoto API būsenų modelio ir siuntos aplinkybių. Patikrinkite, ar identifikatorius gautas iš siuntimo sistemos, ar tinkamai pasirinktas kurjeris ir ar atsakas nurodo laukiančius duomenis, o ne atmestą įvestį.

Naudokite atskiras vidines būsenas, pavyzdžiui, input_rejected, awaiting_events ir temporarily_unavailable. Tai siūlomos taikomosios programos būsenos, o ne standartizuotos API reikšmės. Jos padeda neleisti, kad laikinas duomenų trūkumas virstų netiksliu pranešimu klientui.

Valdykite užklausų dažnio ribojimus visoje integracijoje, o ne kiekviename darbuotoje

RFC 6585 apibrėžia HTTP 429 kaip užklausų dažnio ribojimo atsaką ir leidžia jame pateikti Retry-After antraštę. Standartas nenustato universalaus sekimo API limito ar skaičiavimo metodo. Ribojimai gali būti dokumentuoti paskyros, kredencialo, galinio taško ar kitu lygiu; naudokite faktines teikėjo taisykles.

RFC 9110 nurodo dvi Retry-After formas: neneigiamą sekundžių skaičių arba HTTP datą. Išanalizuokite abi. Jei reikšmė yra data, kruopščiai apskaičiuokite likusį laukimo laiką ir atsižvelkite į laikrodžių skirtumus. Jei jos nėra arba ji netinkama, taikykite sukonfigūruotą atsarginę laukimo politiką.

Vieno darbuotojo miego nepakanka, kai kiti darbuotojai toliau naudoja tą pačią kvotą. Nustatykite dažnio kontrolę bendrame atitinkamo kredencialo ar paskyros taške. Centrinis planuoklis, bendra žetonų saugykla ar lygiavertė paskirstyta kontrolė gali koordinuoti šį srautą.

1. Nustatykite paveiktą sritį. Išsiaiškinkite, kuriam galiniam taškui, kredencialui ar paskyrai taikomas limitas.
2. Laikykitės serverio nurodyto laukimo. Neplanuokite ankstesnio pakartojimo, nei leidžia galiojanti Retry-After reikšmė.
3. Atidėkite paveiktus eilėje esančius darbus. Neužblokuokite nesusijusio srauto, kai ribojimai iš tiesų nepriklausomi.
4. Sumažinkite lygiagretumą arba užklausų dažnį. Vienkartinis laukimas nepakeitus užklausų modelio gali sukelti tą pačią problemą.
5. Tęskite su tarpais. Pasibaigus laukimo laikui neatleiskite viso laukiančio darbo vienu metu.

Kai palaikoma, paketų naudojimas gali sumažinti užklausų skaičių, tačiau turi atitikti dokumentuotas paketo dydžio ir apskaitos taisykles. Nemanykite, kad vienas paketas sunaudoja vieną kvotos vienetą. Taip pat, jei galima, naudokite saityno kablius, kad sumažintumėte išvengiamą apklausą, tačiau išlaikykite integracijai reikalingą sutikrinimo procesą.

Naudokite ribotus pakartojimus su laukimo laiku ir atsitiktiniu vėlinimu

Pakartojimai yra tinkami, kai sutrikimas gali išnykti nepakeitus užklausos ir saugu pakartoti operaciją. Laikini ryšio sutrikimai ir kai kurios serverio klaidos gali priklausyti šiai kategorijai. Netinkamas turinys, netinkamas kredencialas ar nuolatinė leidimų problema paprastai reikalauja pataisymo.

Praktiškas atsarginis variantas yra apribotas eksponentinis laukimo laikas su visišku atsitiktiniu vėlinimu:

backoff_window = min(max_delay, base_delay * 2^retry_index)
jitter_delay = random(0, backoff_window)
next_delay = max(valid_retry_after_delay, jitter_delay)

Čia retry_index pirmajam pakartojimui prasideda nuo nulio, o nesant Retry-After papildomas minimalus laukimas netaikomas. Tai yra įgyvendinimo pasirinkimai, o ne privalomas HTTP algoritmas. Pasirinkite bazinį delsos laiką, ribą, bandymų skaičių ir bendrą terminą pagal savo darbo krūvį bei teikėjo rekomendacijas.

Atsitiktinis vėlinimas paskirsto užklausas laike, užuot leidęs kiekvienam darbuotojui jas kartoti tuo pačiu grafiku. Delsos riba apriboja eksponentinę dalį; ji neturėtų pakeisti ilgesnio galiojančio serverio nurodyto laukimo. Jei šis laukimas viršija darbo terminą, atidėkite arba nutraukite darbą pagal politiką, o ne kartokite anksčiau.

Kiekvienai pakartojimų grandinei nustatykite pabaigą

• Bandymų limitas: apribokite papildomų užklausų skaičių.
• Praėjusio laiko limitas: nustokite kartoti darbą, kuris viršijo naudingą apdorojimo laiką.
• Aiški atsakomybė: pasirinkite, kuris sluoksnis valdo pakartojimus, kad HTTP kliento ir eilės pakartojimai netikėtai nesidaugintų.
• Patikimas planavimas: saugokite atidėtus darbus, o ne pasikliaukite ilgu laukimu trumpalaikiuose procesuose.
• Atkūrimo kelias: išsekusius darbus siųskite į peržiūrai skirtą nepavykusių darbų eilę, nurodydami priežastį ir kitą veiksmą.

Užsitęsusio sutrikimo metu apsvarstykite grandinės nutraukiklį, kuris laikinai pristabdo įprastus iškvietimus ir leidžia kontroliuojamus atkūrimo patikrinimus. Tai taikomųjų programų atsparumo modelis, o ne įrodymas, kad jo reikalauja konkretus sekimo teikėjas.

Prieš siųsdami iš naujo išspręskite neaiškių įrašymų situaciją

Skirtojo laiko pabaiga reiškia, kad jūsų programa negavo viso atsako. Tai neįrodo, kad serveris atmetė arba niekada neapdorojo užklausos. Šis skirtumas svarbus registruojant sekimo numerius ar keičiant sekimo konfigūraciją.

RFC 9110 paaiškina idempotentinius metodus ir įspėja automatiškai nekartoti neidempotentinių užklausų, jei nėra pagrindo žinoti, kad kartojimas saugus arba kad pradinė operacija nebuvo pritaikyta. Įvertinkite dokumentuotą operacijos semantiką, o ne manykite, kad kiekvienas sekimo galinis taškas veikia kaip tik skaitymui skirta paieška.

• Jei galima, naudokite teikėjo dokumentuotą idempotentiškumo mechanizmą, laikydamiesi jo apimties ir saugojimo taisyklių.
• Tos pačios loginės operacijos pakartojimams naudokite tą patį idempotentiškumo raktą; nemanykite, kad bus atsižvelgta į bet kurią pasirinktinę antraštę.
• Jei palaikoma, prieš kartodami neaiškų įrašymą patikrinkite esamą registraciją.
• Naudokite vietinį unikalumo apribojimą, suderintą su dokumentuota teikėjo siuntos tapatybe.
• Išsaugokite operacijos rezultatą, kad pakartotinis eilės pristatymas automatiškai nesukeltų dar vieno įrašymo.

Atliekant paketines operacijas, išsaugokite kiekvieno elemento rezultatą. Kartokite tik elementus, priskirtus laikinai nepavykusiems, o elementus, kurių rezultatas lieka nežinomas, sutikrinkite. Pakartotinai paleidus visą paketą galima kartoti sėkmingą darbą ir be reikalo sunaudoti užklausų kvotą.

Pritaikykite politiką savo sekimo teikėjui

17TRACK integracijai naudokite Tracking API puslapį ir oficialią API dokumentaciją kaip pradinį tašką konkrečiam teikėjo susitarimui. Klaidų klasifikatorių konfigūruokite, o ne įtvirtinkite bendro HTTP vadovo prielaidas.

Prieš įgyvendindami patvirtinkite atitinkamo galinio taško užklausos schemą, atsako apvalkalą, elementų lygmens klaidų reikšmes, užklausų dažnio ribojimo sritį, paketų apribojimus ir pasikartojančių pateikimų taisykles. Jei naudojate įvykių pristatymą, taip pat patikrinkite patvirtinimo, autentifikavimo ir pakartotinio pristatymo reikalavimus. Šis vadovas nenustato skaitinio 17TRACK dažnio limito, pakartojimų grafiko ar idempotentiškumo funkcijos.

Kiekvieną patvirtintą taisyklę užrašykite susiejime nuo teikėjo atsako iki taikomojo veiksmo: pataisyti įvestį, sutvarkyti konfigūraciją, palaukti, sutikrinti arba eskaluoti. Neatpažinta klaida turėtų išsaugoti diagnostinį kontekstą ir vadovautis ribotu atsarginiu keliu, o ne pagal nutylėjimą kartotis neribotai.

Stebėkite atkūrimo kokybę ir testuokite sutrikimų kelius

Registruokite operaciją, galinį tašką, HTTP būseną, taikomosios programos klaidos kodą, bandymo numerį, delsą, kitą suplanuotą veiksmą ir, jei pateiktas, teikėjo užklausos identifikatorių. Venkite įrašyti API raktus, nereikalingą adresų informaciją ar neribotus atsako turinius. Kai nereikalingos visos reikšmės, sekimo identifikatorius maskuokite arba maišykite.

Atskirai stebėkite netinkamos įvesties dažnį, ribojimą, eilės amžių, išsekusius pakartojimus ir paskutinį sėkmingą sinchronizavimą. Integracijoje gali būti mažas HTTP klaidų dažnis, tačiau siuntų informacija vis tiek gali būti pasenusi. Klientams skirti puslapiai turėtų išsaugoti paskutinę žinomą siuntos būseną ir atskirti atnaujinimo nesėkmę nuo kurjerio praneštos pristatymo išimties.

Prieš išleidimą ištestuokite netinkamą įvestį, galiojančius identifikatorius be įvykių, abi Retry-After formas, trūkstamas antraštes, dalines paketų klaidas, skirtojo laiko pabaigą po įrašymų ir pakartotinį eilės pristatymą. Taip pat imituokite pakankamai ilgą sutrikimą, kad būtų išnaudotas pakartojimų biudžetas. Testas sėkmingas tik tada, kai darbas nuspėjamai sustabdomas arba atidedamas, sėkmingi elementai be reikalo nekartojami, o nepavykę elementai lieka atkuriami.

DUK

Ar netinkamą sekimo numerį reikia automatiškai kartoti?

Ne, kai API aiškiai atmeta įvestį kaip netinkamą. Pirmiausia pataisykite numerį, kurjerio pasirinkimą arba privalomus laukus. Jei atsakas reiškia, kad siuntos įvykiai dar nepasiekiami, naudokite dokumentuotą atnaujinimo eigą, o ne laikykite tai patvirtinimo klaida.

Ar HTTP 200 reiškia, kad paketo užklausa visiškai sėkminga?

Nebūtinai. Patikrinkite teikėjo atsako schemą, ar joje pateikiami operacijos ir elementų lygmens rezultatai. Išsaugokite sėkmingus rezultatus ir atskirkite klaidas, kad kartojant vieną elementą nereikėtų kartoti viso likusio paketo.

Kiek pakartotinių bandymų turėtų leisti sekimo integracija?

Universalaus skaičiaus nėra. Nustatykite ir bandymų limitą, ir praėjusio laiko biudžetą, atsižvelgdami į teikėjo rekomendacijas, operacijos saugumą ir tai, kiek laiko rezultatas išlieka naudingas. Suplanuota foninė sinchronizacija gali toleruoti kitokį atkūrimo laiką nei interaktyvi kliento užklausa.

Ar pasibaigus užklausos laikui siuntą reikia iškart pažymėti kaip nepavykusią?

Ne. Užklausos laiko pabaiga yra integracijos rezultatas, o ne siuntos įvykis. Išsaugokite paskutinę žinomą sekimo būseną, suplanuokite saugų atkūrimą ir nepaverskite ryšio problemos pranešimu apie nepavykusį pristatymą.

Kas turėtų nutikti išnaudojus visus pakartojimus?

Perkelkite darbą į patikimą nepavykusių darbų arba peržiūros eilę kartu su diagnostiniu kontekstu. Nustatykite, ar atkūrimui reikia pataisyti įvestį, atkurti kredencialus, kreiptis į teikėją ar vėliau kontroliuojamai paleisti iš naujo. Neatmeskite darbo tyliai ir nepradėkite to paties neriboto pakartojimų ciklo.

Šaltiniai

• RFC 9110: HTTP Semantics — HTTP būsenų semantika, idempotentiniai metodai, automatinio pakartojimo aspektai ir Retry-After laukas.
• RFC 6585: Additional HTTP Status Codes — 429 Too Many Requests apibrėžimas ir pasirinktinė Retry-After antraštė.
• 17TRACK Tracking API — oficialus sekimo API produkto pradinis puslapis.
• 17TRACK API documentation — nuoroda, skirta konkretiems teikėjo integracijos reikalavimams tikrinti.