Skip to main content
DomůBlogPrůvodciJak odeslat více sledovacích čísel v jednom požadavku API (limity dávek a částečná selhání)

Jak odeslat více sledovacích čísel v jednom požadavku API (limity dávek a částečná selhání)

17TRACK

Chcete-li odeslat více sledovacích čísel v jednom požadavku API, použijte koncový bod Tracking API, který výslovně přijímá dávky, naformátujte každou zásilku podle jeho schématu požadavku a větší seznamy rozdělte do dávek v rámci zdokumentovaných limitů. Poté zkontrolujte jak HTTP odpověď, tak výsledek každé zásilky: úspěšný HTTP požadavek nemusí nutně znamenat, že byla přijata všechna sledovací čísla. Opakujte pouze způsobilá selhání a před opětovným odesláním celé dávky slaďte nejisté výsledky.

Jak odeslat více sledovacích čísel v jednom požadavku API

Tato příručka je určena vývojářům, kteří propojují sledování zásilek se systémem pro správu objednávek, skladovou platformou, e-commerce aplikací nebo interním panelem. Cílem není pouze odesílat méně požadavků. Jde o evidenci každé zásilky bez vytváření duplicitní práce nebo ztráty neúspěšných záznamů.

Nejprve zjistěte, co dávkový koncový bod skutečně provádí

Integrace sledování může zahrnovat několik odlišných operací. Registrace zásilek, získávání jejich nejnovějších informací o sledování a přijímání následných aktualizací nejsou vzájemně zaměnitelné.

  • Registrace: Odeslání zásilek, aby služba mohla zahájit nebo udržovat jejich sledování.
  • Vyhledání: Vyžádání informací o sledování zásilek v souladu s pravidly načítání daného koncového bodu.
  • Aktualizace doručení: Přijímání pozdějších změn prostřednictvím podporovaného mechanismu, například webhooků, nebo jejich načítání prostřednictvím plánovaných požadavků.

V dokumentaci ověřte přesnou operaci, kterou potřebujete. Registrační koncový bod přijímající více záznamů nepotvrzuje, že koncový bod pro vyhledávání přijímá stejný počet záznamů, používá stejné schéma nebo má stejný rychlostní limit.

U integrace 17TRACK začněte na stránce produktu Tracking API a pomocí oficiální dokumentace API ověřte operaci, metodu ověřování, formát požadavku a pole odpovědi. Níže uvedené příklady považujte za implementační vzory, nikoli za náhradu smlouvy daného API.

Dávkové limity nejsou jen maximální počet zásilek

Pro Tracking API neexistuje univerzální limit dávky. Limity se mohou lišit podle poskytovatele, koncového bodu, verze API a konfigurace účtu. Před implementací dávkového zpracování tyto omezení evidujte samostatně.

OmezeníCo ověřitDůsledek pro implementaci
Položky na požadavekMaximální počet záznamů pro konkrétní operaciRozdělit vstupní seznam před odesláním
Velikost těla požadavkuJakýkoli zdokumentovaný limit v bajtechZohlednit volitelná pole a velikost serializace
Frekvence požadavkůPočet povolených požadavků během stanoveného intervaluŘídit rychlost požadavků prostřednictvím sdíleného omezovače
SouběžnostJakékoli omezení současných požadavkůOmezit počet aktivních pracovníků
Evidence využitíZda se využití počítá podle požadavku, zásilky nebo jiné jednotkyOdhadovat spotřebu odděleně od objemu požadavků

Pokud například hypotetický koncový bod povoluje 25 záznamů na požadavek, 63 záznamů vyžaduje tři požadavky obsahující 25, 25 a 13 záznamů. Tato čísla ilustrují pouze rozdělení do bloků; nejde o uvedené limity 17TRACK.

Nepředpokládejte, že dávkové zpracování snižuje účtované využití. Může snížit režii HTTP požadavků, ale jakýkoli dopad na poplatky závisí na skutečných pravidlech evidence poskytovatele. Stejně tak platná velikost dávky neopravňuje k neomezenému počtu paralelních požadavků.

Před sestavením požadavku připravte záznamy

