Skip to main content
DomovBlogVodnikiKako poslati več sledilnih številk v eni zahtevi API (omejitve paketne obdelave in delne napake)

Kako poslati več sledilnih številk v eni zahtevi API (omejitve paketne obdelave in delne napake)

17TRACK

Č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.

Kako poslati več sledilnih številk v eni zahtevi API

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.

OmejitevKaj potrditiPosledica za implementacijo
Elementi na zahtevoNajvečje število zapisov za določeno operacijoPred pošiljanjem razdelite vhodni seznam
Velikost telesa zahteveVse dokumentirane omejitve bajtovUpoštevajte neobvezna polja in velikost serializacije
Hitrost zahtevDovoljene zahteve v določenem časovnem intervaluZahteve usmerjajte prek skupnega omejevalnika
SočasnostMorebitna omejitev hkratnih zahtevOmejite število aktivnih delavcev
Obračun uporabeAli se uporaba šteje po zahtevi, pošiljki ali drugi enotiPorabo 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.

  1. Sledilne številke ohranite kot nize. Če jih pretvorite v številke, lahko odstranite začetne ničle ali spremenite dolge identifikatorje.
  2. 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.
  3. Preverite obvezna polja. Nekateri postopki lahko zahtevajo identifikator prevoznika ali dodatne podatke o pošiljki. Uporabljajte samo dokumentirana imena in vrednosti polj.
  4. Določite izrecen obseg odstranjevanja dvojnikov. Ponavljajoča se sledilna številka ni samodejno dvojnik pri vsakem prevozniku, trgovcu ali zgodovinski pošiljki.
  5. 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.

IzidPriporočeno dejanje
Neveljavno polje ali nepodprta vrednostPopravite vhodne podatke; nespremenjenih podatkov ne pošiljajte ponovno
Napaka pri preverjanju pristnosti ali dovoljenjihZaustavite prizadeto delo ter popravite poverilnice ali dostop
Odgovor zaradi omejitve hitrostiZahtevo odložite v skladu z dokumentiranimi navodili in ustreznimi glavami odgovora
Začasna napaka na ravni elementaElement ponovite z omejenim številom poskusov in postopnim zakasnjevanjem
Časovna omejitev po oddajiOznačite kot negotovo; uskladite izid ali uporabite dokumentirana jamstva glede varnosti ponovnega poskusa
Neprepoznan ali nepopoln rezultatOhranite 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.

  1. Pošljite veljaven paket z dokumentiranim največjim številom elementov, nato pa preverite, kako odjemalec prepreči prevelik paket.
  2. Preverite, ali sledilne številke z začetnimi ničlami preživijo serializacijo in shranjevanje.
  3. Preizkusite kombinacijo sprejetih in zavrnjenih elementov, ne da bi ponovno pošiljali uspešne zapise.
  4. Simulirajte omejevanje hitrosti in potrdite, da več delavcev upošteva isto omejitev.
  5. Simulirajte časovno omejitev po oddaji in preverite pot uskladitve.
  6. Med prejemom odgovora in lokalnim shranjevanjem ponovno zaženite delavca.
  7. Preizkusite manjkajoče, neznane ali nepovezljive rezultate elementov.
  8. 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