Obravnavanje napak API-ja za sledenje: Kako upravljati neveljavne številke za sledenje, omejitve hitrosti in ponovne poskuse

Napake API-ja za sledenje obravnavajte tako, da ločite neveljaven vnos, začasne napake, omejitve hitrosti in rezultate statusa pošiljke. Neveljavne številke za sledenje zavrnite ali popravite, namesto da bi jih nespremenjene ponovno pošiljali, pri omejitvah hitrosti uskladite obseg zahtevkov ter začasne napake ponovite z omejenim eksponentnim umikom in naključnim zamikom. Pred ponovitvijo registracije ali druge zahteve za zapis preverite, ali je bil prvi poskus uspešen.

Za razvijalce, ki podatke o sledenju povezujejo s sistemom za upravljanje naročil, skladiščno platformo ali stranjo za sledenje, namen ni le manj neuspešnih zahtevkov. Cilj je zanesljiva vidljivost pošiljk brez podvojenih registracij, neobvladljivih valov ponovnih poskusov, zavajajočih sporočil o dostavi ali nepotrebnih zahtevkov za podporo.

Pred izbiro odziva razvrstite napako

Integracija sledenja ima več ločenih izidov, ki jih je treba oceniti: ali je bila omrežna zahteva dokončana, ali je API sprejel operacijo, ali je bil vsak zahtevani element sledenja uspešen in ali so dogodki pošiljke na voljo. Obravnavanje vseh štirih kot ene same zastavice uspeha ali neuspeha povzroča napake, ki bi se jim bilo mogoče izogniti.

Uspešen odgovor HTTP ne pomeni nujno, da je bil vsak element v paketu uspešen. Nasprotno pa uspešno obdelano iskanje brez dogodkov sledenja ni nujno napaka API-ja. Preglejte telo odgovora in za vsak rezultat uporabite dokumentirani pomen ponudnika.

Pogoj	Priporočeno dejanje	Ponoviti nespremenjeno?
Napačno oblikovana številka ali neveljavno polje zahteve	Preverite in popravite vnos	Ne
Manjkajoči ali neveljavni poverilni podatki	Preverite poverilne podatke, dovoljenja in okolje	Šele po popravku
Odgovor z omejitvijo hitrosti	Odložite prizadeto delo in zmanjšajte skupni pritisk zahtev	Po zahtevanem čakanju, če je varno
Začasna napaka storitve	Uporabite omejeni umik in preverite varnost operacije	Običajno, znotraj proračuna ponovitev
Časovna omejitev po oddaji registracije	Uskladite, ali registracija obstaja	Ne slepo
Sprejeto iskanje brez dogodkov pošiljke	Upoštevajte dokumentirani življenjski cikel sledenja	Uporabite načrtovano osveževanje, ne hitrih ponovitev

Statusne kode HTTP so izhodišče, ne popolno drevo odločanja za posameznega ponudnika. RFC 9110 opredeljuje semantiko HTTP, RFC 6585 pa opredeljuje 429 Too Many Requests. Vaša integracija mora razlagati tudi dokumentirane aplikacijske kode napak in rezultate na ravni posameznih elementov.

Neveljavne številke za sledenje: ločite napačen vnos od manjkajočih dogodkov

»Neveljavna številka za sledenje« lahko opisuje različne težave: napačno oblikovan identifikator, nepodprto kombinacijo prevoznika in številke, manjkajoče zahtevano polje prevoznika ali drugo preverjanje, značilno za ponudnika. Ne predpostavljajte, da je številka neveljavna samo zato, ker niso vrnjeni nobeni dogodki sledenja.

Preverjajte, ne da bi poškodovali identifikator

• Številke za sledenje shranjujte kot nize. Številčno shranjevanje lahko odstrani začetne ničle ali spremeni dolge identifikatorje.
• Ohranite izvirni vnos. Hranite ločeno normalizirano vrednost, da bodo pretvorbe preverljive.
• Normalizirajte previdno. Po potrebi odstranite okoliške presledke, vendar notranje znake odstranite ali velikost črk spremenite le, kadar to dovoljujejo dokumentirana pravila.
• Lokalno preverite zahtevana polja. Pred pošiljanjem zaznajte prazne številke, manjkajoče identifikatorje prevoznika in neveljavne oblike zahtev.
• Izogibajte se univerzalnemu regularnemu izrazu za številke sledenja. Pravilo, zasnovano za enega prevoznika, lahko zavrne veljavne identifikatorje drugega.
• Potrdite vsebino polja. Številka naročila, skladiščna referenca in številka za sledenje prevoznika niso zamenljive, razen če jih končna točka izrecno podpira.