Většina zbytečných selhání dávek začíná při přípravě vstupu. Každou zásilku před přidáním do dávky ověřte, ale vyhněte se pravidlům, která by náhodně odmítala platná sledovací čísla od různých přepravců.

  1. Uchovávejte sledovací čísla jako řetězce. Převod na čísla může odstranit počáteční nuly nebo změnit dlouhé identifikátory.
  2. Odstraňte náhodné okolní mezery. Neodstraňujte vnitřní znaky ani neměňte velikost písmen, pokud to příslušná specifikace nepovoluje.
  3. Ověřte povinná pole. Některé pracovní postupy mohou vyžadovat identifikátor přepravce nebo další informace o zásilce. Používejte pouze zdokumentované názvy a hodnoty polí.
  4. Zvolte explicitní rozsah deduplikace. Opakované sledovací číslo není automaticky duplicitou u každého přepravce, obchodníka nebo historické zásilky.
  5. Uchovávejte místní identifikátor zásilky. Uložte vztah mezi odesílanou položkou a záznamem objednávky nebo zásilky, i když API nepřijímá vlastní referenční pole.

U Carrier Tracking napříč více sítěmi neurčujte přepravce pouze podle délky nebo předpony sledovacího čísla, pokud tento závěr není spolehlivý pro váš konkrétní pracovní postup. Pokud API podporuje identifikaci přepravce, postupujte podle zdokumentovaného chování při nejednoznačnosti.

Ilustrační struktura požadavku

Následující JSON ukazuje koncept dávkového obsahu. Obálka, názvy vlastností a identifikátory jsou pouze ilustrační, nejde o schéma požadavku 17TRACK. Některá API očekávají pole nejvyšší úrovně namísto objektu obsahujícího pole.

{
  "shipments": [
    {
      "tracking_number": "EXAMPLE000001",
      "carrier_id": "DOCUMENTED_CARRIER_ID"
    },
    {
      "tracking_number": "EXAMPLE000002",
      "carrier_id": "DOCUMENTED_CARRIER_ID"
    }
  ]
}

Vytvářejte obsah pomocí serializátoru JSON, nikoli spojováním řetězců. Přihlašovací údaje odesílejte zdokumentovaným mechanismem a uchovávejte je mimo správu zdrojového kódu, kód doručovaný prohlížeči a běžné protokoly.

Odpověď zpracujte na dvou úrovních

Dávkový požadavek má výsledek na transportní úrovni a výsledek na aplikační úrovni. Integrace musí vyhodnotit oba.

Úroveň 1: Obdržel požadavek použitelnou odpověď?

Začněte stavem HTTP, hlavičkami odpovědi a tělem odpovědi. Chyby ověřování, nesprávně sestavené požadavky, omezení rychlosti a selhání serveru mohou zabránit běžnému zpracování položek. Síťový timeout je jiný případ: klient nemusí vědět, zda server požadavek přijal nebo zpracoval.

HTTP sémantiku definuje RFC 9110. Dokumentace poskytovatele však určuje, jak se jeho pole výsledků na aplikační úrovni mapují na skutečné výsledky zásilek.

Úroveň 2: Co se stalo s každou zásilkou?

Pokud odpověď podporuje výsledky na úrovni položek, zařaďte každý odeslaný záznam. Nepředpokládejte, že HTTP 200 znamená úspěch každého záznamu nebo že seznam výsledků zachovává pořadí požadavku, pokud to smlouva výslovně nezaručuje.

  • Přijato: Operace byla úspěšná podle zdokumentované definice koncového bodu.
  • Trvalé selhání vstupu: Před dalším pokusem záznam opravte nebo prošetřete.
  • Opakovatelné selhání: Naplánujte další pokus podle pokynů poskytovatele pro opakování.
  • Neznámý výsledek: Odpověď chybí, je neúplná nebo ji nelze bezpečně přiřadit k odeslanému záznamu.

Odpovědi typu „již zaregistrováno“ nebo podobné odpovědi související s duplicitou ponechte odděleně, dokud nepochopíte jejich zdokumentovaný význam. Mohou znamenat, že požadovaný stav již existuje, ale neměly by být automaticky považovány za potvrzení vlastnictví, konfigurace nebo předplatného.

Po zpracování odpovědi by každý vstupní záznam měl mít přesně jeden místní výsledek. Užitečná kontrola sladění je: odeslané záznamy se rovnají přijatým záznamům plus trvalým selháním plus opakovatelným selháním plus neznámým výsledkům. Jde o místní účetní pravidlo, nikoli o požadovaný formát odpovědi API.

Částečná selhání řešte bez opakovaného odesílání úspěšných záznamů

Představme si ilustrační dávku deseti zásilek: sedm je přijato, dvě mají neplatná povinná pole a u jedné dojde ke zdokumentované dočasné chybě. Uložte sedm úspěšných výsledků, dvě neplatné záznamy předejte k opravě a opakujte pouze dočasně neúspěšnou položku.

