Si të dërgoni disa numra gjurmimi në një kërkesë API (kufizimet e grupimit dhe dështimet e pjesshme)
Për të dërguar disa numra gjurmimi në një kërkesë të vetme API, përdorni një pikë fundore të Tracking API që pranon në mënyrë të qartë grupe, formatoni çdo dërgesë sipas skemës së kërkesës së saj dhe ndani listat më të mëdha në grupe brenda kufijve të dokumentuar. Më pas shqyrtoni si përgjigjen HTTP, ashtu edhe rezultatin e çdo dërgese: një kërkesë HTTP e suksesshme nuk do të thotë domosdoshmërisht se çdo numër gjurmimi është pranuar. Provoni sërish vetëm dështimet e përshtatshme dhe pajtoni rezultatet e pasigurta përpara se të ridërgoni një grup të tërë.

Ky udhëzues është për zhvilluesit që lidhin gjurmimin e dërgesave me një sistem të menaxhimit të porosive, platformë magazine, aplikacion ecommerce ose panel të brendshëm. Qëllimi nuk është thjesht të dërgohen më pak kërkesa. Qëllimi është të llogaritet çdo dërgesë pa krijuar punë të dyfishtë ose pa humbur regjistrimet e dështuara.
Së pari, përcaktoni se çfarë bën në të vërtetë pika fundore e grupit
Një integrim gjurmimi mund të përfshijë disa veprime të dallueshme. Regjistrimi i dërgesave, marrja e informacionit më të fundit të gjurmimit dhe marrja e përditësimeve të mëvonshme nuk janë të këmbyeshme.
- Regjistrimi: Dërgoni dërgesat që shërbimi të mund të fillojë ose të vazhdojë gjurmimin e tyre.
- Kërkimi: Kërkoni informacion gjurmimi për dërgesat, në përputhje me rregullat e marrjes së të dhënave të pikës fundore.
- Përditësimi i dorëzimit: Merrni ndryshime të mëvonshme përmes një mekanizmi të mbështetur, si webhooks, ose merrini përmes kërkesave të planifikuara.
Kontrolloni dokumentacionin për veprimin e saktë që ju nevojitet. Një pikë fundore regjistrimi që pranon disa regjistrime nuk dëshmon se një pikë fundore kërkimi pranon të njëjtin numër, përdor të njëjtën skemë ose ka të njëjtin kufi shpejtësie.
Për një integrim me 17TRACK, filloni me faqen e produktit Tracking API dhe përdorni dokumentacionin zyrtar të API-së për të konfirmuar veprimin, metodën e autentikimit, formatin e kërkesës dhe fushat e përgjigjes. Trajtojini shembujt më poshtë si modele zbatimi, jo si zëvendësim të kontratës së kësaj API-je.
Kufijtë e grupeve janë më shumë se një numër maksimal dërgesash
Nuk ka një kufi universal grupi për një Tracking API. Kufijtë mund të ndryshojnë sipas ofruesit, pikës fundore, versionit të API-së dhe konfigurimit të llogarisë. Përpara zbatimit të grupeve, regjistroni veçmas këto kufizime.
| Kufizimi | Çfarë të konfirmoni | Pasojat për zbatimin |
|---|---|---|
| Elementet për kërkesë | Numri maksimal i regjistrimeve për veprimin specifik | Ndajeni listën e hyrjes përpara dërgimit |
| Madhësia e trupit të kërkesës | Çdo kufi i dokumentuar në bajte | Llogaritni fushat opsionale dhe madhësinë e serializimit |
| Shpejtësia e kërkesave | Kërkesat e lejuara gjatë një intervali të përcaktuar | Rregulloni ritmin e kërkesave përmes një kufizuesi të përbashkët |
| Paralelizmi | Çdo kufizim për kërkesat e njëkohshme | Kufizoni numrin e punonjësve aktivë |
| Llogaritja e përdorimit | Nëse përdorimi llogaritet sipas kërkesës, dërgesës ose një njësie tjetër | Vlerësoni konsumin veçmas nga vëllimi i kërkesave |
Për shembull, nëse një pikë fundore hipotetike lejon 25 regjistrime për kërkesë, 63 regjistrime kërkojnë tri kërkesa me nga 25, 25 dhe 13 regjistrime. Këta numra ilustrojnë vetëm ndarjen në pjesë; nuk janë kufij të deklaruar të 17TRACK.
Mos supozoni se grupimi ul përdorimin e faturueshëm. Ai mund të ulë mbingarkesën e kërkesave HTTP, por çdo ndikim në tarifa varet nga rregullat faktike të llogaritjes së ofruesit. Po kështu, një madhësi e vlefshme grupi nuk autorizon kërkesa paralele të pakufizuara.
Përgatitni regjistrimet përpara ndërtimit të kërkesës
Shumica e dështimeve të shmangshme të grupeve fillojnë me përgatitjen e hyrjes. Vlerësoni çdo dërgesë përpara se ta shtoni në një grup, por shmangni rregullat që mund të refuzojnë pa dashje numra të ligjshëm gjurmimi nga transportues të ndryshëm.
- Ruajini numrat e gjurmimit si vargje. Shndërrimi i tyre në numra mund të heqë zerot në fillim ose të ndryshojë identifikuesit e gjatë.
- Hiqni hapësirat e tepërta rrethuese. Mos hiqni karakteret e brendshme dhe mos ndryshoni shkronjat e mëdha e të vogla, përveçse kur specifikimi përkatës lejon një normalizim të tillë.
- Vlerësoni fushat e kërkuara. Disa procese mund të kërkojnë një identifikues transportuesi ose informacion shtesë për dërgesën. Përdorni vetëm emra dhe vlera fushash të dokumentuara.
- Zgjidhni një fushëveprim të qartë për heqjen e dublikatave. Një numër i përsëritur gjurmimi nuk është automatikisht dublikatë në çdo transportues, tregtar ose dërgesë historike.
- Mbani një identifikues lokal të dërgesës. Ruani lidhjen midis artikullit të dërguar dhe regjistrimit të porosisë ose dërgesës suaj, edhe kur API-ja nuk pranon fusha reference të personalizuara.
Për Carrier Tracking në disa rrjete, mos e përcaktoni transportuesin vetëm nga gjatësia ose prefiksi i numrit të gjurmimit, përveçse kur ky përfundim është i besueshëm për procesin tuaj specifik. Kur API-ja mbështet identifikimin e transportuesit, ndiqni sjelljen e dokumentuar për trajtimin e paqartësive.
Struktura ilustruese e kërkesës
JSON-i i mëposhtëm tregon konceptin e një ngarkese grupi. Mbështjellësi, emrat e vetive dhe identifikuesit janë ilustrues dhe nuk përbëjnë skemën e kërkesës së 17TRACK. Disa API kërkojnë një varg në nivelin kryesor në vend të një objekti që përmban një varg.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Ndërtoni ngarkesën përmes një serializuesi JSON dhe jo duke bashkuar vargje. Dërgoni kredencialet e autentikimit përmes mekanizmit të dokumentuar dhe mbajini jashtë kontrollit të versioneve, kodit të dërguar në shfletues dhe regjistrave rutinë.
Përpunoni përgjigjen në dy nivele
Një kërkesë grupi ka një rezultat në nivel transporti dhe një rezultat në nivel aplikacioni. Integrimi juaj duhet t'i vlerësojë të dyja.
Niveli 1: A mori kërkesa një përgjigje të përdorshme?
Filloni me statusin HTTP, kokat e përgjigjes dhe trupin e përgjigjes. Gabimet e autentikimit, kërkesat e keqformuara, kufizimi i shpejtësisë dhe dështimet e serverit mund të pengojnë përpunimin normal të elementeve. Një skadim i kohës së rrjetit është ndryshe: klienti mund të mos e dijë nëse serveri e mori ose e përpunoi kërkesën.
Semantika HTTP përcaktohet në RFC 9110. Megjithatë, dokumentacioni i ofruesit përcakton se si fushat e rezultatit në nivel aplikacioni lidhen me rezultatet faktike të dërgesave.
Niveli 2: Çfarë ndodhi me çdo dërgesë?
Nëse përgjigjja mbështet rezultate në nivel elementi, klasifikoni çdo regjistrim të dërguar. Mos supozoni se HTTP 200 do të thotë se çdo regjistrim ka sukses, ose se lista e rezultateve ruan rendin e kërkesës, përveçse kur kontrata e garanton shprehimisht këtë.
- Pranuar: Veprimi pati sukses sipas përkufizimit të dokumentuar të pikës fundore.
- Dështim i përhershëm i hyrjes: Korrigjoni ose hetoni regjistrimin përpara një përpjekjeje tjetër.
- Dështim i riprovueshëm: Planifikoni një përpjekje tjetër sipas udhëzimeve të ofruesit për riprovim.
- Rezultat i panjohur: Përgjigjja mungon, është e paplotë ose nuk mund të përputhet në mënyrë të sigurt me regjistrimin e dërguar.
Mbajini përgjigjet si “already registered” ose përgjigje të ngjashme që lidhen me dublikatat të ndara derisa të kuptoni kuptimin e tyre të dokumentuar. Ato mund të tregojnë se gjendja e dëshiruar tashmë ekziston, por nuk duhet të trajtohen automatikisht si konfirmim i suksesit të pronësisë, konfigurimit ose abonimit.
Pas përpunimit të një përgjigjeje, çdo regjistrim hyrës duhet të ketë saktësisht një rezultat lokal. Një kontroll i dobishëm pajtimi është: regjistrimet e dërguara janë të barabarta me regjistrimet e pranuara plus dështimet e përhershme plus dështimet e riprovueshme plus rezultatet e panjohura. Ky është një rregull lokal llogaritjeje, jo format i kërkuar i përgjigjes së API-së.
Trajtoni dështimet e pjesshme pa riluajtur regjistrimet e suksesshme
Supozoni se një grup ilustrues përmban dhjetë dërgesa: shtatë pranohen, dy kanë fusha të kërkuara të pavlefshme dhe një has një gabim të përkohshëm të dokumentuar. Ruani rezultatet e shtatë sukseseve, dërgoni dy regjistrimet e pavlefshme për korrigjim dhe provoni sërish vetëm dështimin e përkohshëm.
Riluajtja e të dhjetë regjistrimeve krijon trafik të panevojshëm dhe mund të ndërlikojë trajtimin e dublikatave. Gjithashtu e bën më të vështirë dallimin midis një refuzimi fillestar dhe një përgjigjeje të mëvonshme që lidhet me dublikatën.
| Rezultati | Veprimi i rekomanduar |
|---|---|
| Fushë e pavlefshme ose vlerë e pambështetur | Korrigjoni hyrjen; mos e riprovoni pa ndryshime |
| Dështim autentikimi ose lejeje | Pezulloni punën e prekur dhe rregulloni kredencialet ose aksesin |
| Përgjigje për kufizim shpejtësie | Vonesoni sipas udhëzimeve të dokumentuara dhe kokave përkatëse të përgjigjes |
| Gabim i përkohshëm në nivel elementi | Riprovoni atë element me përpjekje të kufizuara dhe rritje graduale të vonesës |
| Skadim kohe pas dërgimit | Shënojeni si të pasigurt; pajtojeni ose përdorni garancitë e dokumentuara të sigurisë së riprovimit |
| Rezultat i panjohur ose i paplotë | Ruani provat dhe hetoni në vend që të supozoni sukses |
HTTP 429 tregon shumë kërkesa dhe përgjigjja e tij mund të përfshijë një kokë Retry-After, siç përshkruhet në RFC 6585. Mos supozoni se kjo kokë është gjithmonë e pranishme. Kur nuk jepet vonesë e qartë riprovimi, përdorni një politikë vonese të kufizuar në përputhje me dokumentacionin e API-së.
Shtoni luhatje të rastësishme për t'i shpërndarë riprovimet nga punonjës të shumtë, vendosni një numër maksimal përpjekjesh ose një moshë maksimale riprovimi dhe dërgoni regjistrimet e shteruara në një radhë shqyrtimi. Riprovimi pa kufi mund të fshehë një problem të qëndrueshëm konfigurimi.
Pse skadimet e kohës kërkojnë trajtim të veçantë
Një skadim kohe nuk provon refuzimin. Serveri mund ta ketë pranuar grupin përpara se lidhja të dështonte. Prandaj, riluajtja automatike e një kërkese që ndryshon gjendjen mund të përsërisë punën.
Nëse pika fundore mbështet çelësa idempotence të dokumentuar, ndiqni rregullat e saj, përfshirë fushëveprimin dhe ruajtjen e çelësit. Mos shpikni një kokë idempotence dhe mos supozoni se serveri e respekton. Përndryshe, përdorni një proces të mbështetur kërkimi ose pajtimi për të përcaktuar nëse ekziston gjendja e dëshiruar përpara ridërgimit. Heqja lokale e dublikatave ndihmon në koordinimin e punonjësve tuaj, por nuk garanton idempotencë në anën e serverit.
Një proces praktik për përpunimin e grupeve
Mbajini detajet specifike të ofruesit në një përshtatës, në mënyrë që radha, planifikuesi i riprovimeve dhe logjika e monitorimit të mos varen nga emrat e papërpunuar të fushave të përgjigjes.
validate records and retain local shipment IDs
resolve duplicates within the intended business scope
split records using documented item and payload limits
for each batch through a bounded worker pool:
persist an attempt record before sending
wait for the shared rate limiter
send using the provider-specific adapter
if the outcome is uncertain:
enqueue reconciliation
continue
classify request-level and item-level outcomes
persist one outcome for every submitted record
schedule only eligible failures for retry
route invalid or exhausted records for review
Bëjeni ruajtjen e rezultateve dhe planifikimin e riprovimeve të rikuperueshme. Për shembull, një regjistrim i qëndrueshëm pune ose një model transaksional radhimi mund të parandalojë që një rrëzim i procesit të humbasë vendimin për riprovim. Kur punonjësit rinisin, ata duhet të jenë në gjendje të dallojnë punën e padërguar nga puna, rezultati në distancë i së cilës është ende i pasigurt.
Përdorni madhësinë e grupit si një cilësim të konfigurueshëm të lidhur me pikën fundore përkatëse, jo si një konstante të shpërndarë në të gjithë bazën e kodit. Një grup më i vogël mund të jetë i dobishëm gjatë diagnostikimit ose izolimit të regjistrimeve problematike; grupi më i madh i lejuar nuk është automatikisht madhësia më e mirë e funksionimit.
Monitoroni rezultatet e dërgesave, jo vetëm kohën e funksionimit HTTP
API Monitoring duhet të tregojë nëse dërgesat po arrijnë gjendjen e synuar. Një panel që raporton vetëm nivelet e suksesit HTTP mund të mos zbulojë dështimet e pjesshme brenda përgjigjeve përndryshe të suksesshme.
- Shkalla e pranimit të elementeve: Regjistrimet e pranuara pjesëtuar me regjistrimet e dërguara, me trajtim të përcaktuar qartë të riprovimeve.
- Shpërndarja e dështimeve: Numërimet sipas pikës fundore, kodit të dokumentuar të gabimit dhe kontekstit përkatës të transportuesit.
- Rezultatet e panjohura: Regjistrimet e papajtuara dhe koha që kanë mbetur të pazgjidhura.
- Ngarkesa e riprovimeve: Riprovimet në pritje, mosha e riprovimit më të vjetër dhe përpjekjet e shteruara.
- Gjendja e kërkesave: Vonesa, skadime kohe, kufizim shpejtësie dhe gabime serveri.
- Freskia e gjurmimit: Nëse dërgesat e pranuara marrin më pas informacion të përdorshëm gjurmimi.
Pranimi i regjistrimit nuk është provë e një skanimi të ri nga transportuesi. Mbajeni statusin e përpunimit të API-së të ndarë nga lëvizja e dërgesës dhe freskia e të dhënave, në mënyrë që një incident integrimi të mos ngatërrohet me një vonesë dorëzimi.
Regjistroni ID-të lokale të grupeve, referencat e dërgesave, numrin e përpjekjeve, kodet e dokumentuara të gabimeve dhe ID-të e kërkesave të ofruesit kur janë të disponueshme. Redaktoni kredencialet dhe informacionin personal të panevojshëm. Përdorni identifikuesit e gjurmimit vetëm kur janë të nevojshëm operacionalisht dhe shmangni vendosjen e identifikuesve të papërpunuar të dërgesave në etiketat e metrikave me kardinalitet të lartë.
Testoni këto raste përpara prodhimit
Përdorni një sandbox të dokumentuar ose mjedis testimi të kontrolluar kur është i disponueshëm. Mos supozoni se numrat e shpikur të gjurmimit do të prodhojnë përgjigje të parashikueshme në prodhim.
- Dërgoni një grup të vlefshëm në kufirin e dokumentuar të elementeve, më pas testoni se si klienti juaj parandalon një grup me madhësi të tepërt.
- Verifikoni që numrat e gjurmimit me zero në fillim mbijetojnë serializimit dhe ruajtjes.
- Testoni elemente të pranuara dhe të refuzuara së bashku pa riprovuar regjistrimet e suksesshme.
- Simuloni kufizimin e shpejtësisë dhe konfirmoni që punonjës të shumtë respektojnë të njëjtin kufi.
- Simuloni një skadim kohe pas dërgimit dhe verifikoni rrugën e pajtimit.
- Rinisni një punonjës midis marrjes së përgjigjes dhe ruajtjes lokale.
- Testoni rezultate elementesh që mungojnë, janë të panjohura ose nuk mund të përputhen.
- Konfirmoni që regjistrimet e pavlefshme arrijnë një radhë të dukshme korrigjimi në vend që të riprovohen pafundësisht.
Një integrim i gatshëm për prodhim mund të shpjegojë gjendjen e çdo dërgese të dërguar, përfshirë ato rezultatet e të cilave janë përkohësisht të panjohura. Ulja e numrit të kërkesave është e dobishme; ruajtja e kësaj përgjegjshmërie është qëllimi më i rëndësishëm i projektimit.
Pyetje të shpeshta
Sa numra gjurmimi mund të dërgoj në një kërkesë?
Përdorni kufirin e dokumentuar për pikën fundore dhe versionin e saktë të API-së. Kontrolloni gjithashtu madhësinë e kërkesës, kufijtë e shpejtësisë dhe çdo kufizim specifik të llogarisë. Nuk ka një numër universal të sigurt që mund të zbatohet në të gjitha API-të e gjurmimit ose në veprime të ndryshme brenda së njëjtës API.
A mund të shkaktojë një numër i pavlefshëm gjurmimi dështimin e gjithë grupit?
Po, në varësi të rregullave të vlerësimit të pikës fundore. Disa API kthejnë refuzime individuale, ndërsa të tjera mund ta refuzojnë kërkesën përpara përpunimit të elementeve. Kontrolloni si gabimet në nivel kërkese, ashtu edhe rezultatet në nivel elementi; mos supozoni se çdo pikë fundore grupi mbështet pranimin e pjesshëm.
A duhet ta riprovoj një grup kur përgjigjja HTTP është e suksesshme?
Jo automatikisht. Së pari analizoni statusin e dokumentuar në nivel aplikacioni dhe rezultatet e elementeve. Ruani regjistrimet e suksesshme dhe riprovoni vetëm dështimet e përshtatshme. Nëse rezultati nuk mund të interpretohet në mënyrë të sigurt, klasifikojeni si të pasigurt dhe hetojeni.
A mund të përziej transportues në të njëjtin grup?
Vetëm kur pika fundore e mbështet atë strukturë kërkese. Konfirmoni nëse informacioni i transportuesit jepet për çdo dërgesë, nëse mbështetet identifikimi automatik dhe çfarë ndodh kur identifikimi është i paqartë. Një shërbim me shumë transportues nuk përcakton vetvetiu rregullat e grupimit të çdo pike fundore.
A i bën grupimi përditësimet e gjurmimit të mbërrijnë më shpejt?
Grupimi mund të ulë numrin e kërkesave që dërgon aplikacioni juaj, por nuk i bën vetvetiu ngjarjet e transportuesit të shfaqen më herët. Regjistrimi, marrja e të dhënave, disponueshmëria e skanimit nga transportuesi dhe dërgimi i përditësimeve janë pjesë të ndara të procesit.
Burimet
- 17TRACK Tracking API — pikënisja zyrtare e produktit për zhvilluesit që vlerësojnë një integrim gjurmimi.
- Dokumentacioni i API-së 17TRACK — referencë për kontratën e pikës fundore specifike të ofruesit, kufijtë, autentikimin dhe trajtimin e përgjigjeve.
- RFC 9110: Semantika HTTP — semantika e kodeve të statusit HTTP, idempotenca, riprovimet automatike dhe Retry-After.
- RFC 6585: Kode shtesë të statusit HTTP — përkufizimi i HTTP 429 Too Many Requests dhe kokës opsionale Retry-After.


