Skip to main content
DomovBlogVodnikiKaj naj vrne končna točka webhooka za sledenje? Statusne kode, časovne omejitve in ponovni poskusi?

Kaj naj vrne končna točka webhooka za sledenje? Statusne kode, časovne omejitve in ponovni poskusi?

17TRACK

Končna točka spletnega kavlja za sledenje mora po sprejemu dogodka v obdelavo vrniti hiter in nameren odgovor 2xx. Pri večini integracij je najvarnejši vzorec preveriti pristnost zahteve, preveriti koristni tovor, shraniti dogodek ali ga dodati v čakalno vrsto ter potrditi njegov sprejem z 200 OK ali 202 Accepted. Odgovore 4xx uporabite za zahteve, ki jih pošiljatelj ne sme poskusiti znova, odgovore 5xx pa, kadar je začasna težava na strani strežnika preprečila sprejem. Natančno vedenje glede časovne omejitve in ponovnih poskusov je še vedno odvisno od pogodbe ponudnika spletnega kavlja, zato mora biti vaša izvedba zasnovana na dokumentiranem vedenju pošiljatelja in ne na predpostavkah.

Katere statusne kode in časovne omejitve mora vrniti končna točka spletnega kavlja za sledenje

Pri spletnem kavlju za sledenje ali status pošiljke je ta razlika pomembna, ker lahko dogodki dostave prispejo več kot enkrat, prispejo v napačnem vrstnem redu ali se po omrežni napaki znova predvajajo. Naloga končne točke ni nujno dokončati vsake poslovne operacije, preden odgovori. Njena prva naloga je zanesljivo odločiti, ali je bil dogodek sprejet.

Pogodba o odgovoru v praksi

Odgovor spletnega kavlja ima dva naslovnika: sistem, ki pošilja zahtevo, in vašo aplikacijo. Pošiljatelj potrebuje jasen rezultat HTTP, da se lahko odloči, ali bo dostavo označil kot uspešno, jo ponovil ali ustavil. Vaša aplikacija potrebuje dovolj časa za preverjanje in trajno beleženje dogodka. Te cilje je lažje doseči, če ima končna točka kratko sinhrono pot in ločeno asinhrono pot obdelave.

  1. Prejmite zahtevo HTTP prek HTTPS.
  2. Preverite podpis, poverilnice za preverjanje pristnosti, časovni žig ali druge mehanizme celovitosti zahteve, ki jih zahteva ponudnik.
  3. Razčlenite in preverite koristni tovor, ne da bi izvajali počasna opravila v zalednih sistemih.
  4. Zapišite dogodek ali zapis za preprečevanje podvajanja in sklic na dogodek v trajno shrambo ali zanesljivo čakalno vrsto.
  5. Vrnite nameren odgovor 2xx.
  6. Posodobitev sledenja, obvestilo stranki, spremembo zaloge ali drugo poslovno dejanje obdelajte asinhrono.

Odgovor ne sme trditi, da je bil dogodek sprejet, če obstaja samo v pomnilniku procesa. Če se aplikacija sesuje takoj po vrnitvi uspeha, se lahko dogodek, ki ni bil nikoli trajno shranjen, izgubi, medtem ko pošiljatelj verjame, da je bila dostava uspešna. Točka, na kateri vrnete 2xx, se mora zato ujemati z vašim dejanskim jamstvom trajnosti.

Katero statusno kodo mora vrniti spletni kavelj?

OdgovorPomen za pošiljateljaObičajna uporaba spletnega kavlja
200 OKZahteva je bila sprejeta in uspešno obravnavana.Praktična privzeta izbira po preverjanju in trajnem sprejemu.
202 AcceptedZahteva je bila sprejeta v obdelavo, vendar se lahko delo nadaljuje.Uporabno, ko je bil dogodek varno dodan v čakalno vrsto, poslovna obdelava pa je asinhrona.
204 No ContentZahteva je bila uspešna in telo odgovora ni potrebno.Primerno, če ponudnik sprejema prazen uspešen odgovor.
400–499Zahteva je neveljavna, ni avtorizirana ali v poslani obliki ni sprejemljiva.Napačno oblikovan koristni tovor, neuspešno preverjanje pristnosti, neveljaven podpis ali trajno zavrnjen dogodek.
429 Too Many RequestsPrejemnik uporablja omejevanje hitrosti.Uporabite le, če sta vedenje pošiljatelja pri ponovnih poskusih in vaša politika omejevanja hitrosti združljiva.
500–599Prejemnik zahteve ni mogel sprejeti zaradi težave na strani strežnika ali začasne težave.Nedosegljiva zbirka podatkov, napaka čakalne vrste, napaka odvisnosti ali nepričakovana napaka aplikacije.