Če API izrecno zavrne vnos, ga usmerite v popravek namesto v samodejno zanko ponovitev. Vključite uporaben razlog, na primer »zahtevan identifikator prevoznika«, namesto da bi vsako težavo pri preverjanju zmanjšali na »sledenje ni uspelo«.

»Brez dogodkov« obravnavajte kot ločeno stanje

Pošiljka ima lahko identifikator za sledenje, še preden so na voljo uporabni dogodki premikov. Pravilen odziv je odvisen od dokumentiranega modela statusov API-ja in konteksta pošiljke. Preverite, ali je identifikator prišel iz sistema za pošiljanje, ali je izbira prevoznika pravilna in ali odgovor kaže na čakajoče podatke namesto na zavrnjen vnos.

Uporabite ločena notranja stanja, kot so input_rejected, awaiting_events in temporarily_unavailable. To so predlagana aplikacijska stanja, ne standardizirane vrednosti API-ja. Pomagajo preprečiti, da bi začasna vrzel v podatkih postala netočno sporočilo stranki.

Omejitve hitrosti upravljajte na ravni integracije, ne posameznega delavca

RFC 6585 opredeljuje HTTP 429 kot odgovor z omejitvijo hitrosti in dovoljuje vključitev glave Retry-After. Standard ne določa univerzalne omejitve ali načina štetja za API-je za sledenje. Omejitve so lahko dokumentirane po računu, poverilnem podatku, končni točki ali drugem obsegu; uporabite dejanska pravila ponudnika.

RFC 9110 določa dve obliki za Retry-After: nenegativno število sekund ali datum HTTP. Razčlenite obe obliki. Če je vrednost datum, previdno izračunajte preostali čas čakanja in upoštevajte razlike med urami. Če manjka ali je neuporabna, uporabite konfigurirano nadomestno politiko umika.

Ko en delavec spi, to ni dovolj, če drugi delavci še naprej uporabljajo isti dovoljeni obseg. Nadzor hitrosti postavite na skupno mejo za ustrezni poverilni podatek ali račun. Osrednji razporejevalnik, skupna vedra žetonov ali enakovreden porazdeljeni nadzor lahko uskladijo ta promet.

1. Določite prizadeti obseg. Ugotovite, za katero končno točko, poverilni podatek ali račun velja omejitev.
2. Upoštevajte navodilo strežnika glede čakanja. Ne načrtujte ponovitve prej, kot to dovoljuje veljavna vrednost Retry-After.
3. Odložite prizadeto delo v čakalni vrsti. Izognite se blokiranju nepovezanega prometa, kadar so omejitve res neodvisne.
4. Zmanjšajte sočasnost ali pogostost zahtev. Enkratno čakanje brez spremembe vzorca zahtev lahko znova povzroči isto težavo.
5. Nadaljujte z razmiki. Ko se čakanje konča, ne sprostite celotnega zaostanka hkrati.

Kjer je podprto, lahko paketno pošiljanje zmanjša število zahtev, vendar mora upoštevati dokumentirana pravila glede velikosti paketov in obračunavanja. Ne predpostavljajte, da en paket porabi eno enoto dovoljenega obsega. Prav tako uporabite spletne kavlje, kjer so na voljo, da zmanjšate nepotrebno preverjanje, pri tem pa ohranite postopek usklajevanja, ki ga zahteva vaša integracija.

Uporabite omejene ponovitve z umikom in naključnim zamikom

Ponovitve so primerne, kadar se napaka lahko odpravi brez spremembe zahteve in je ponovitev operacije varna. Začasne napake povezave in izbrane napake strežnika lahko spadajo v to kategorijo. Napačno oblikovana vsebina, neveljaven poverilni podatek ali trajna težava z dovoljenji običajno zahteva popravek.

Praktična nadomestna možnost je omejeni eksponentni umik s popolnim naključnim zamikom:

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)