Opětovné odeslání všech deseti záznamů vytváří zbytečný provoz a může zkomplikovat řešení duplicit. Také ztěžuje rozlišení původního odmítnutí od pozdější odpovědi související s duplicitou.

VýsledekDoporučená akce
Neplatné pole nebo nepodporovaná hodnotaOpravte vstup; nezopakujte beze změny
Selhání ověřování nebo oprávněníPozastavte dotčenou práci a opravte přihlašovací údaje nebo přístup
Odpověď s omezením rychlostiOdložte podle zdokumentovaných pokynů a příslušných hlaviček odpovědi
Dočasná chyba na úrovni položkyOpakujte položku s omezeným počtem pokusů a exponenciálním čekáním
Timeout po odesláníOznačte jako nejisté; slaďte výsledek nebo použijte zdokumentované záruky bezpečnosti opakování
Nerozpoznaný nebo neúplný výsledekUchovejte důkazy a prošetřete situaci místo předpokladu úspěchu

HTTP 429 označuje příliš mnoho požadavků a jeho odpověď může obsahovat hlavičku Retry-After, jak je popsáno v RFC 6585. Nepředpokládejte, že je tato hlavička vždy přítomná. Pokud není uvedeno žádné explicitní zpoždění opakování, použijte omezenou zásadu čekání v souladu s dokumentací API.

Přidejte náhodnou odchylku, aby se opakování z více pracovníků rozložila, nastavte maximální počet pokusů nebo stáří opakování a vyčerpané záznamy odešlete do fronty ke kontrole. Neomezené opakování může skrýt trvalý problém s konfigurací.

Proč timeouty vyžadují zvláštní zacházení

Timeout nepotvrzuje odmítnutí. Server mohl dávku přijmout ještě před selháním spojení. Automatické opakování požadavku měnícího stav proto může práci zopakovat.

Pokud koncový bod podporuje zdokumentované idempotency keys, dodržujte jeho pravidla včetně rozsahu klíče a doby uchování. Nevymýšlejte vlastní hlavičku idempotence a nepředpokládejte, že ji server respektuje. Jinak použijte podporovaný pracovní postup vyhledání nebo sladění a před opětovným odesláním zjistěte, zda požadovaný stav existuje. Místní deduplikace pomáhá koordinovat vlastní pracovníky, ale nezaručuje idempotenci na straně serveru.

Praktický pracovní postup dávkového zpracování

Podrobnosti specifické pro poskytovatele uchovávejte v adaptéru, aby fronta, plánovač opakování a monitorovací logika nebyly závislé na názvech nezpracovaných polí odpovědi.

ověřit záznamy a uchovat místní identifikátory zásilek
vyřešit duplicity v zamýšleném obchodním rozsahu
rozdělit záznamy podle zdokumentovaných limitů položek a obsahu

pro každou dávku prostřednictvím omezené skupiny pracovníků:
    před odesláním uložit záznam o pokusu
    počkat na sdílený omezovač rychlosti
    odeslat pomocí adaptéru specifického pro poskytovatele

    pokud je výsledek nejistý:
        zařadit sladění do fronty
        pokračovat

    klasifikovat výsledky na úrovni požadavku a položky
    uložit jeden výsledek pro každý odeslaný záznam
    naplánovat k opakování pouze způsobilá selhání
    neplatné nebo vyčerpané záznamy předat ke kontrole

Ukládání výsledků a plánování opakování musí být obnovitelné. Například trvalý záznam úlohy nebo transakční vzor řazení do fronty může zabránit tomu, aby pád procesu způsobil ztrátu rozhodnutí o opakování. Po restartu by pracovníci měli rozlišit neodeslanou práci od práce, jejíž vzdálený výsledek je stále nejistý.

Velikost dávky nastavte jako konfigurovatelné nastavení navázané na příslušný koncový bod, nikoli jako konstantu rozptýlenou v celé kódové základně. Menší dávka může být užitečná při řešení problémů nebo izolaci chybných záznamů; největší povolená dávka není automaticky nejvhodnější provozní velikost.

Monitorujte výsledky zásilek, nejen dostupnost HTTP