200 OK je pogosto najmanj presenetljiva izbira, ker je splošno razumljena kot uspešen sprejem. Tudi 202 Accepted je semantično uporabna, kadar je končna točka sprejela dogodek za poznejšo obdelavo. Nobena od teh kod ni samodejno pravilna: dokumentacija pošiljatelja lahko določa, kateri odgovori 2xx štejejo kot uspešni, nekateri ponudniki pa lahko pričakujejo določeno telo ali vrsto vsebine.

Ne vračajte odgovora 2xx samo zato, ker je zahteva HTTP dosegla vaš strežnik. Če preverjanje podpisa ni uspešno ali koristnega tovora ni mogoče varno razlagati, je odgovor 4xx običajno bolj resničen. Po drugi strani ne vračajte 4xx zaradi začasnega izpada zbirke podatkov, če bi dogodek lahko pozneje uspel. Odgovor 5xx pošiljatelju, ki podpira ponovne poskuse, omogoča, da dogodek znova dostavi, čeprav lahko ponudnik uporablja lastno politiko.

Kako obravnavati časovne omejitve?

Vrednosti časovnih omejitev spletnih kavljev so specifične za ponudnika. Ne obstaja univerzalna časovna omejitev HTTP, ki bi jo uporabljala vsaka platforma za sledenje, pošiljatelj pa lahko preneha čakati, še preden vaša aplikacija dokonča počasno operacijo. Dokumentirano časovno omejitev pošiljatelja obravnavajte kot zgornjo mejo in ne kot cilj. Vaša končna točka bi morala običajno odgovoriti precej pred to mejo.

Najpogostejša oblikovalska napaka je izvedba vsega dela v zalednih sistemih pred potrditvijo spletnega kavlja. Upravljavec lahko zaporedoma pokliče zbirko podatkov, sistem za upravljanje naročil, storitev obvestil in analitični cevovod. Ena počasna odvisnost lahko povzroči, da pošiljatelj vidi časovno omejitev, čeprav vaša aplikacija delo dokonča pozneje. Pošiljatelj lahko nato poskus ponovi, kar povzroči podvojeno obdelavo ali tekmujoče posodobitve.

Sinhrono pot omejite na delo, potrebno za varno odločitev o sprejemu. To običajno vključuje preverjanje pristnosti zahteve, osnovno preverjanje sheme, trajno shranjevanje dogodka in objavo v čakalno vrsto. Draga obogatitev podatkov, poizvedbe pri prevoznikih, sporočanje strankam in klice API-jev tretjih oseb prepustite delavcu. Čas, porabljen za prejem, preverjanje, trajno shranjevanje in potrditev dogodka, spremljajte ločeno od časa, porabljenega za njegovo obdelavo.

Časovna omejitev ni enaka neuspešni poslovni operaciji. Z vidika pošiljatelja časovna omejitev običajno pomeni, da ni prejel uporabnega uspešnega odgovora. Vaša storitev je morda dogodek uspešno shranila tik pred prekinitvijo povezave. Zato sta idempotentnost in preprečevanje podvajanja potrebna tudi takrat, ko je končna točka videti zanesljiva.

Kaj povzroči ponovne poskuse?

Pošiljatelj spletnega kavlja lahko poskus ponovi po napaki povezave, časovni omejitvi ali odgovoru, ki ga njegova pogodba razvršča kot neuspešnega. Natančen urnik, največje število poskusov, algoritem zakasnitve in časovno okno dostave se med ponudniki razlikujejo. Ne obljubljajte določenega števila ponovnih poskusov, razen če je navedeno v dokumentaciji ponudnika.