Tukaj se retry_index za prvi ponovni poskus začne z nič, manjkajoči Retry-After pa ne doda minimalnega čakanja. To so izvedbene odločitve, ne zahtevan algoritem HTTP. Osnovni zamik, omejitev, število poskusov in skupni rok izberite glede na svojo delovno obremenitev in navodila ponudnika.

Naključni zamik razporedi zahteve skozi čas, namesto da bi jih vsak delavec ponovil po istem urniku. Omejitev zamika omejuje eksponentno komponento; ne sme preglasiti daljšega, veljavnega čakanja, ki ga zahteva strežnik. Če to čakanje presega rok opravila, opravilo odložite ali končajte v skladu s politiko, namesto da bi ga ponovili prezgodaj.

Vsaki verigi ponovitev določite končno točko

• Omejitev poskusov: omejite število dodatnih zahtev.
• Omejitev pretečenega časa: prenehajte ponavljati delo, ki je preseglo svoje koristno časovno okno obdelave.
• Izrecno lastništvo: izberite plast, ki nadzoruje ponovitve, da se ponovitve odjemalca HTTP in čakalne vrste nepričakovano ne pomnožijo.
• Trajno razporejanje: shranjujte odložena opravila, namesto da bi se zanašali na dolga spanja v kratkoživih procesih.
• Pot obnovitve: izčrpana opravila pošljite v pregledljivo čakalno vrsto neuspelih opravil z razlogom in naslednjim dejanjem.

Med dolgotrajnim izpadom razmislite o odklopniku, ki začasno zaustavi rutinske klice in dovoljuje nadzorovane preizkuse obnovitve. To je vzorec odpornosti aplikacije in ni dokaz, da ga zahteva kateri koli določen ponudnik sledenja.

Pred ponovnim pošiljanjem razrešite dvoumne zapise

Časovna omejitev pomeni, da vaša aplikacija ni prejela popolnega odgovora. Ne dokazuje, da je strežnik zahtevo zavrnil ali je sploh ni obdelal. Ta razlika je pomembna pri registraciji številk za sledenje ali spreminjanju konfiguracije sledenja.

RFC 9110 pojasnjuje idempotentne metode in opozarja pred samodejnim ponavljanjem neidempotentnih zahtev brez podlage za ugotovitev, da je ponovitev varna ali da prvotna operacija ni bila izvedena. Ocenite dokumentirano semantiko operacije in ne predpostavljajte, da se vsaka končna točka za sledenje obnaša kot iskanje, ki je samo za branje.

• Kadar je na voljo, uporabite mehanizem idempotentnosti, ki ga dokumentira ponudnik, ter upoštevajte njegova pravila obsega in hrambe.
• Za ponovitve iste logične operacije ohranite isti ključ idempotentnosti; ne predpostavljajte, da bo poljuben glavi po meri upoštevan.
• Če je podprto, pred ponovitvijo dvoumnega zapisa preverite obstoječo registracijo.
• Uporabite lokalno omejitev enoličnosti, usklajeno z dokumentirano identiteto pošiljke ponudnika.
• Shranite izid operacije, da ponovna dostava iz čakalne vrste samodejno ne sproži novega zapisa.

Pri paketnih operacijah shranite rezultat vsakega elementa. Ponovite le elemente, razvrščene kot začasno neuspešne, in uskladite elemente, katerih izidi ostajajo neznani. Ponovno predvajanje celotnega paketa lahko ponovi uspešno delo in po nepotrebnem porabi dovoljeni obseg zahtev.

Politiko uporabite pri svojem ponudniku sledenja

Za integracijo 17TRACK uporabite stran Tracking API in uradno dokumentacijo API-ja kot izhodišče za pogodbo, značilno za ponudnika. Klasifikator napak naj bo nastavljiv, namesto da bi trdo kodirali predpostavke iz splošnega vodnika HTTP.

Pred izvedbo potrdite shemo zahtev ustrezne končne točke, ovojnico odgovora, pomene napak na ravni elementov, obseg omejitve hitrosti, omejitve paketov in pravila za podvojene oddaje. Če uporabljate dostavo dogodkov, preverite tudi zahteve glede potrditve, preverjanja pristnosti in ponovne dostave. Ta vodnik ne določa številčne omejitve hitrosti 17TRACK, urnika ponovitev ali funkcije idempotentnosti.

