Obdelava statusa »v izvajanju« pri preverjanju naročila prek API

Kaj pomeni processing v odgovoru API

Status processing, in_progress ali drugo enakovredno stanje pomeni, da je ponudnik naročilo sprejel v obdelavo, vendar ni zabeležil izida. Pri storitvah promocije je to lahko preverjanje povezave, čakanje v čakalni vrsti, zagon naloge ali postopno dostavljanje naročene količine.

Processing ne potrjuje uspešne izvedbe in ne pomeni napake. Po njem lahko naročilo preide v completed, partial, canceled ali failed. Dokler ponudnik vrača vmesni status, ne ustvarjajte ponovne zahteve za isto povezavo in isto količino.

HTTP 200 s statusom processing pomeni uspešen odgovor API, ne pa uspešnega zaključka naročila. Te dogodke je treba hraniti in obdelovati ločeno.

Kateri podatki so potrebni za preverjanje naročila

Za polling potrebujete zunanji ID naročila, ki ga je ponudnik vrnil ob ustvarjanju. Shranite ga skupaj z notranjim ID, izvirno količino, parametri storitve, povezavo, časom ustvarjanja in izvirnim odgovorom API. Iskanje naročila po imenu kanala, povezavi ali količini je nezanesljivo: takšne vrednosti se lahko ujemajo pri več zahtevah.

Če po ustvarjanju pride do časovne omejitve, zahteve ne pošiljajte samodejno znova. Ponudnik je lahko zahtevo sprejel, odgovor pa se je lahko izgubil na poti. Najprej uporabite metodo iskanja naročila, če je navedena v dokumentaciji, ali primer predajte v preverjanje.

Pomanjkljivost shranjevanja samo trenutnega statusa je, da ob sporu ni mogoče obnoviti, kdaj je naročilo prešlo v processing, ali je bil napredek in kateri odgovori so prihajali prej.

Primer zahteve za status prek curl

Natančen naslov, način avtorizacije in imena polj vzemite iz ponudnikove dokumentacije. Spodaj je prikazana predloga: vrednosti v kotnih oklepajih je treba zamenjati s podatki konkretnega API.

Zahteva GET za eno naročilo

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

Primer odgovora:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "значение_времени"

}

Polji completed_quantity in remains sta navedeni le kot primer strukture. Ponudnik lahko uporablja progress, start_count, balance ali druga imena. Pomanjkljivost pristopa GET je, da nekateri API-ji sprejemajo preverjanje statusa le prek POST.

Primer zahteve POST in paketnega preverjanja

Zahteva POST za status enega naročila

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

Ključa API ne posredujte v nizu URL. Naslovi zahtev pridejo v dnevnike posrednikov, sisteme analitike, zgodovino brskalnika in tehnične dnevnike. Pomanjkljivost POST je, da ga je težje ročno preveriti prek naslovne vrstice, vendar to ni razlog za prenos skrivnosti v URL.

Paketna zahteva za aktivna naročila

Če API podpira paketno preverjanje, pošljite več ID-jev z eno zahtevo:

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

Odgovor povežite z notranjim naročilom po zunanjem ID, ne po položaju elementa v polju. Pomanjkljivost paketnega preverjanja: ponudnik lahko ne vrne vseh naročil, omeji velikost seznama ali sporoči napako samo za en ID.

Kako določiti polling za processing

Po prvem odgovoru processing naslednje preverjanje postavite v čakalno vrsto. Interval izberite glede na dokumentacijo API, omejitve pogostosti in naravo storitve. Pri nalogah, kjer se status spreminja hitro, je na začetku dopustno pogostejše preverjanje. Pri postopni promociji stalne kratke zahteve običajno ne prinesejo novih informacij.

Praktična shema je podaljševanje premora po enakih odgovorih processing. Prvo preverjanje se izvede po začetni zakasnitvi, nato interval raste do določenega maksimuma. Če API vrne napredek ali nov čas posodobitve, lahko štetje začnete od te spremembe.

• Po ustvarjanju naročila ne preverjajte statusa takoj večkrat zapored: storitev lahko potrebuje čas za uvrstitev v čakalno vrsto.
• Pri ponavljajočem se processing podaljšujte interval med zahtevami, namesto da ohranjate stalno pogostost.
• Dodajte majhno naključno odstopanje času zagona nalog, da naročila ne poizvedujejo API-ja hkrati.
• Če ponudnik posreduje Retry-After ali podobno priporočilo, ga uporabite kot prednostno.
• Pri naročilih s spletnimi kljukami ohranite kontrolni polling: obvestilo lahko ne prispe.

Pomanjkljivost redkega pollinga je, da lahko vmesnik po dejanskem zaključku prikazuje stari status. Pomanjkljivost preveč pogostega pollinga je tveganje, da naletite na omejitve API, prejmete 429 in ustvarite odvečno obremenitev.