Prejemnik mora predvidevati, da se ponovni poskusi lahko zgodijo, in jih načrtno obravnavati:

  • Uporabite identifikator dogodka, kadar je na voljo. Shranite ga z omejitvijo enoličnosti ali enakovrednim ključem za preprečevanje podvajanja.
  • Obdelavo naredite idempotentno. Dvakratna uporaba iste posodobitve statusa dostave ne sme poslati dveh sporočil stranki, ustvariti dveh vračil ali nepravilno napredovati naročila.
  • Ohranite izvirni koristni tovor ali uporaben revizijski zapis. To omogoča ponovno predvajanje, preiskavo in usklajevanje.
  • Sprejem ločite od obdelave. Delavec lahko ponovi notranje napake, ne da bi moral pošiljatelj ponoviti celotno izmenjavo HTTP.
  • Beležite statusne kode odgovorov in zakasnitve. Povečanje števila odgovorov 5xx, časovnih omejitev ali podvojenih ID-jev dogodkov lahko razkrije izpad, še preden uporabniki prijavijo manjkajoče posodobitve sledenja.

Podvojen dogodek bi moral običajno prejeti uspešen odgovor, če je bil izvirni dogodek že trajno sprejet. Vračanje napake za vsak dvojnik lahko sproži nepotrebne ponovne poskuse. Končna točka lahko zabeleži, da je bil dogodek že viden, preskoči ponovljeno poslovno dejanje in vrne isti razred uspeha, kot se uporablja za nov sprejeti dogodek.

Kdaj vrniti 4xx, 429 ali 5xx?

Vrnite 4xx, kadar ponovni poskus iste zahteve verjetno ne bo odpravil težave. Primeri vključujejo neveljaven podpis, manjkajoče zahtevano preverjanje pristnosti, nepodprto obliko koristnega tovora ali zahtevo, ki krši trajno pravilo preverjanja. Pred izbiro 4xx preverite, ali pošiljatelj to statusno kodo obravnava kot trajno napako. Nekatere platforme imajo lastna pravila za neuspešne dostave.

429 uporabljajte previdno. HTTP določa 429 za omejevanje hitrosti, glava Retry-After pa lahko sporoči, kdaj bi bil ponovni poskus primeren. Vendar vsak pošiljatelj spletnih kavljev kode 429 ne razlaga enako. Če je vaša čakalna vrsta polna ali je storitev preobremenjena, potrdite, da bo ponudnik varno ponovil poskus in da njegov urnik ponovnih poskusov ne bo poslabšal preobremenitve. Omejena vstopna čakalna vrsta in načrt povratnega pritiska sta običajno boljša kot dovoliti nepredvidljive neuspehe zahtev.

Vrnite 5xx, kadar prejemnik zaradi začasne težave dogodka ne more varno sprejeti. To vključuje nedosegljivo zbirko podatkov, neuspešen zapis v trajno čakalno vrsto ali notranjo napako, ki je preprečila preverjanje oziroma trajno shranjevanje. Vračanje 200 ob tihem zavrženju dogodka oteži obnovitev, ker pošiljatelj nima razloga, da bi poskusil znova.

Pri dostavi spletnih kavljev se izogibajte preusmeritvam, kot so 301, 302 ali 307. Obravnava preusmeritev se med odjemalci razlikuje, preusmeritev podpisane zahteve pa lahko povzroči nejasnosti glede cilja, metode in telesa. Ponudnika namesto tega konfigurirajte s končno končno točko HTTPS.

Zanesljiva politika odgovorov za dogodke sledenja