API Monitoring by měl ukazovat, zda zásilky dosahují požadovaného stavu. Panel zobrazující pouze míru úspěšnosti HTTP může přehlédnout částečná selhání uvnitř jinak úspěšných odpovědí.

  • Míra přijetí položek: Přijaté záznamy dělené odeslanými záznamy s jasně definovaným zacházením s opakováními.
  • Rozložení selhání: Počty podle koncového bodu, zdokumentovaného kódu chyby a relevantního kontextu přepravce.
  • Neznámé výsledky: Nesladěné záznamy a doba, po kterou zůstaly nevyřešené.
  • Fronta opakování: Čekající opakování, stáří nejstaršího opakování a vyčerpané pokusy.
  • Stav požadavků: Latence, timeouty, omezení rychlosti a chyby serveru.
  • Aktuálnost sledování: Zda přijaté zásilky následně obdrží použitelné informace o sledování.

Přijetí registrace není důkazem nového skenu přepravce. Stav zpracování API uchovávejte odděleně od pohybu zásilky a aktuálnosti dat, aby nedošlo k záměně incidentu integrace se zpožděním doručení.

Protokolujte místní ID dávek, reference zásilek, počty pokusů, zdokumentované kódy chyb a ID požadavků poskytovatele, pokud jsou k dispozici. Redigujte přihlašovací údaje a nepotřebné osobní údaje. Identifikátory sledování používejte pouze tam, kde jsou provozně nezbytné, a nevkládejte nezpracované identifikátory zásilek do štítků metrik s vysokou kardinalitou.

Před nasazením do produkce otestujte tyto případy

Pokud je k dispozici, použijte zdokumentovaný sandbox nebo řízené testovací prostředí. Nepředpokládejte, že smyšlená sledovací čísla povedou k předvídatelným produkčním odpovědím.

  1. Odešlete platnou dávku na zdokumentovaném limitu položek a poté otestujte, jak klient zabrání nadměrně velké dávce.
  2. Ověřte, že sledovací čísla s počátečními nulami přežijí serializaci a uložení.
  3. Otestujte kombinaci přijatých a odmítnutých položek bez opakování úspěšných záznamů.
  4. Simulujte omezení rychlosti a potvrďte, že více pracovníků respektuje stejný limit.
  5. Simulujte timeout po odeslání a ověřte cestu sladění.
  6. Restartujte pracovníka mezi přijetím odpovědi a místním uložením.
  7. Otestujte chybějící, neznámé nebo nepřiřaditelné výsledky položek.
  8. Potvrďte, že neplatné záznamy dosáhnou viditelné fronty oprav místo nekonečného opakování.

Integrace připravená pro produkci dokáže vysvětlit stav každé odeslané zásilky včetně těch, jejichž výsledek je dočasně neznámý. Snížení počtu požadavků je užitečné; zachování této odpovědnosti je důležitějším návrhovým cílem.

Časté dotazy

Kolik sledovacích čísel mohu odeslat v jednom požadavku?

Použijte limit zdokumentovaný pro přesný koncový bod a verzi API. Ověřte také velikost požadavku, rychlostní limity a omezení specifická pro účet. Neexistuje bezpečné univerzální číslo použitelné napříč Tracking API ani napříč různými operacemi jednoho API.

Může jedno neplatné sledovací číslo způsobit selhání celé dávky?

Ano, záleží na pravidlech ověřování koncového bodu. Některá API vracejí individuální odmítnutí, zatímco jiná mohou požadavek odmítnout ještě před zpracováním položek. Kontrolujte chyby na úrovni požadavku i výsledky na úrovni položek; nepředpokládejte, že každý dávkový koncový bod podporuje částečné přijetí.

Mám opakovat dávku, když je HTTP odpověď úspěšná?

Ne automaticky. Nejprve analyzujte zdokumentovaný stav na aplikační úrovni a výsledky položek. Uložte úspěšné záznamy a opakujte pouze způsobilá selhání. Pokud výsledek nelze bezpečně interpretovat, označte jej jako nejistý a prošetřete.

Mohu v jedné dávce kombinovat různé přepravce?

Pouze pokud koncový bod tuto strukturu požadavku podporuje. Ověřte, zda se informace o přepravci zadává pro každou zásilku, zda je podporována automatická identifikace a co se stane při nejednoznačné identifikaci. Služba pro více přepravců sama o sobě nepotvrzuje pravidla dávkování každého koncového bodu.

Způsobí dávkové zpracování rychlejší doručování aktualizací sledování?

Dávkové zpracování může snížit počet požadavků odesílaných aplikací, ale samo o sobě nezpůsobí dřívější výskyt událostí přepravce. Registrace, načítání dat, dostupnost skenů přepravce a doručování aktualizací jsou samostatné části pracovního postupu.

Zdroje