Katere čase hraniti za nadzor processing

Za razlikovanje običajne izvedbe od zataknitve en sam trenutni status ne zadostuje. Za vsako aktivno naročilo hranite čas ustvarjanja, prvo prejetje processing, zadnji uspešni odgovor API, zadnjo spremembo zunanjega statusa in zadnjo spremembo napredka.

Koristno je tudi shranjevati izvirno količino, potrjeno izvedeno količino, preostanek in izvirni status ponudnika. Če API ne vrača napredka, to ni razlog, da bi naročilo šteli za zataknjeno: ravnajte se po času zadnjega odgovora in pričakovanem obdobju obdelave, če je navedeno v pogojih storitve.

Najdaljšega časa čakanja ni mogoče določiti z eno številko za vse storitve. Uporabite rok, ki ga ponudnik navaja za konkretno storitev, z notranjo rezervo za čakalno vrsto in posodobitev podatkov. Če rok ni naveden, določite ločeno pravilo za vsako kategorijo storitev in ga pregledujte glede na zgodovino dejanske obdelave.

Kaj storiti, če se processing ne spremeni

Dolgotrajen processing ne dokazuje napake. Najprej preverite, ali so prihajali uspešni odgovori API, ali sta se completed_quantity ali remains spreminjala, ali so bile spletne kljuke in ali so se spremenila pravila storitve. Odsotnost vidne rasti je lahko povezana z zakasnitvijo statistike platforme ali s tem, da ponudnik napredek posodablja šele ob zaključku.

Ko je notranji rok čakanja presežen, naročila ne prekličite samodejno. Izvedite izredno preverjanje statusa, zaprosite za podatke z ločeno metodo, če je predvidena, in preverite zgodovino obvestil. Če ponudnik še vedno potrjuje processing, naročilo prenesite v notranje stanje »potrebno preverjanje«, vendar ohranite zunanji status brez zamenjave.

• Zabeležite čas zadnjega potrjenega odgovora in celoten odgovor API.
• Preverite, ali se je napredek od prejšnjega poizvedovanja spremenil.
• Po dosegu notranjega praga zmanjšajte pogostost samodejnih zahtev.
• V podporo posredujte zunanji ID, povezavo, parametre storitve, zgodovino statusov in tehnične napake.
• Preostanka ne zaganjajte znova do odgovora ponudnika ali jasnega končnega statusa.

Pomanjkljivost ročnega preverjanja je, da naročilo zahteva pozornost podpore. Toda samodejna prekinitev ali podvojitev je nevarnejša: izvajanje se lahko pri ponudniku nadaljuje.

Kako ločiti napako zahteve od statusa naročila

Omrežna napaka, časovna omejitev, HTTP 429 in odgovor 5xx ne sporočajo stanja samega naročila. Pomenijo le, da novega zanesljivega statusa ni bilo mogoče pridobiti. V takšni situaciji ohranite zadnji potrjeni status, zabeležite tehnično napako in načrtujte novo preverjanje.

Pri 429 upoštevajte Retry-After, če je glava posredovana. Pri začasnih omrežnih napakah in 5xx podaljšajte premor med poskusi. Pri napaki avtorizacije, podpisa ali pravic dostopa ne nastavljajte pogostih ponovnih poskusov: preveriti je treba ključ, veljavnost žetona, omejitve IP in nastavitve dostopa.

Če API vrne HTTP 200, vendar JSON ni mogoče razčleniti ali v odgovoru ni order_id in status, shranite celotno telo odgovora in preverjanje označite kot nepravilno. Odsotnosti statusa ne zamenjujte s completed, canceled ali processing.

Kdaj prenehati s samodejnimi ponovnimi zahtevami

Polling ne sme biti neskončen. Omejite število tehničnih ponovitev za začasne napake in ločeno nadzorujte skupni rok, ko je naročilo v processing. Po izčrpanju omejitve ponovnih poskusov nalogo preverjanja prenesite v čakalno vrsto za obravnavo, namesto da vsako minuto brez izida ustvarjate nove zahteve.

Ponovitev zahteve za status je običajno varna, če metoda samo bere podatke. Metod ustvarjanja, preklica, dopolnitve, ponovnega zagona in vračila ni mogoče mehansko ponavljati po časovni omejitvi. Brez idempotentnega ključa ali izrecne potrditve ponudnika lahko takšna ponovitev naročilo spremeni dvakrat.

Pomanjkljivost omejevanja ponovnih poskusov je, da del posodobitev postane ročna naloga. Neskončni ponovni poskusi so slabši: prikrivajo napako, porabljajo omejitve in otežujejo razčlenjevanje dnevnikov.

Kako sprejeti končni status po processing