Za večino integracij spletnih kavljev za sledenje je naslednja politika smiselno izhodišče:

  1. Vrnite 200 ali 202, ko je dogodek prestal preverjanje pristnosti in bil trajno shranjen ali dodan v zanesljivo čakalno vrsto.
  2. Vrnite odgovor 4xx za neveljaven podpis, neveljavno preverjanje pristnosti ali trajno neuporaben koristni tovor, skladno z dokumentiranimi pravili ponudnika.
  3. Vrnite 5xx, kadar začasna napaka preprečuje trajni sprejem.
  4. Za varno prepoznan dvojnik vrnite uspešen odgovor, hkrati pa preprečite podvojene poslovne učinke.
  5. Upravljavec naj bo hiter, njegovo zakasnitev potrditve pa merite.
  6. Pred uvedbo v produkcijo preizkusite scenarije časovnih omejitev, ponovnih poskusov, podvajanja, napačnega vrstnega reda, napačne oblike in izpada ponudnika.

Če integrirate API za sledenje, začnite z dokumentacijo spletnega kavlja ponudnika in potrdite sprejete kode uspeha, način podpisovanja zahtev, časovno omejitev, sprožilce ponovnih poskusov, shemo koristnega tovora in identifikator dogodka. Pri integracijah 17TRACK je uradna dokumentacija Tracking API ustrezno mesto za preverjanje pogodbe, specifične za ponudnika, namesto sklepanja na podlagi splošne prakse HTTP.

Kontrolni seznam izvedbe

  • Končna točka je dosegljiva prek HTTPS in ima stabilen produkcijski URL.
  • Preverjanje pristnosti in podpisa se izvedeta pred poslovno obdelavo.
  • Izvirna zahteva ali preverljiva predstavitev se po potrebi ohrani za preverjanje podpisov in odpravljanje težav.
  • Dogodek se trajno shrani, preden je poslan uspešen odgovor.
  • Podvojene dostave so varne in ne ponavljajo nepreklicnih dejanj.
  • Delavci lahko notranjo obdelavo ponovijo neodvisno od cikla ponovnih poskusov HTTP pošiljatelja.
  • Dnevniki vključujejo ID dogodka, čas dostave, kodo odgovora, stanje obdelave in ID korelacije, ne da bi razkrivali skrivnosti.
  • Opozorila razlikujejo časovne omejitve končne točke, napake preverjanja 4xx, izpade 5xx, zamude čakalne vrste in podvojene dostave.
  • Dokumentirano vedenje ponudnika je bilo preizkušeno z resničnimi dogodki ali dogodki v peskovniku.

FAQ

Ali je 200 OK boljši od 202 Accepted za spletni kavelj?

Noben ni univerzalno boljši. Uporabite 200 OK, ko je bila zahteva sprejeta in vaša integracija odgovor obravnava kot splošen uspeh. Uporabite 202 Accepted, ko je bil dogodek sprejet za asinhrono obdelavo. Potrdite, da pošiljatelj izbrani odgovor 2xx razvršča kot uspešen.

Ali mora končna točka spletnega kavlja počakati, dokler posodobitev sledenja ni v celoti obdelana?

Običajno ne. Počakati mora le, dokler dogodek ni preverjen glede pristnosti, preverjen in trajno sprejet. Dolgotrajno delo bi se moralo običajno izvajati po potrditvi, da počasna odvisnost ne povzroči nepotrebne časovne omejitve in ponovnega poskusa.

Kaj se mora zgoditi, ko isti dogodek sledenja prispe dvakrat?

Prepoznajte ga z ID-jem dogodka ponudnika ali skrbno zasnovanim enakovrednim ključem, preskočite podvojene stranske učinke in vrnite uspešen odgovor, če je bil dogodek že sprejet. Tako so ponovni poskusi varni, ne da bi prikrili nove napake pri obdelavi.

Ali mora neveljaven podpis vrniti 400 ali 401?

Izbira je odvisna od vašega modela preverjanja pristnosti in dokumentiranih pričakovanj ponudnika. Obe kodi lahko sporočata zavrnitev, vendar je doslednost pomembnejša od univerzalne izbire ene kode. Ne potrjujte dogodka, katerega pristnosti ne morete preveriti.

Ali odgovor 5xx vedno povzroči ponovni poskus?

Ne. Številni sistemi spletnih kavljev ponovijo poskus pri časovnih omejitvah in napakah strežnika, vendar so sprožilci in urniki ponovnih poskusov specifični za ponudnika. Ponovne poskuse obravnavajte kot dokumentirano vedenje integracije in jih preverite v testnem okolju.

Viri