Kaip išsiųsti kelis sekimo numerius vienoje API užklausoje (paketinio apdorojimo apribojimai ir daliniai gedimai)
Norėdami vienoje API užklausoje išsiųsti kelis sekimo numerius, naudokite Tracking API galinį tašką, kuris aiškiai priima paketą, suformatuokite kiekvieną siuntą pagal jo užklausos schemą ir didesnius sąrašus suskaidykite į paketus, neviršijančius dokumentacijoje nurodytų apribojimų. Tada patikrinkite ir HTTP atsakymą, ir kiekvienos siuntos rezultatą: sėkminga HTTP užklausa nebūtinai reiškia, kad visi sekimo numeriai buvo priimti. Pakartokite tik tinkamų pakartoti nesėkmių bandymus ir, prieš iš naujo pateikdami visą paketą, suderinkite neaiškius rezultatus.

Šis vadovas skirtas kūrėjams, jungiantiems siuntų sekimą su užsakymų valdymo sistema, sandėlio platforma, elektroninės prekybos programa arba vidine skydeliu. Tikslas nėra vien išsiųsti mažiau užklausų. Reikia apskaityti kiekvieną siuntą nesukuriant pasikartojančio darbo ir neprarandant nesėkmingų įrašų.
17TRACK Order TrackingNuolat informuokite klientus apie pristatymo būseną ir gerinkite firminę DTC patirtį po pirkimo.
Sužinoti daugiau →Pirmiausia nustatykite, ką iš tikrųjų atlieka paketų galinis taškas
Integruojant sekimą gali būti atliekamos kelios skirtingos operacijos. Siuntų registravimas, naujausios jų sekimo informacijos gavimas ir vėlesnių atnaujinimų priėmimas nėra tarpusavyje pakeičiami veiksmai.
17TRACK APISupaprastinkite pasaulinį siuntų sekimą naudodami siuntų atnaujinimus iš daugiau nei 3 500 vežėjų.
Sužinoti daugiau →- Registravimas: Pateikite siuntas, kad paslauga galėtų pradėti arba tęsti jų sekimą.
- Paieška: Prašykite siuntų sekimo informacijos laikydamiesi galinio taško gavimo taisyklių.
- Pristatymo atnaujinimas: Gaukite vėlesnius pakeitimus naudodami palaikomą mechanizmą, pavyzdžiui, žiniatinklio kablius, arba gaukite juos pagal suplanuotas užklausas.
Dokumentacijoje patikrinkite, kokios tiksliai operacijos jums reikia. Registravimo galinis taškas, priimantis kelis įrašus, neįrodo, kad paieškos galinis taškas priima tokį patį skaičių įrašų, naudoja tą pačią schemą arba turi tokį patį užklausų dažnio limitą.
Integruodami 17TRACK, pradėkite nuo Tracking API produkto puslapio ir naudokite oficialią API dokumentaciją, kad patvirtintumėte operaciją, autentifikavimo metodą, užklausos formatą ir atsakymo laukus. Toliau pateiktus pavyzdžius laikykite diegimo šablonais, o ne šios API sutarties pakaitalu.
Paketų apribojimai apima daugiau nei didžiausią siuntų skaičių
Tracking API nėra universalaus paketų limito. Apribojimai gali skirtis pagal teikėją, galinį tašką, API versiją ir paskyros konfigūraciją. Prieš įgyvendindami paketų siuntimą, atskirai užfiksuokite šiuos apribojimus.
Skaityti daugiau: Kaip pasirinkti siuntų sekimo API elektroninei prekybai?| Apribojimas | Ką patvirtinti | Įgyvendinimo pasekmė |
|---|---|---|
| Elementai vienoje užklausoje | Didžiausias konkrečios operacijos įrašų skaičius | Prieš siųsdami suskaidykite įvesties sąrašą |
| Užklausos turinio dydis | Bet koks dokumentacijoje nurodytas baitų limitas | Atsižvelkite į pasirinktinius laukus ir serializavimo dydį |
| Užklausų dažnis | Leidžiamų užklausų skaičius per nustatytą intervalą | Valdykite užklausų tempą naudodami bendrą ribotuvą |
| Lygiagretumas | Bet koks vienu metu siunčiamų užklausų apribojimas | Apribokite aktyvių darbuotojų skaičių |
| Naudojimo apskaita | Ar naudojimas skaičiuojamas pagal užklausą, siuntą ar kitą vienetą | Įvertinkite sunaudojimą atskirai nuo užklausų kiekio |
Pavyzdžiui, jei hipotetinis galinis taškas leidžia vienoje užklausoje pateikti 25 įrašus, 63 įrašams reikės trijų užklausų, kuriose bus atitinkamai 25, 25 ir 13 įrašų. Šie skaičiai iliustruoja tik skaidymą į dalis; jie nėra nurodyti 17TRACK limitai.
Nepainiokite paketų siuntimo su apmokestinamo naudojimo mažinimu. Jis gali sumažinti HTTP užklausų sąnaudas, tačiau poveikis mokesčiams priklauso nuo faktinių teikėjo apskaitos taisyklių. Taip pat galiojantis paketo dydis nesuteikia teisės neribotai siųsti lygiagrečių užklausų.
Paruoškite įrašus prieš kurdami užklausą
Dauguma išvengiamų paketų klaidų prasideda nuo įvesties paruošimo. Patikrinkite kiekvieną siuntą prieš įtraukdami ją į paketą, tačiau venkite taisyklių, kurios netyčia atmestų teisėtus skirtingų vežėjų sekimo numerius.
- Išsaugokite sekimo numerius kaip eilutes. Pavertus juos skaičiais, gali būti pašalinti pradžioje esantys nuliai arba pakeisti ilgi identifikatoriai.
- Pašalinkite atsitiktinius aplinkinius tarpus. Netrinkite vidinių simbolių ir nekeiskite raidžių registro, nebent atitinkama specifikacija leidžia tokį normalizavimą.
- Patikrinkite privalomus laukus. Kai kurioms darbo eigoms gali reikėti vežėjo identifikatoriaus arba papildomos siuntos informacijos. Naudokite tik dokumentacijoje nurodytus laukų pavadinimus ir reikšmes.
- Aiškiai nustatykite dublikatų šalinimo sritį. Pasikartojantis sekimo numeris ne visada yra dublikatas tarp visų vežėjų, prekybininkų ar istorinių siuntų.
- Išsaugokite vietinį siuntos identifikatorių. Saugokite ryšį tarp siunčiamo elemento ir savo užsakymo arba siuntos įrašo, net jei API nepriima pasirinktinių nuorodos laukų.
Naudodami Carrier Tracking keliuose tinkluose, nenustatykite vežėjo vien pagal sekimo numerio ilgį ar priešdėlį, nebent toks nustatymas yra patikimas jūsų konkrečioje darbo eigoje. Jei API palaiko vežėjo identifikavimą, vadovaukitės dokumentuotu neaiškių atvejų tvarkymu.
Papildoma informacija: kelių vežėjų sekimas: kas tai yra, nauda ir veikimo principasPavyzdinė užklausos struktūra
Toliau pateiktas JSON rodo paketinio turinio koncepciją. Apvalkalas, ypatybių pavadinimai ir identifikatoriai yra iliustraciniai, o ne 17TRACK užklausos schema. Kai kurios API vietoje objekto, kuriame yra masyvas, tikisi aukščiausio lygio masyvo.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Kurkite turinį naudodami JSON serializatorių, o ne sujungdami eilutes. Autentifikavimo duomenis siųskite dokumentacijoje nurodytu būdu ir nelaikykite jų versijų valdymo sistemoje, naršyklėje vykdomame kode ar įprastuose žurnaluose.
Apdorokite atsakymą dviem lygiais
Paketinė užklausa turi transporto lygio ir programos lygio rezultatą. Jūsų integracija turi įvertinti abu.
1 lygis: ar užklausa gavo tinkamą atsakymą?
Pradėkite nuo HTTP būsenos, atsakymo antraščių ir atsakymo turinio. Autentifikavimo klaidos, netinkamai suformuotos užklausos, dažnio ribojimas ir serverio klaidos gali neleisti įprastai apdoroti elementų. Tinklo skirtasis laikas yra kitoks atvejis: klientas gali nežinoti, ar serveris gavo arba apdorojo užklausą.
HTTP semantika apibrėžta RFC 9110. Tačiau tai, kaip programos lygio rezultatų laukai susiejami su faktinėmis siuntų būsenomis, nustato teikėjo dokumentacija.
2 lygis: kas nutiko kiekvienai siuntai?
Jei atsakymas palaiko elementų lygio rezultatus, suskirstykite kiekvieną pateiktą įrašą. Nemanykite, kad HTTP 200 reiškia, jog kiekvienas įrašas buvo sėkmingas, arba kad rezultatų sąrašas išsaugo užklausos tvarką, nebent sutartyje tai aiškiai garantuojama.
- Priimta: Operacija pavyko pagal dokumentuotą galinio taško apibrėžimą.
- Nuolatinė įvesties klaida: Prieš kitą bandymą pataisykite arba ištirkite įrašą.
- Pakartotina klaida: Suplanuokite kitą bandymą pagal teikėjo pakartotinių bandymų gaires.
- Nežinomas rezultatas: Atsakymas trūksta, yra neišsamus arba jo negalima saugiai susieti su pateiktu įrašu.
„Jau užregistruota“ ar panašius su dublikatais susijusius atsakymus laikykite atskirai, kol suprasite jų dokumentuotą reikšmę. Jie gali reikšti, kad norima būsena jau egzistuoja, tačiau jų nereikėtų automatiškai laikyti sėkmingu nuosavybės, konfigūracijos ar prenumeratos patvirtinimu.
Apdorojus atsakymą, kiekvienas įvesties įrašas turi turėti tiksliai vieną vietinį rezultatą. Naudinga suderinimo patikra: pateikti įrašai lygūs priimtiems įrašams ir nuolatinėms klaidoms, pakartotinoms klaidoms bei nežinomiems rezultatams kartu sudėjus. Tai vietinė apskaitos taisyklė, o ne privalomas API atsakymo formatas.
Tvarkykite dalines klaidas nekartodami sėkmingų įrašų
Tarkime, iliustraciniame pakete yra dešimt siuntų: septynios priimtos, dviejose trūksta arba neteisingi privalomi laukai, o vienai įvyko dokumentuota laikina klaida. Išsaugokite septynis sėkmingus rezultatus, perduokite du neteisingus įrašus taisyti ir pakartokite tik laikinos klaidos atvejį.
Pakartotinai pateikus visus dešimt įrašų sukuriamas nereikalingas srautas ir gali apsunkėti dublikatų tvarkymas. Taip pat tampa sunkiau atskirti pradinį atmetimą nuo vėlesnio su dublikatu susijusio atsakymo.
| Rezultatas | Rekomenduojamas veiksmas |
|---|---|
| Neteisingas laukas arba nepalaikoma reikšmė | Pataisykite įvestį; nekeistą įrašą pakartotinai siųsti nereikia |
| Autentifikavimo arba leidimo klaida | Sustabdykite susijusį darbą ir pataisykite kredencialus arba prieigą |
| Dažnio ribojimo atsakymas | Atidėkite pagal dokumentuotas gaires ir taikomas atsakymo antraštes |
| Laikina elemento lygio klaida | Pakartokite šio elemento bandymą su ribotu bandymų skaičiumi ir laukimo didinimu |
| Skirtasis laikas po pateikimo | Pažymėkite kaip neaiškų; suderinkite arba naudokite dokumentuotas pakartotinio siuntimo saugumo garantijas |
| Neatpažintas arba neišsamus rezultatas | Išsaugokite įrodymus ir ištirkite, užuot laikę operaciją sėkminga |
HTTP 429 reiškia per daug užklausų, o jo atsakyme gali būti Retry-After antraštė, kaip aprašyta RFC 6585. Nemanykite, kad ši antraštė visada pateikiama. Kai aiškus pakartotinio bandymo delsos laikas nenurodytas, naudokite riboto laukimo didinimo politiką, suderinamą su API dokumentacija.
Pridėkite atsitiktinį delsos komponentą, kad keli darbuotojai pakartotinius bandymus paskirstytų laike, nustatykite didžiausią bandymų skaičių arba pakartotinio bandymo amžių ir išsekusius įrašus perduokite peržiūros eilei. Neribotas pakartotinis bandymas gali paslėpti nuolatinę konfigūracijos problemą.
Kodėl skirties laiko atvejams reikia ypatingo dėmesio
Skirtasis laikas neįrodo, kad užklausa buvo atmesta. Serveris galėjo priimti paketą prieš nutrūkstant ryšiui. Todėl automatiškai pakartotinai siunčiant būseną keičiančią užklausą galima pakartoti darbą.
Jei galinis taškas palaiko dokumentuotus idempotentiškumo raktus, laikykitės jo taisyklių, įskaitant rakto sritį ir saugojimo trukmę. Nekurkite idempotentiškumo antraštės patys ir nemanykite, kad serveris į ją atsižvelgs. Kitu atveju naudokite palaikomą paieškos arba suderinimo darbo eigą, kad prieš pakartotinį pateikimą nustatytumėte, ar norima būsena egzistuoja. Vietinis dublikatų šalinimas padeda koordinuoti jūsų darbuotojus, tačiau negarantuoja serverio pusės idempotentiškumo.
Praktinė paketinio apdorojimo darbo eiga
Teikėjui būdingą informaciją laikykite adapteryje, kad eilė, pakartotinių bandymų planuoklis ir stebėjimo logika nepriklausytų nuo neapdorotų atsakymo laukų pavadinimų.
patikrinkite įrašus ir išsaugokite vietinius siuntų ID
pašalinkite dublikatus numatytoje verslo srityje
suskaidykite įrašus pagal dokumentuotus elementų ir turinio limitus
kiekvienam paketui per ribotą darbuotojų telkinį:
prieš siųsdami išsaugokite bandymo įrašą
palaukite bendro dažnio ribotuvo
siųskite naudodami konkrečiam teikėjui skirtą adapterį
jei rezultatas neaiškus:
įtraukite į suderinimo eilę
tęskite
suskirstykite užklausos ir elemento lygio rezultatus
išsaugokite po vieną rezultatą kiekvienam pateiktam įrašui
suplanuokite pakartotinius bandymus tik tinkamoms klaidoms
neteisingus arba išsekusius įrašus perduokite peržiūrai
Užtikrinkite, kad rezultatų išsaugojimą ir pakartotinių bandymų planavimą būtų galima atkurti. Pavyzdžiui, patvarus užduoties įrašas arba transakcinis eilių sudarymo modelis gali neleisti proceso gedimui prarasti sprendimo dėl pakartotinio bandymo. Paleidus darbuotojus iš naujo, jie turi atskirti neišsiųstą darbą nuo darbo, kurio nuotolinis rezultatas vis dar neaiškus.
Paketų dydį nustatykite kaip konfigūruojamą parametrą, susietą su atitinkamu galiniu tašku, o ne kaip konstantą, išsklaidytą visoje kodų bazėje. Mažesnis paketas gali būti naudingas šalinant triktis arba atskiriant probleminius įrašus; didžiausias leidžiamas paketas ne visada yra geriausias veikimo dydis.
Stebėkite siuntų rezultatus, o ne tik HTTP veikimo laiką
API Monitoring turi rodyti, ar siuntos pasiekia numatytą būseną. Skydelis, kuriame rodoma tik HTTP sėkmės rodiklis, gali nepastebėti dalinių klaidų kitu atveju sėkminguose atsakymuose.
- Elementų priėmimo rodiklis: Priimtų įrašų dalis nuo pateiktų įrašų, aiškiai apibrėžiant pakartotinių bandymų vertinimą.
- Klaidų pasiskirstymas: Skaičius pagal galinį tašką, dokumentuotą klaidos kodą ir susijusį vežėjo kontekstą.
- Nežinomi rezultatai: Nesuderinti įrašai ir laikas, kurį jie lieka neišspręsti.
- Pakartotinių bandymų eilė: Laukiantys pakartotiniai bandymai, seniausio pakartotinio bandymo amžius ir išnaudoti bandymai.
- Užklausų būklė: Vėlinimas, skirtieji laikai, dažnio ribojimas ir serverio klaidos.
- Sekimo naujumas: Ar priimtos siuntos vėliau gauna tinkamą sekimo informaciją.
Registravimo priėmimas nėra naujo vežėjo skenavimo įrodymas. API apdorojimo būseną laikykite atskirai nuo siuntos judėjimo ir duomenų naujumo, kad integracijos incidentas nebūtų supainiotas su pristatymo vėlavimu.
Kai įmanoma, registruokite vietinius paketų ID, siuntų nuorodas, bandymų skaičių, dokumentuotus klaidų kodus ir teikėjo užklausų ID. Paslėpkite kredencialus ir nereikalingą asmeninę informaciją. Sekimo identifikatorius naudokite tik tada, kai to reikia veiklai, ir venkite neapdorotų siuntų identifikatorių didelės kardinalumo reikšmės metrikų etiketėse.
Prieš naudodami gamyboje patikrinkite šiuos atvejus
Jei įmanoma, naudokite dokumentuotą smėlio dėžę arba kontroliuojamą bandymų aplinką. Nemanykite, kad išgalvoti sekimo numeriai gamyboje sukurs nuspėjamus atsakymus.
- Pateikite galiojantį paketą, kurio dydis lygus dokumentuotam elementų limitui, tada patikrinkite, kaip klientas neleidžia sukurti per didelio paketo.
- Patikrinkite, ar sekimo numeriai su pradžioje esančiais nuliais išlieka serializuojant ir saugant.
- Patikrinkite mišrius priimtus ir atmestus elementus, nepakartodami sėkmingų įrašų.
- Imituokite dažnio ribojimą ir patvirtinkite, kad keli darbuotojai laikosi to paties limito.
- Imituokite skirtąjį laiką po pateikimo ir patikrinkite suderinimo kelią.
- Iš naujo paleiskite darbuotoją tarp atsakymo gavimo ir vietinio išsaugojimo.
- Patikrinkite trūkstamus, nepažįstamus arba nesusiejamus elementų rezultatus.
- Patvirtinkite, kad neteisingi įrašai patenka į matomą taisymo eilę, o ne siunčiami pakartotinai neribotą laiką.
Gamybai paruošta integracija gali paaiškinti kiekvienos pateiktos siuntos būseną, įskaitant tas, kurių rezultatas laikinai nežinomas. Užklausų skaičiaus mažinimas yra naudingas, tačiau svarbesnis projektavimo tikslas yra išlaikyti šią atskaitomybę.
DUK
Kiek sekimo numerių galiu išsiųsti vienoje užklausoje?
Naudokite konkrečiam galiniam taškui ir API versijai dokumentacijoje nurodytą limitą. Taip pat patikrinkite užklausos dydį, dažnio limitus ir konkrečiai paskyrai taikomus apribojimus. Nėra saugaus universalaus skaičiaus, kurį būtų galima taikyti visoms sekimo API arba skirtingoms vienos API operacijoms.
Ar vienas neteisingas sekimo numeris gali sukelti viso paketo nesėkmę?
Taip, priklausomai nuo galinio taško tikrinimo taisyklių. Kai kurios API pateikia atskirus atmetimus, o kitos gali atmesti užklausą prieš apdorodamos elementus. Tikrinkite ir užklausos lygio klaidas, ir elementų lygio rezultatus; nemanykite, kad kiekvienas paketų galinis taškas palaiko dalinį priėmimą.
Ar turėčiau pakartoti paketą, kai HTTP atsakymas sėkmingas?
Ne automatiškai. Pirmiausia išanalizuokite dokumentuotą programos lygio būseną ir elementų rezultatus. Išsaugokite sėkmingus įrašus ir pakartokite tik tinkamų klaidų bandymus. Jei rezultato negalima saugiai interpretuoti, klasifikuokite jį kaip neaiškų ir ištirkite.
Ar tame pačiame pakete galiu maišyti vežėjus?
Tik jei galinis taškas palaiko tokią užklausos struktūrą. Patvirtinkite, ar vežėjo informacija pateikiama kiekvienai siuntai, ar palaikomas automatinis identifikavimas ir kas nutinka, kai identifikavimas yra neaiškus. Kelių vežėjų paslauga savaime neapibrėžia kiekvieno galinio taško paketų taisyklių.
Ar paketų siuntimas pagreitina sekimo atnaujinimų gavimą?
Paketų siuntimas gali sumažinti jūsų programos siunčiamų užklausų skaičių, tačiau pats savaime nepadaro vežėjų įvykių pasiekiamų greičiau. Registravimas, duomenų gavimas, vežėjo skenavimo pasiekiamumas ir atnaujinimų pristatymas yra atskiros darbo eigos dalys.
Šaltiniai
- 17TRACK Tracking API — oficialus produkto pradžios taškas kūrėjams, vertinantiems sekimo integraciją.
- 17TRACK API dokumentacija — teikėjui būdingos galinio taško sutarties, limitų, autentifikavimo ir atsakymų apdorojimo nuoroda.
- RFC 9110: HTTP semantika — HTTP būsenų semantika, idempotentiškumas, automatiniai pakartotiniai bandymai ir Retry-After.
- RFC 6585: Papildomi HTTP būsenos kodai — HTTP 429 Too Many Requests apibrėžimas ir pasirenkama Retry-After antraštė.