Preprečite povratni prehod iz completed v processing zaradi poznega odgovora pollinga ali stare spletne kljuke. Pri vsaki posodobitvi primerjajte čas dogodka pri ponudniku, zaporedno številko različice, če obstaja, in trenutno notranje stanje.

• new in pending lahko preideta v processing, canceled ali failed.
• processing lahko preide v completed, partial, canceled ali failed.
• partial ni treba samodejno šteti za completed.
• completed, canceled in failed običajno veljajo za končne in blokirajo samodejno vračanje nazaj.
• Neznan status ali nedovoljen prehod zahtevata ločeno preverjanje.

Tudi toga tabela prehodov ima pomanjkljivost: ponudnik lahko doda veljavno novo stanje. Zato shranjujte izvirni status in ga ne prepisujte z notranjo klasifikacijo.

Kako obdelati partial in preostanek naročila

Partial pomeni, da je potrjen le del izvirne količine. V odgovoru API so lahko dejansko izvedena količina, preostanek, razlog in podatki o nadomestilu. Te vrednosti hranite ločeno: izvirne količine naročila ni mogoče zamenjati z izvedeno količino.

Primer končnega odgovora je lahko takšen:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "значение_или_отсутствие_поля"

}

Najprej ugotovite, kaj API dejansko potrjuje: ali je vračilo že izvedeno, ali je vračilo le načrtovano, ali je preostanek preklican ali je potreben stik s podporo. Če polja o vračilu ni, preostanka ne štejte za samodejno nadomeščenega.

Neizvedenega dela ne zaganjajte znova brez ločene odločitve. Ponudnik lahko še zaključuje obračun, statistika platforme se lahko posodablja z zakasnitvijo, ponovna zahteva pa lahko ustvari podvojeno promocijo. Pomanjkljivost čakanja na potrditev je, da preostanek ne bo zaprt takoj, vendar ne bo nastalo odvečno naročilo.

Spletne kljuke ne nadomestijo kontrolnega preverjanja

Spletna kljuka omogoča takojšnjo posodobitev kartice naročila po dogodku, ne da bi čakali na naslednji polling. V obdelovalniku poiščite naročilo po zunanjem ID, preverite podpis ali skrivnost, shranite ID dogodka in prehod uporabite šele po preverjanju dopustnosti.

Ponovna dostava spletne kljuke mora biti varna: istega dogodka ni mogoče šteti za novo spremembo. Dogodki lahko prispejo tudi neurejeno, zato končnega naročila ne vračajte nazaj samo na podlagi poznega processing.

Kontrolni polling je potreben tudi pri stabilnih spletnih kljukah. Pomanjkljivost spletnih kljuk je zahtevnejša nastavitev: potreben je dosegljiv obdelovalnik, zaščita pred ponarejenimi zahtevami, deduplikacija in dnevnik dogodkov.

Kaj prikazati stranki pri processing in zataknitvi

V vmesniku ni treba prikazovati celotnega tehničnega JSON. Za processing zadostuje stanje »naročilo v obdelavi«. Če je API posredoval zanesljiv napredek, prikažite potrjeno količino ločeno od izvirne in je ne predstavljajte kot končni rezultat.

Za naročilo, ki je preseglo notranji rok nadzora, uporabite razumljivo stanje, kot je »preverjamo izvedbo«. Ne sporočajte preklica, vračila ali popolnega zaključka, dokler tega ne potrdi odgovor ponudnika.

Obvestila so koristna ob sprejemu naročila, končni izvedbi, partial, preklicu, napaki in potrebi po preverjanju. Sporočila po vsakem pollingu ustvarjajo šum in stranki ne pomagajo razumeti dejanskega stanja zahteve.

Kateri zapisi so potrebni v dnevniku obdelave

Zgodovina odgovorov pomaga razčleniti zataknjen processing, izgubljeno spletno kljuko, spor glede delne izvedbe in neskladje med vmesnikom in API. Za vsak klic shranite zunanji ID, vir posodobitve, čas zahteve in odgovora, kodo HTTP, izvirni status, normalizirani status, napredek, preostanek in besedilo tehnične napake.

V običajne dnevnike ne zapisujte ključev API, žetonov, podpisov in drugih skrivnosti. Omejite dostop do surovih odgovorov: vsebujejo lahko podatke, ki ne smejo biti v vmesniku podpore.

Pred zagonom preverite scenarije s ponavljajočim se processing, odsotnostjo napredka, časovno omejitvijo, 429, napako 5xx, nepravilnim JSON, pozno spletno kljuko, podvojeno spletno kljuko, partial, canceled in neznanim statusom. Testni način je koristen za strukturo integracije, vendar je njegova pomanjkljivost, da morda ne ponavlja dejanskih čakalnih vrst in zakasnitev delovnega API.