Kako poslati več sledilnih številk v eni zahtevi API (omejitve paketne obdelave in delne napake)
Če želite v eni zahtevi API poslati več sledilnih številk, uporabite končno točko Tracking API, ki izrecno podpira paketne zahteve, vsako pošiljko oblikujte v skladu z njeno shemo zahteve in večje sezname razdelite na pakete znotraj dokumentiranih omejitev. Nato preverite tako odgovor HTTP kot rezultat vsake pošiljke: uspešna zahteva HTTP ne pomeni nujno, da so bile sprejete vse sledilne številke. Ponovite samo upravičene neuspešne zahteve in pred ponovno oddajo celotnega paketa razrešite negotove izide.

Ta vodnik je namenjen razvijalcem, ki sledenje pošiljkam povezujejo s sistemom za upravljanje naročil, skladiščno platformo, aplikacijo za e-trgovino ali notranjo nadzorno ploščo. Cilj ni zgolj pošiljanje manjšega števila zahtev. Treba je upoštevati vsako pošiljko, ne da bi ustvarili podvojeno delo ali izgubili neuspešne zapise.
Najprej ugotovite, kaj paketna končna točka dejansko počne
Integracija sledenja lahko vključuje več različnih operacij. Registracija pošiljk, pridobivanje njihovih najnovejših podatkov o sledenju in prejemanje nadaljnjih posodobitev niso medsebojno zamenljivi.
- Registracija: Pošljite pošiljke, da lahko storitev začne ali nadaljuje njihovo sledenje.
- Iskanje: Zahtevajte podatke o sledenju pošiljk ob upoštevanju pravil pridobivanja določene končne točke.
- Posodobitev dostave: Prejemajte poznejše spremembe prek podprtega mehanizma, kot so spletne kljuke, ali jih pridobivajte z načrtovanimi zahtevami.
V dokumentaciji preverite natančno operacijo, ki jo potrebujete. Registracijska končna točka, ki sprejema več zapisov, ne dokazuje, da končna točka za iskanje sprejema enako število zapisov, uporablja enako shemo ali ima enako omejitev hitrosti.
Pri integraciji s 17TRACK začnite na strani izdelka Tracking API in uporabite uradno dokumentacijo API, da potrdite operacijo, način preverjanja pristnosti, obliko zahteve in polja odgovora. Spodnje primere obravnavajte kot vzorce implementacije, ne kot nadomestilo za pogodbo tega API-ja.
Omejitve paketov so več kot le največje število pošiljk
Za Tracking API ni univerzalne omejitve velikosti paketa. Omejitve se lahko razlikujejo glede na ponudnika, končno točko, različico API-ja in konfiguracijo računa. Pred uvedbo paketne obdelave si te omejitve zabeležite ločeno.
| Omejitev | Kaj potrditi | Posledica za implementacijo |
|---|---|---|
| Elementi na zahtevo | Največje število zapisov za določeno operacijo | Pred pošiljanjem razdelite vhodni seznam |
| Velikost telesa zahteve | Vse dokumentirane omejitve bajtov | Upoštevajte neobvezna polja in velikost serializacije |
| Hitrost zahtev | Dovoljene zahteve v določenem časovnem intervalu | Zahteve usmerjajte prek skupnega omejevalnika |
| Sočasnost | Morebitna omejitev hkratnih zahtev | Omejite število aktivnih delavcev |
| Obračun uporabe | Ali se uporaba šteje po zahtevi, pošiljki ali drugi enoti | Porabo ocenite ločeno od obsega zahtev |
Če na primer hipotetična končna točka dovoljuje 25 zapisov na zahtevo, 63 zapisov zahteva tri zahteve z 25, 25 in 13 zapisi. Te številke ponazarjajo le razdeljevanje; niso omejitve 17TRACK.
Ne predvidevajte, da paketna obdelava zmanjša obračunljivo uporabo. Lahko zmanjša režijske stroške zahtev HTTP, vendar je vpliv na stroške odvisen od dejanskih pravil obračunavanja ponudnika. Prav tako veljavna velikost paketa ne dovoljuje neomejenega vzporednega pošiljanja zahtev.
Pred izdelavo zahteve pripravite zapise
Večina preprečljivih napak pri paketni obdelavi se začne pri pripravi vhodnih podatkov. Pred dodajanjem v paket preverite vsako pošiljko, vendar se izogibajte pravilom, ki bi pomotoma zavrnila veljavne sledilne številke različnih prevoznikov.
- Sledilne številke ohranite kot nize. Če jih pretvorite v številke, lahko odstranite začetne ničle ali spremenite dolge identifikatorje.
- Odstranite nenamerne presledke na začetku in koncu. Notranjih znakov ne odstranjujte in ne spreminjajte velikosti črk, razen če ustrezna specifikacija dovoljuje takšno normalizacijo.
- Preverite obvezna polja. Nekateri postopki lahko zahtevajo identifikator prevoznika ali dodatne podatke o pošiljki. Uporabljajte samo dokumentirana imena in vrednosti polj.
- Določite izrecen obseg odstranjevanja dvojnikov. Ponavljajoča se sledilna številka ni samodejno dvojnik pri vsakem prevozniku, trgovcu ali zgodovinski pošiljki.
- Ohranite lokalni identifikator pošiljke. Shranite povezavo med odhodnim elementom in svojim zapisom naročila ali pošiljke, tudi če API ne sprejema polj z referencami po meri.
Pri sledenju prevoznikov v več omrežjih ne sklepajte o prevozniku samo na podlagi dolžine ali predpone sledilne številke, razen če je tak sklep zanesljiv za vaš konkretni postopek. Kjer API podpira identifikacijo prevoznika, upoštevajte njegovo dokumentirano ravnanje v primeru dvoumnosti.
Ponazoritvena struktura zahteve
Naslednji JSON prikazuje koncept paketa. Ovojnica, imena lastnosti in identifikatorji so ponazoritveni, ne predstavljajo sheme zahteve 17TRACK. Nekateri API-ji namesto objekta, ki vsebuje polje, pričakujejo matriko na najvišji ravni.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Nosilnost izdelajte s serializatorjem JSON, namesto da bi združevali nize. Poverilnice za preverjanje pristnosti pošljite prek dokumentiranega mehanizma ter jih hranite zunaj nadzora izvorne kode, kode, dostavljene brskalniku, in običajnih dnevnikov.
Odgovor obdelajte na dveh ravneh
Paketna zahteva ima izid na transportni ravni in izid na aplikacijski ravni. Vaša integracija mora oceniti oba.
1. raven: Ali je zahteva prejela uporaben odgovor?
Začnite s statusom HTTP, glavami odgovora in telesom odgovora. Napake pri preverjanju pristnosti, nepravilno oblikovane zahteve, omejevanje hitrosti in napake strežnika lahko preprečijo običajno obdelavo elementov. Časovna omejitev omrežja je drugačna: odjemalec morda ne ve, ali je strežnik zahtevo prejel ali obdelal.
Semantiko HTTP opredeljuje RFC 9110. Vendar dokumentacija ponudnika določa, kako se njegova polja rezultatov na aplikacijski ravni preslikajo v dejanske izide pošiljk.
2. raven: Kaj se je zgodilo z vsako pošiljko?
Če odgovor podpira rezultate na ravni elementov, razvrstite vsak poslani zapis. Ne predvidevajte, da HTTP 200 pomeni uspeh vsakega zapisa ali da seznam rezultatov ohranja vrstni red zahteve, razen če pogodba to izrecno zagotavlja.
- Sprejeto: Operacija je uspela v skladu z dokumentirano opredelitvijo končne točke.
- Trajna vhodna napaka: Pred novim poskusom zapis popravite ali raziščite.
- Napaka, ki jo je mogoče ponoviti: Načrtujte nov poskus v skladu z navodili ponudnika za ponavljanje.
- Neznan izid: Odgovor manjka, je nepopoln ali ga ni mogoče varno povezati s poslanim zapisom.
Odgovore, kot je »že registrirano«, ali podobne odgovore, povezane z dvojniki, hranite ločeno, dokler ne razumete njihovega dokumentiranega pomena. Lahko pomenijo, da želeno stanje že obstaja, vendar jih ne smete samodejno obravnavati kot potrditev lastništva, konfiguracije ali naročnine.
Po obdelavi odgovora mora imeti vsak vhodni zapis natanko en lokalni izid. Koristno preverjanje uskladitve je: poslani zapisi so enaki vsoti sprejetih zapisov, trajnih napak, napak, ki jih je mogoče ponoviti, in neznanih izidov. To je lokalno računovodsko pravilo, ne zahtevana oblika odgovora API-ja.
Delne napake obravnavajte brez ponovnega pošiljanja uspešnih zapisov
Predpostavimo, da ponazoritveni paket vsebuje deset pošiljk: sedem jih je sprejetih, dve imata neveljavna obvezna polja, pri eni pa pride do dokumentirane začasne napake. Shranite sedem uspešnih izidov, dve neveljavni pošiljki pošljite v popravek in ponovite samo začasno neuspešno pošiljko.
Če ponovno pošljete vseh deset zapisov, ustvarite nepotreben promet in lahko otežite obravnavo dvojnikov. Prav tako je težje razlikovati prvotno zavrnitev od poznejšega odgovora, povezanega z dvojnikom.
| Izid | Priporočeno dejanje |
|---|---|
| Neveljavno polje ali nepodprta vrednost | Popravite vhodne podatke; nespremenjenih podatkov ne pošiljajte ponovno |
| Napaka pri preverjanju pristnosti ali dovoljenjih | Zaustavite prizadeto delo ter popravite poverilnice ali dostop |
| Odgovor zaradi omejitve hitrosti | Zahtevo odložite v skladu z dokumentiranimi navodili in ustreznimi glavami odgovora |
| Začasna napaka na ravni elementa | Element ponovite z omejenim številom poskusov in postopnim zakasnjevanjem |
| Časovna omejitev po oddaji | Označite kot negotovo; uskladite izid ali uporabite dokumentirana jamstva glede varnosti ponovnega poskusa |
| Neprepoznan ali nepopoln rezultat | Ohranite dokaze in raziščite primer, namesto da bi predpostavili uspeh |
HTTP 429 pomeni preveč zahtev, njegov odgovor pa lahko vsebuje glavo Retry-After, kot je opisano v RFC 6585. Ne predvidevajte, da je ta glava vedno prisotna. Če izrecna zakasnitev za ponovni poskus ni navedena, uporabite omejeno strategijo postopnega zakasnjevanja, skladno z dokumentacijo API-ja.
Dodajte naključni zamik, da razporedite ponovne poskuse več delavcev, določite največje število poskusov ali najdaljšo starost ponavljanja in izčrpane zapise pošljite v pregledno čakalno vrsto. Neskončno ponavljanje lahko prikrije trajno težavo s konfiguracijo.
Zakaj je treba časovne omejitve obravnavati posebej
Časovna omejitev ne dokazuje zavrnitve. Strežnik je paket morda sprejel, preden je povezava odpovedala. Samodejno ponovno pošiljanje zahteve, ki spreminja stanje, lahko zato podvoji delo.
Če končna točka podpira dokumentirane ključe idempotentnosti, upoštevajte njena pravila, vključno z obsegom in hrambo ključa. Ne izmišljajte si glave idempotentnosti in ne predvidevajte, da jo strežnik upošteva. V nasprotnem primeru uporabite podprto iskanje ali postopek uskladitve, da pred ponovno oddajo ugotovite, ali želeno stanje obstaja. Lokalno odstranjevanje dvojnikov pomaga usklajevati vaše delavce, vendar ne zagotavlja idempotentnosti na strani strežnika.
Praktični potek paketne obdelave
Podrobnosti, specifične za ponudnika, hranite v prilagodniku, da čakalna vrsta, razporejevalnik ponovnih poskusov in logika spremljanja niso odvisni od surovih imen polj odgovora.
preverite zapise in ohranite lokalne ID-je pošiljk
razrešite dvojnike znotraj predvidenega poslovnega obsega
razdelite zapise z uporabo dokumentiranih omejitev elementov in nosilnosti
za vsak paket prek omejenega bazena delavcev:
pred pošiljanjem shranite zapis poskusa
počakajte na skupni omejevalnik hitrosti
pošljite prek prilagodilnika, specifičnega za ponudnika
če je izid negotov:
dodajte v čakalno vrsto za uskladitev
nadaljujte
razvrstite izide na ravni zahteve in elementa
za vsak poslani zapis shranite en izid
za ponovni poskus načrtujte samo upravičene napake
neveljavne ali izčrpane zapise pošljite v pregled
Shranjevanje izidov in načrtovanje ponovnih poskusov naj bo mogoče obnoviti. Trajni zapis opravila ali transakcijski vzorec čakalne vrste lahko na primer prepreči, da bi sesutje procesa izgubilo odločitev o ponovnem poskusu. Po ponovnem zagonu morajo delavci razlikovati med neposlanim delom in delom, katerega oddaljeni izid je še vedno negotov.
Velikost paketa naj bo nastavljiva možnost, povezana z ustrezno končno točko, ne pa konstanta, raztresena po celotni kodni zbirki. Manjši paket je lahko koristen pri odpravljanju težav ali ločevanju problematičnih zapisov; največji dovoljeni paket ni samodejno najboljša delovna velikost.
Spremljajte izide pošiljk, ne le delovanja HTTP
Spremljanje API-ja mora pokazati, ali pošiljke dosegajo želeno stanje. Nadzorna plošča, ki prikazuje samo stopnje uspešnosti HTTP, lahko spregleda delne napake v sicer uspešnih odgovorih.
- Stopnja sprejema elementov: Sprejeti zapisi, deljeni s poslanimi zapisi, z jasno opredeljeno obravnavo ponovnih poskusov.
- Porazdelitev napak: Število napak po končni točki, dokumentirani kodi napake in ustreznem kontekstu prevoznika.
- Neznani izidi: Neusklajeni zapisi in čas, ki so ga ostali nerazrešeni.
- Zaostanek ponovnih poskusov: Čakajoči ponovni poskusi, starost najstarejšega ponovnega poskusa in izčrpani poskusi.
- Zdravje zahtev: Zakasnitve, časovne omejitve, omejevanje hitrosti in napake strežnika.
- Svežina sledenja: Ali sprejete pošiljke pozneje prejmejo uporabne podatke o sledenju.
Sprejem registracije ni dokaz novega skeniranja pri prevozniku. Status obdelave API-ja ločite od premikanja pošiljke in svežine podatkov, da incidenta integracije ne zamenjate z zamudo pri dostavi.
Zabeležite lokalne ID-je paketov, reference pošiljk, število poskusov, dokumentirane kode napak in ID-je zahtev ponudnika, kadar so na voljo. Redigirajte poverilnice in nepotrebne osebne podatke. Identifikatorje sledenja uporabljajte samo tam, kjer so operativno potrebni, in surovih identifikatorjev pošiljk ne vstavljajte v oznake metrik z veliko kardinalnostjo.
Pred produkcijo preizkusite te primere
Kjer je na voljo, uporabite dokumentirano peskovniško ali nadzorovano testno okolje. Ne predvidevajte, da bodo izmišljene sledilne številke v produkciji povzročile predvidljive odgovore.
- Pošljite veljaven paket z dokumentiranim največjim številom elementov, nato pa preverite, kako odjemalec prepreči prevelik paket.
- Preverite, ali sledilne številke z začetnimi ničlami preživijo serializacijo in shranjevanje.
- Preizkusite kombinacijo sprejetih in zavrnjenih elementov, ne da bi ponovno pošiljali uspešne zapise.
- Simulirajte omejevanje hitrosti in potrdite, da več delavcev upošteva isto omejitev.
- Simulirajte časovno omejitev po oddaji in preverite pot uskladitve.
- Med prejemom odgovora in lokalnim shranjevanjem ponovno zaženite delavca.
- Preizkusite manjkajoče, neznane ali nepovezljive rezultate elementov.
- Potrdite, da neveljavni zapisi dosežejo vidno čakalno vrsto za popravke, namesto da bi se ponavljali v nedogled.
Integracija, pripravljena za produkcijo, lahko pojasni stanje vsake poslane pošiljke, vključno s tistimi, katerih izid je začasno neznan. Zmanjšanje števila zahtev je koristno, vendar je ohranjanje te odgovornosti pomembnejši cilj zasnove.
Pogosta vprašanja
Koliko sledilnih številk lahko pošljem v eni zahtevi?
Uporabite omejitev, dokumentirano za natančno končno točko in različico API-ja. Preverite tudi velikost zahteve, omejitve hitrosti in morebitne omejitve, povezane z računom. Ni varne univerzalne številke, ki bi jo lahko uporabili pri vseh API-jih za sledenje ali pri različnih operacijah znotraj enega API-ja.
Ali lahko ena neveljavna sledilna številka povzroči neuspeh celotnega paketa?
Da, odvisno od pravil preverjanja končne točke. Nekateri API-ji vrnejo posamezne zavrnitve, drugi pa lahko zahtevo zavrnejo pred obdelavo elementov. Preverite napake na ravni zahteve in rezultate na ravni elementov; ne predvidevajte, da vsaka paketna končna točka podpira delni sprejem.
Ali naj paket ponovim, ko je odgovor HTTP uspešen?
Ne samodejno. Najprej razčlenite dokumentirani status na aplikacijski ravni in rezultate elementov. Shranite uspešne zapise ter ponovite samo upravičene napake. Če rezultata ni mogoče varno razlagati, ga označite kot negotovega in raziščite.
Ali lahko v istem paketu združim različne prevoznike?
Samo če končna točka podpira takšno strukturo zahteve. Potrdite, ali se podatki o prevozniku posredujejo za vsako pošiljko, ali je podprta samodejna identifikacija in kaj se zgodi, kadar je identifikacija dvoumna. Storitev za več prevoznikov sama po sebi ne določa pravil paketne obdelave vsake končne točke.
Ali paketna obdelava omogoči hitrejši prihod posodobitev sledenja?
Paketna obdelava lahko zmanjša število zahtev, ki jih pošlje vaša aplikacija, vendar sama po sebi ne povzroči, da bi se dogodki prevoznika pojavili prej. Registracija, pridobivanje podatkov, razpoložljivost skeniranja pri prevozniku in dostava posodobitev so ločeni deli postopka.
Viri
- 17TRACK Tracking API — uradna vstopna točka izdelka za razvijalce, ki ocenjujejo integracijo sledenja.
- Dokumentacija 17TRACK API — referenca za pogodbo končne točke, omejitve, preverjanje pristnosti in obravnavo odgovorov, specifične za ponudnika.
- RFC 9110: Semantika HTTP — semantika statusov HTTP, idempotentnost, samodejni ponovni poskusi in Retry-After.
- RFC 6585: Dodatne kode statusa HTTP — opredelitev HTTP 429 Too Many Requests in njegove neobvezne glave Retry-After.