Vsako potrjeno pravilo zabeležite v preslikavi od odgovora ponudnika do dejanja aplikacije: popravi vnos, popravi konfiguracijo, počakaj, uskladi ali stopnjuj. Neprepoznana napaka mora ohraniti diagnostični kontekst in slediti omejeni nadomestni poti, ne pa privzeto uporabljati neomejenih ponovitev.

Spremljajte kakovost obnovitve in preizkusite poti napak

Zabeležite operacijo, končno točko, status HTTP, aplikacijsko kodo napake, številko poskusa, zakasnitev, naslednje načrtovano dejanje in identifikator zahteve ponudnika, kadar je posredovan. Izogibajte se beleženju ključev API-ja, nepotrebnih podatkov o naslovu ali neomejenih teles odgovorov. Identifikatorje sledenja zakrijte ali zgostite, kadar njihove polne vrednosti niso potrebne.

Ločeno spremljajte stopnje neveljavnih vnosov, omejevanje, starost čakalne vrste, izčrpane ponovitve in zadnjo uspešno sinhronizacijo. Integracija ima lahko nizko stopnjo napak HTTP, hkrati pa še vedno prikazuje zastarele informacije o pošiljkah. Strani, namenjene strankam, morajo ohraniti zadnji znani status pošiljke in razlikovati med neuspešnim osveževanjem ter izjemo pri dostavi, ki jo je sporočil prevoznik.

Pred izdajo preizkusite napačno oblikovan vnos, veljavne identifikatorje brez dogodkov, obe obliki Retry-After, manjkajoče glave, delne napake paketov, časovne omejitve po zapisih in ponovno dostavo iz čakalne vrste. Simulirajte tudi izpad, ki traja dovolj dolgo, da se proračun ponovitev izčrpa. Preizkus je uspešen le, ko se delo predvidljivo ustavi ali odloži, uspešni elementi niso po nepotrebnem ponovno predvajani in neuspešni elementi ostanejo obnovljivi.

Pogosta vprašanja

Ali je treba neveljavno številko za sledenje samodejno ponoviti?

Ne, kadar API izrecno zavrne vnos kot neveljaven. Najprej popravite številko, izbiro prevoznika ali zahtevana polja. Če odgovor namesto tega pomeni, da dogodki pošiljke še niso na voljo, uporabite dokumentirani potek osveževanja in tega ne obravnavajte kot napako pri preverjanju.

Ali HTTP 200 pomeni, da je bila paketna zahteva v celoti uspešna?

Ne nujno. Preverite shemo odgovora ponudnika za rezultate na ravni operacije in elementa. Shranite uspehe in ločite napake, da ponovitev enega elementa po nepotrebnem ne ponovi preostalih.

Koliko ponovitev naj dovoli integracija sledenja?

Univerzalnega števila ni. Na podlagi navodil ponudnika, varnosti operacije in tega, kako dolgo ostane rezultat uporaben, določite omejitev poskusov in časovni proračun. Načrtovana sinhronizacija v ozadju lahko prenese drugačno časovno okno obnovitve kot interaktivna zahteva stranke.

Ali naj časovna omejitev takoj označi pošiljko kot neuspešno?

Ne. Časovna omejitev zahteve je izid integracije, ne dogodek pošiljke. Ohranite zadnje znano stanje sledenja, načrtujte varno obnovitev in težave s povezljivostjo ne pretvorite v obvestilo o neuspešni dostavi.

Kaj se mora zgoditi, ko so ponovitve izčrpane?

Opravilo premaknite v trajno čakalno vrsto neuspelih opravil ali pregledov skupaj z diagnostičnim kontekstom. Določite, ali obnovitev zahteva popravljen vnos, obnovljene poverilne podatke, pomoč ponudnika ali poznejše nadzorovano ponovno predvajanje. Opravila ne zavrzite tiho in ne zaženite istega neomejenega cikla ponovitev.

Viri

• RFC 9110: Semantika HTTP — semantika statusov HTTP, idempotentne metode, premisleki glede samodejnih ponovitev in polje Retry-After.
• RFC 6585: Dodatne statusne kode HTTP — opredelitev 429 Too Many Requests in njegove neobvezne glave Retry-After.
• 17TRACK Tracking API — uradna vstopna točka za izdelek API-ja za sledenje.
• Dokumentacija API-ja 17TRACK — referenca za preverjanje zahtev za integracijo, značilnih za ponudnika.