Több nyomonkövetési szám küldése egyetlen API-kérésben (kötegkorlátok és részleges hibák)
Ha több nyomkövetési számot szeretne elküldeni egyetlen API-kérésben, használjon olyan Tracking API-végpontot, amely kifejezetten támogatja a kötegelt feldolgozást, formázza az egyes küldeményeket a kérés sémája szerint, és ossza fel a nagyobb listákat a dokumentált korlátokon belüli kötegekre. Ezután vizsgálja meg mind a HTTP-választ, mind az egyes küldemények eredményét: a sikeres HTTP-kérés nem feltétlenül jelenti azt, hogy minden nyomkövetési szám elfogadásra került. Csak a jogosult hibákat próbálja újra, és a teljes köteg újbóli elküldése előtt egyeztesse a bizonytalan kimeneteleket.

Ez az útmutató azoknak a fejlesztőknek szól, akik a küldemények nyomkövetését rendeléskezelő rendszerhez, raktárplatformhoz, e-kereskedelmi alkalmazáshoz vagy belső irányítópulthoz kapcsolják. A cél nem pusztán a kevesebb kérés küldése. Minden küldeményt nyilván kell tartani anélkül, hogy ismételt munkát hoznánk létre, vagy elveszítenénk a sikertelen rekordokat.
Először azonosítsa, mit végez valójában a kötegelt végpont
Egy nyomkövetési integráció több különböző műveletet foglalhat magában. A küldemények regisztrálása, a legfrissebb nyomkövetési információk lekérése és a későbbi frissítések fogadása nem felcserélhető műveletek.
- Regisztráció: Küldemények beküldése, hogy a szolgáltatás megkezdhesse vagy fenntarthassa a nyomkövetést.
- Lekérdezés: Nyomkövetési információk kérése a küldeményekhez, a végpont lekérdezési szabályainak megfelelően.
- Kézbesítés frissítése: Későbbi változások fogadása támogatott mechanizmuson, például webhookokon keresztül, vagy lekérésük ütemezett kérésekkel.
A pontosan szükséges műveletért tekintse át a dokumentációt. Az, hogy egy több rekordot elfogadó regisztrációs végpont létezik, nem jelenti azt, hogy egy lekérdezési végpont ugyanennyi rekordot fogad el, ugyanazt a sémát használja vagy ugyanazzal a sebességkorláttal rendelkezik.
17TRACK-integráció esetén kezdje a Tracking API termékoldalával, és a hivatalos API-dokumentáció segítségével erősítse meg a műveletet, a hitelesítési módot, a kérés formátumát és a válasz mezőit. Az alábbi példákat megvalósítási mintáknak tekintse, ne az adott API-szerződés helyettesítőjének.
A kötegkorlátok nem merülnek ki a küldemények maximális számában
Nincs univerzális kötegkorlát egy Tracking API-hoz. A korlátok szolgáltatónként, végpontonként, API-verziónként és a fiók konfigurációjától függően eltérhetnek. A kötegelés megvalósítása előtt külön rögzítse ezeket a korlátozásokat.
| Korlátozás | Mit kell megerősíteni | Megvalósítási következmény |
|---|---|---|
| Kéréselemek száma | Az adott művelethez tartozó maximális rekordszám | A bemeneti lista felosztása küldés előtt |
| Kérés törzsének mérete | Bármely dokumentált bájtkorlát | Az opcionális mezők és a szerializálási méret figyelembevétele |
| Kéréssebesség | A meghatározott időintervallumban engedélyezett kérések száma | A kérések ütemezése közös korlátozón keresztül |
| Párhuzamosság | Bármely egyidejű kérésre vonatkozó korlátozás | Az aktív feldolgozók számának korlátozása |
| Használat elszámolása | A használatot kérés, küldemény vagy más egység alapján számítják-e | A fogyasztás becslése a kérések számától elkülönítve |
Ha például egy hipotetikus végpont kérésenként 25 rekordot engedélyez, akkor 63 rekordhoz három kérés szükséges, amelyek 25, 25 és 13 rekordot tartalmaznak. Ezek a számok csak a darabolást szemléltetik; nem a 17TRACK korlátai.
Ne feltételezze, hogy a kötegelés csökkenti a számlázott használatot. Mérsékelheti a HTTP-kérések többletterhelését, de a díjakra gyakorolt hatás a szolgáltató tényleges elszámolási szabályaitól függ. Hasonlóképpen, az érvényes kötegméret nem jogosít korlátlan számú párhuzamos kérésre.
Készítse elő a rekordokat a kérés felépítése előtt
A legtöbb elkerülhető kötegelt hiba a bemenet előkészítésével kezdődik. Minden küldeményt ellenőrizzen, mielőtt köteghez adná, de kerülje azokat a szabályokat, amelyek véletlenül elutasítják a különböző fuvarozóktól származó érvényes nyomkövetési számokat.
- A nyomkövetési számokat szövegként őrizze meg. Számokká alakításuk eltávolíthatja a kezdő nullákat vagy módosíthatja a hosszú azonosítókat.
- Távolítsa el a véletlenül hozzáadott környező szóközöket. Ne távolítsa el a belső karaktereket, és ne módosítsa a kis- és nagybetűket, kivéve, ha a vonatkozó specifikáció engedélyezi az ilyen normalizálást.
- Ellenőrizze a kötelező mezőket. Egyes munkafolyamatok fuvarozóazonosítót vagy további küldeményinformációkat igényelhetnek. Csak dokumentált mezőneveket és értékeket használjon.
- Határozzon meg egyértelmű deduplikációs hatókört. Egy ismétlődő nyomkövetési szám nem automatikusan duplikátum minden fuvarozó, kereskedő vagy korábbi küldemény esetében.
- Tartson fenn helyi küldeményazonosítót. Tárolja a kapcsolatot a kimenő tétel és a rendelési vagy küldeményrekord között akkor is, ha az API nem fogad el egyéni hivatkozási mezőket.
Több hálózaton végzett Carrier Tracking esetén ne következtesse ki a fuvarozót kizárólag a nyomkövetési szám hosszából vagy előtagjából, hacsak ez a következtetés nem megbízható az adott munkafolyamatban. Ha az API támogatja a fuvarozó azonosítását, kövesse a dokumentált, nem egyértelmű esetek kezelésére vonatkozó viselkedését.
Szemléltető kérésstruktúra
Az alábbi JSON egy kötegelt törzs koncepcióját mutatja be. A burkolóelem, a tulajdonságnevek és az azonosítók szemléltető jellegűek, nem egy 17TRACK-kérés sémáját jelentik. Egyes API-k legfelső szintű tömböt várnak objektum helyett, amely tömböt tartalmaz.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}A törzset karakterláncok összefűzése helyett JSON-szerializálóval állítsa elő. A hitelesítési adatokat a dokumentált mechanizmuson keresztül küldje, és tartsa távol őket a forráskódtól, a böngészőbe küldött kódtól és a szokásos naplóktól.
Dolgozza fel a választ két szinten
Egy kötegelt kérésnek van átviteli szintű és alkalmazásszintű kimenetele. Az integrációnak mindkettőt értékelnie kell.
1. szint: Érkezett használható válasz a kérésre?
Kezdje a HTTP-állapottal, a válaszfejlécekkel és a válasz törzsével. A hitelesítési hibák, a hibásan formázott kérések, a sebességkorlátozás és a szerverhibák megakadályozhatják a normál tételfeldolgozást. A hálózati időtúllépés más eset: az ügyfél nem biztos, hogy tudja, a szerver megkapta vagy feldolgozta-e a kérést.
A HTTP-szemantikát az RFC 9110 határozza meg. A szolgáltató dokumentációja határozza meg azonban, hogy az alkalmazásszintű eredménymezők hogyan feleltethetők meg a tényleges küldeménykimeneteleknek.
2. szint: Mi történt az egyes küldeményekkel?
Ha a válasz támogatja a tételszintű eredményeket, minden beküldött rekordot soroljon be. Ne feltételezze, hogy a HTTP 200 minden rekord sikerét jelenti, vagy hogy az eredménylista megőrzi a kérés sorrendjét, hacsak a szerződés ezt kifejezetten nem garantálja.
- Elfogadva: A művelet a végpont dokumentált meghatározása szerint sikeres volt.
- Végleges bemeneti hiba: Javítsa ki vagy vizsgálja ki a rekordot újabb próbálkozás előtt.
- Újrapróbálható hiba: Ütemezzen újabb próbálkozást a szolgáltató újrapróbálási útmutatója szerint.
- Ismeretlen kimenetel: A válasz hiányzik, hiányos, vagy nem párosítható biztonságosan a beküldött rekorddal.
Az „már regisztrálva” vagy hasonló, duplikációval kapcsolatos válaszokat tartsa elkülönítve, amíg nem érti dokumentált jelentésüket. Jelezhetik, hogy a kívánt állapot már fennáll, de nem szabad automatikusan sikeres tulajdonjogi, konfigurációs vagy előfizetés-visszaigazolásként kezelni őket.
A válasz feldolgozása után minden bemeneti rekordhoz pontosan egy helyi kimenetelnek kell tartoznia. Hasznos egyeztetési ellenőrzés: a beküldött rekordok száma egyenlő az elfogadott rekordok, a végleges hibák, az újrapróbálható hibák és az ismeretlen kimenetelek összegével. Ez helyi elszámolási szabály, nem kötelező API-válaszformátum.
Kezelje a részleges hibákat a sikeres rekordok újbóli lejátszása nélkül
Tegyük fel, hogy egy szemléltető köteg tíz küldeményt tartalmaz: hetet elfogadnak, kettőnél hiányoznak vagy érvénytelenek a kötelező mezők, egy pedig dokumentált ideiglenes hibába ütközik. Mentse a hét sikeres kimenetelt, küldje a két hibás rekordot javításra, és csak az ideiglenesen hibás tételt próbálja újra.
Mind a tíz rekord újrajátszása szükségtelen forgalmat generálhat, és megnehezítheti a duplikációk kezelését. Emellett nehezebb megkülönböztetni az eredeti elutasítást a későbbi, duplikációval kapcsolatos választól.
| Kimenetel | Javasolt művelet |
|---|---|
| Érvénytelen mező vagy nem támogatott érték | Javítsa a bemenetet; változatlanul ne próbálja újra |
| Hitelesítési vagy jogosultsági hiba | Szüneteltesse az érintett munkát, és javítsa a hitelesítő adatokat vagy a hozzáférést |
| Sebességkorlátozási válasz | Késleltesse a dokumentált útmutató és az alkalmazandó válaszfejlécek szerint |
| Ideiglenes tételszintű hiba | Próbálja újra az adott tételt korlátozott számú kísérlettel és visszalépéssel |
| Beküldés utáni időtúllépés | Jelölje bizonytalanként; egyeztesse, vagy használja a dokumentált újrapróbálási biztonsági garanciákat |
| Fel nem ismert vagy hiányos eredmény | Őrizze meg a bizonyítékokat és vizsgálja ki ahelyett, hogy sikert feltételezne |
A HTTP 429 túl sok kérést jelenthet, és a válasz tartalmazhat Retry-After fejlécet, az RFC 6585 leírása szerint. Ne feltételezze, hogy ez a fejléc mindig jelen van. Ha nincs explicit újrapróbálási késleltetés megadva, használjon az API dokumentációjával összhangban álló, korlátozott visszalépési szabályzatot.
Adjon véletlenszerű késleltetést a több feldolgozó újrapróbálásainak szétosztásához, állítson be maximális kísérletszámot vagy újrapróbálási időt, és küldje az elhasznált rekordokat ellenőrzési sorba. A végtelen újrapróbálás elrejthet egy tartós konfigurációs problémát.
Miért igényelnek különleges kezelést az időtúllépések?
Az időtúllépés nem bizonyítja az elutasítást. Lehet, hogy a szerver elfogadta a köteget, mielőtt a kapcsolat megszakadt. Az állapotmódosító kérés automatikus újraküldése ezért megismételheti a munkát.
Ha a végpont támogatja a dokumentált idempotenciakulcsokat, kövesse a szabályait, beleértve a kulcs hatókörét és megőrzését is. Ne találjon ki idempotencia-fejlécet, és ne feltételezze, hogy a szerver kezeli azt. Ellenkező esetben használjon támogatott lekérdezési vagy egyeztetési munkafolyamatot annak meghatározására, hogy a kívánt állapot fennáll-e, mielőtt újraküldené a kérést. A helyi deduplikáció segíti a saját feldolgozók koordinációját, de nem garantálja a szerveroldali idempotenciát.
Gyakorlati kötegelt feldolgozási munkafolyamat
Tartsa a szolgáltató-specifikus részleteket egy adapterben, hogy a sor, az újrapróbálás-ütemező és a megfigyelési logika ne függjön a nyers válaszmezők neveitől.
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
Az eredménymegőrzést és az újrapróbálások ütemezését tegye helyreállíthatóvá. Például egy tartós feladatrekord vagy tranzakciós sorba állítási minta megakadályozhatja, hogy egy folyamatösszeomlás elveszítse az újrapróbálási döntést. A feldolgozóknak újraindításkor meg kell tudniuk különböztetni az el nem küldött munkát attól a munkától, amelynek távoli kimenetele még bizonytalan.
A kötegméret legyen konfigurálható beállítás, amely az adott végponthoz kapcsolódik, ne pedig a kódbázisban szétszórt konstans. Hibaelhárításkor vagy problémás rekordok elkülönítésekor hasznos lehet kisebb köteget használni; a legnagyobb engedélyezett köteg nem automatikusan a legjobb működési méret.
Ne csak a HTTP-üzemidőt, hanem a küldemények kimenetelét is figyelje
Az API Monitoringnak meg kell mutatnia, hogy a küldemények elérik-e a kívánt állapotot. A kizárólag HTTP-sikerességi arányokat jelentő irányítópultok nem feltétlenül észlelik az egyébként sikeres válaszokon belüli részleges hibákat.
- Tétel-elfogadási arány: Az elfogadott rekordok osztva a beküldött rekordokkal, az újrapróbálások egyértelműen meghatározott kezelésével.
- Hibák eloszlása: Darabszám végpontonként, dokumentált hibakódonként és releváns fuvarozói környezet szerint.
- Ismeretlen kimenetelek: Az egyeztetetlen rekordok és az az idő, amióta megoldatlanok.
- Újrapróbálási hátralék: Függőben lévő újrapróbálások, a legrégebbi újrapróbálás kora és a kimerített kísérletek.
- Kérésállapot: Késleltetés, időtúllépések, sebességkorlátozás és szerverhibák.
- Nyomkövetési frissesség: Az elfogadott küldemények később kapnak-e használható nyomkövetési információkat.
A regisztráció elfogadása nem bizonyítja az új fuvarozói szkennelést. Tartsa külön az API-feldolgozás állapotát a küldemény mozgásától és az adatok frissességétől, hogy egy integrációs incidenst ne keverjen össze kézbesítési késéssel.
Naplózza a helyi kötegazonosítókat, a küldeményhivatkozásokat, a kísérletek számát, a dokumentált hibakódokat és a szolgáltató kérésazonosítóit, ha rendelkezésre állnak. Takarja ki a hitelesítő adatokat és a szükségtelen személyes információkat. Nyomkövetési azonosítókat csak működésileg szükséges esetben használjon, és kerülje a nyers küldeményazonosítók elhelyezését nagy kardinalitású metrikacímkékben.
Ezeket az eseteket tesztelje élesítés előtt
Ha lehetséges, használjon dokumentált sandboxot vagy ellenőrzött tesztkörnyezetet. Ne feltételezze, hogy a kitalált nyomkövetési számok kiszámítható éles válaszokat eredményeznek.
- Küldjön be egy érvényes köteget a dokumentált tételkorlátnál, majd tesztelje, hogyan akadályozza meg az ügyfél a túlméretezett köteget.
- Ellenőrizze, hogy a kezdő nullákat tartalmazó nyomkövetési számok megmaradnak-e a szerializálás és a tárolás során.
- Tesztelje az elfogadott és elutasított tételek keverékét a sikeres rekordok újrapróbálása nélkül.
- Szimulálja a sebességkorlátozást, és erősítse meg, hogy több feldolgozó ugyanazt a korlátot tartja be.
- Szimuláljon beküldés utáni időtúllépést, és ellenőrizze az egyeztetési útvonalat.
- Indítson újra egy feldolgozót a válasz fogadása és a helyi megőrzés között.
- Tesztelje a hiányzó, ismeretlen vagy nem párosítható tételeredményeket.
- Erősítse meg, hogy az érvénytelen rekordok látható javítási sorba kerülnek ahelyett, hogy örökké újrapróbálná őket.
Egy éles használatra kész integráció meg tudja magyarázni minden beküldött küldemény állapotát, beleértve azokat is, amelyek kimenetele átmenetileg ismeretlen. A kérések számának csökkentése hasznos; ennek az elszámoltathatóságnak a megőrzése azonban fontosabb tervezési cél.
GYIK
Hány nyomkövetési számot küldhetek egy kérésben?
Az adott végponthoz és API-verzióhoz dokumentált korlátot használja. Ellenőrizze a kérés méretét, a sebességkorlátokat és a fiókspecifikus korlátozásokat is. Nincs olyan biztonságosan alkalmazható univerzális szám, amely minden Tracking API-ra vagy ugyanazon API különböző műveleteire érvényes lenne.
Okozhatja-e egy érvénytelen nyomkövetési szám a teljes köteg sikertelenségét?
Igen, a végpont érvényesítési szabályaitól függően. Egyes API-k egyéni elutasításokat adnak vissza, míg mások már a tételek feldolgozása előtt elutasíthatják a kérést. Ellenőrizze mind a kérés szintű hibákat, mind a tételszintű eredményeket; ne feltételezze, hogy minden kötegelt végpont támogatja a részleges elfogadást.
Újra kell próbálnom egy köteget, ha a HTTP-válasz sikeres?
Nem automatikusan. Először elemezze a dokumentált alkalmazásszintű állapotot és a tételeredményeket. Mentse a sikeres rekordokat, és csak a jogosult hibákat próbálja újra. Ha az eredmény nem értelmezhető biztonságosan, sorolja bizonytalan kategóriába, és vizsgálja ki.
Kevertethetek fuvarozókat ugyanabban a kötegben?
Csak akkor, ha a végpont támogatja ezt a kérésstruktúrát. Erősítse meg, hogy a fuvarozói információ küldeményenként adható-e meg, támogatott-e az automatikus azonosítás, és mi történik, ha az azonosítás nem egyértelmű. A többfuvarozós szolgáltatás önmagában nem határozza meg minden végpont kötegelési szabályait.
Gyorsabban érkeznek meg a nyomkövetési frissítések a kötegeléstől?
A kötegelés csökkentheti az alkalmazás által küldött kérések számát, de önmagában nem gyorsítja fel a fuvarozói események megjelenését. A regisztráció, az adatok lekérése, a fuvarozói szkennelések elérhetősége és a frissítések kézbesítése a munkafolyamat különálló részei.
Források
- 17TRACK Tracking API — hivatalos kiindulópont a nyomkövetési integrációt értékelő fejlesztők számára.
- 17TRACK API-dokumentáció — hivatkozás a szolgáltató-specifikus végponti szerződéshez, korlátokhoz, hitelesítéshez és válaszkezeléshez.
- RFC 9110: HTTP-szemantika — HTTP-állapotok szemantikája, idempotencia, automatikus újrapróbálások és Retry-After.
- RFC 6585: További HTTP-állapotkódok — a HTTP 429 Too Many Requests és az opcionális Retry-After fejléc meghatározása.


