Како да испратите повеќе броеви за следење во едно API-барање (ограничувања на серијата и делумни неуспеси)
За да испратите повеќе броеви за следење во едно API-барање, користете Tracking API крајна точка што експлицитно прифаќа пакетни барања, форматирајте ја секоја пратка според нејзината шема за барањето и поделете ги поголемите списоци на пакети во рамките на документираните ограничувања. Потоа проверете ги и HTTP-одговорот и резултатот за секоја пратка: успешно HTTP-барање не значи нужно дека секој број за следење е прифатен. Повторно испратете само неуспеси за кои е дозволено повторување и усогласете ги неизвесните исходи пред повторно да го испратите целиот пакет.

Овој водич е наменет за програмери кои го поврзуваат следењето на пратки со систем за управување со нарачки, платформа за магацин, апликација за е-трговија или интерна контролна табла. Целта не е само да се испраќаат помалку барања. Треба да се евидентира секоја пратка без создавање дупликатна работа или губење на неуспешните записи.
Најпрво утврдете што всушност прави крајната точка за пакетни барања
Интеграцијата за следење може да опфаќа неколку различни операции. Регистрирањето пратки, преземањето на нивните најнови информации за следење и примањето последователни ажурирања не се меѓусебно заменливи.
- Регистрација: Испратете пратки за услугата да може да започне или да го одржува нивното следење.
- Пребарување: Побарајте информации за следење на пратките, согласно правилата за преземање на крајната точка.
- Ажурирање на доставата: Примајте подоцнежни промени преку поддржан механизам, како веб-куки, или преземајте ги преку закажани барања.
Проверете ја документацијата за точната операција што ви е потребна. Крајна точка за регистрација што прифаќа повеќе записи не потврдува дека крајната точка за пребарување прифаќа ист број записи, ја користи истата шема или го има истото ограничување на брзината.
За интеграција со 17TRACK, започнете со страницата на производот Tracking API и користете ја официјалната API-документација за да ја потврдите операцијата, методот на автентикација, форматот на барањето и полињата во одговорот. Примерите подолу сметајте ги за имплементациски обрасци, а не за замена на договорот на API.
Ограничувањата на пакетите се повеќе од максимален број пратки
Не постои универзално ограничување на пакетите за Tracking API. Ограничувањата може да се разликуваат според давателот, крајната точка, верзијата на API и конфигурацијата на сметката. Пред да имплементирате пакетна обработка, забележете ги овие ограничувања одделно.
| Ограничување | Што да потврдите | Последица за имплементацијата |
|---|---|---|
| Ставки по барање | Максимален број записи за конкретната операција | Поделете го влезниот список пред испраќањето |
| Големина на телото на барањето | Секое документирано ограничување во бајти | Земете ги предвид изборните полиња и големината по серијализацијата |
| Брзина на барањата | Дозволен број барања во определен интервал | Распоредете ги барањата преку заеднички ограничувач |
| Истовременост | Секое ограничување за истовремени барања | Ограничете го бројот на активни работници |
| Евидентирање на користењето | Дали користењето се брои по барање, пратка или друга единица | Проценете ја потрошувачката одделно од бројот на барања |
На пример, ако хипотетичка крајна точка дозволува 25 записи по барање, 63 записи бараат три барања со 25, 25 и 13 записи. Овие бројки го илустрираат само делењето на пакети; тие не се наведени ограничувања на 17TRACK.
Не претпоставувајте дека пакетната обработка ја намалува наплатливата употреба. Таа може да го намали преоптоварувањето од HTTP-барањата, но влијанието врз трошоците зависи од фактичките правила за евидентирање на давателот. Исто така, валидна големина на пакет не дозволува неограничен број паралелни барања.
Подгответе ги записите пред да го составите барањето
Повеќето неочекувани неуспеси при пакетна обработка започнуваат со подготовката на влезот. Потврдете ја секоја пратка пред да ја додадете во пакет, но избегнувајте правила што може ненамерно да одбијат легитимни броеви за следење од различни превозници.
- Зачувајте ги броевите за следење како низи. Нивното претворање во броеви може да ги отстрани почетните нули или да ги измени долгите идентификатори.
- Отстранете го случајниот празен простор околу вредностите. Не отстранувајте внатрешни знаци и не менувајте ја големината на буквите освен ако соодветната спецификација го дозволува тоа нормализирање.
- Потврдете ги задолжителните полиња. Некои работни текови може да бараат идентификатор на превозникот или дополнителни информации за пратката. Користете само документирани имиња и вредности на полињата.
- Изберете јасен опфат за отстранување дупликати. Повторениот број за следење не е автоматски дупликат кај секој превозник, трговец или историска пратка.
- Чувајте локален идентификатор на пратката. Зачувајте ја врската меѓу испратената ставка и записот за нарачката или пратката, дури и кога API не прифаќа сопствени референтни полиња.
За Carrier Tracking низ повеќе мрежи, не заклучувајте го превозникот само врз основа на должината или префиксот на бројот за следење, освен ако тоа заклучување е сигурно за вашиот конкретен работен тек. Кога API поддржува идентификација на превозник, следете го документираното однесување при нејаснотии.
Илустративна структура на барањето
Следниот JSON го прикажува концептот на пакетно барање. Обвивката, имињата на својствата и идентификаторите се илустративни, а не шема на барање на 17TRACK. Некои API очекуваат низа на највисоко ниво наместо објект што содржи низа.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Составете го товарот преку JSON-серијализатор наместо со спојување низи. Испраќајте ги акредитивите за автентикација преку документираниот механизам и чувајте ги надвор од изворниот код, кодот доставен до прелистувачот и редовните дневници.
Обработете го одговорот на две нивоа
Пакетното барање има исход на транспортно ниво и исход на апликативно ниво. Вашата интеграција мора да ги процени двата.
Ниво 1: Дали барањето доби употреблив одговор?
Започнете со HTTP-статусот, заглавјата на одговорот и телото на одговорот. Грешките при автентикација, неисправните барања, ограничувањето на брзината и грешките на серверот може да спречат нормална обработка на ставките. Истекувањето на мрежното време е различно: клиентот можеби не знае дали серверот го примил или обработил барањето.
HTTP-семантиката е дефинирана во RFC 9110. Сепак, документацијата на давателот утврдува како полињата со резултат на апликативно ниво се поврзуваат со фактичките исходи на пратките.
Ниво 2: Што се случи со секоја пратка?
Ако одговорот поддржува резултати на ниво на ставка, класифицирајте го секој испратен запис. Не претпоставувајте дека HTTP 200 значи дека секој запис успеал или дека списокот со резултати го зачувува редоследот на барањето, освен ако договорот тоа изречно го гарантира.
- Прифатено: Операцијата успеала според документираната дефиниција на крајната точка.
- Траен неуспех на влезот: Поправете го или истражете го записот пред нов обид.
- Неуспех за повторување: Закажете нов обид според упатствата на давателот.
- Непознат исход: Одговорот недостасува, е нецелосен или не може безбедно да се поврзе со испратениот запис.
Чувајте ги одговорите како „веќе регистрирано“ или сличните одговори поврзани со дупликати одделно додека не го разберете нивното документирано значење. Тие може да покажуваат дека посакуваната состојба веќе постои, но не треба автоматски да се сметаат за потврда на успешна сопственост, конфигурација или претплата.
По обработката на одговорот, секој влезен запис треба да има точно еден локален исход. Корисна проверка за усогласување е: испратените записи се еднакви на прифатените записи плус трајните неуспеси плус неуспесите за повторување плус непознатите исходи. Ова е локално сметководствено правило, а не задолжителен формат на API-одговор.
Справувајте се со делумни неуспеси без повторно испраќање на успешните записи
Да претпоставиме дека илустративен пакет содржи десет пратки: седум се прифатени, две имаат невалидни задолжителни полиња, а една наидува на документирана привремена грешка. Зачувајте ги седумте успешни исходи, испратете ги двата невалидни записи на исправка и повторете го обидот само за привремено неуспешната пратка.
Повторното испраќање на сите десет записи создава непотребен сообраќај и може да го усложни справувањето со дупликати. Исто така, потешко е да се разликува првичното одбивање од подоцнежниот одговор поврзан со дупликат.
| Исход | Препорачано дејство |
|---|---|
| Невалидно поле или неподдржана вредност | Поправете го влезот; не повторувајте го обидот без промени |
| Неуспех при автентикација или дозволи | Паузирајте ја засегнатата работа и поправете ги акредитивите или пристапот |
| Одговор за ограничување на брзината | Одложете според документираните упатства и важечките заглавја на одговорот |
| Привремена грешка на ниво на ставка | Повторете ја ставката со ограничен број обиди и постепено одложување |
| Истекување на времето по испраќањето | Означете ја како неизвесна; усогласете ја или користете документирани гаранции за безбедно повторување |
| Непрепознат или нецелосен резултат | Зачувајте ги доказите и истражете наместо да претпоставите успех |
HTTP 429 означува премногу барања, а одговорот може да содржи заглавје Retry-After, како што е опишано во RFC 6585. Не претпоставувајте дека тоа заглавје секогаш постои. Кога не е дадено изречно одложување за повторување, користете ограничена политика на постепено одложување во согласност со документацијата на API.
Додајте случајно одложување за да ги распределите повторните обиди од повеќе работници, поставете максимален број обиди или максимална старост на повторувањето и испратете ги исцрпените записи во редица за проверка. Неограниченото повторување може да сокрие траен проблем со конфигурацијата.
Зошто истекувањата на времето бараат посебен третман
Истекувањето на времето не докажува дека барањето е одбиено. Серверот можеби го прифатил пакетот пред да прекине врската. Затоа автоматското повторно испраќање на барање што ја менува состојбата може да ја повтори работата.
Ако крајната точка поддржува документирани клучеви за идемпотентност, следете ги нејзините правила, вклучувајќи го опфатот и периодот на задржување на клучот. Не измислувајте заглавје за идемпотентност и не претпоставувајте дека серверот ќе го почитува. Во спротивно, користете поддржан работен тек за пребарување или усогласување за да утврдите дали посакуваната состојба постои пред повторно испраќање. Локалното отстранување дупликати помага при координација на вашите работници, но не гарантира идемпотентност на страната на серверот.
Практичен работен тек за обработка на пакети
Чувајте ги деталите специфични за давателот во адаптер, така што редицата, распоредувачот за повторни обиди и логиката за следење нема да зависат од необработените имиња на полињата во одговорот.
потврдете ги записите и зачувајте ги локалните идентификатори на пратките
разрешете ги дупликатите во предвидениот деловен опфат
поделете ги записите користејќи ги документираните ограничувања за ставки и товар
за секој пакет преку ограничен фонд работници:
зачувајте запис за обидот пред испраќањето
почекајте го заедничкиот ограничувач на брзината
испратете преку адаптер специфичен за давателот
ако исходот е неизвесен:
ставете го во редица за усогласување
продолжете
класифицирајте ги исходите на ниво на барање и ставка
зачувајте еден исход за секој испратен запис
закажете повторување само за подобните неуспеси
испратете ги невалидните или исцрпените записи на проверка
Направете го зачувувањето на исходите и закажувањето на повторните обиди отпорни на падови. На пример, траен запис за задача или трансакциски образец за ставање во редица може да спречи падот на процесот да ја изгуби одлуката за повторување. Кога работниците ќе се рестартираат, треба да можат да ја разликуваат непратената работа од работата чиј оддалечен исход сè уште е неизвесен.
Користете ја големината на пакетот како конфигурабилна поставка поврзана со соодветната крајна точка, а не како константа расфрлана низ кодната база. Помал пакет може да биде корисен при отстранување грешки или изолирање проблематични записи; најголемиот дозволен пакет не е автоматски најдобрата оперативна големина.
Следете ги исходите на пратките, а не само достапноста на HTTP
API Monitoring треба да покаже дали пратките ја достигнуваат посакуваната состојба. Контролна табла што ги прикажува само стапките на успешност на HTTP може да ги пропушти делумните неуспеси во инаку успешните одговори.
- Стапка на прифаќање на ставки: Прифатени записи поделени со испратени записи, со јасно дефиниран третман на повторните обиди.
- Распределба на неуспеси: Броеви по крајна точка, документиран код на грешка и релевантен контекст на превозникот.
- Непознати исходи: Неусогласени записи и времето колку што останале нерешени.
- Заостанати повторни обиди: Предложени повторувања, старост на најстарото повторување и исцрпени обиди.
- Состојба на барањата: Доцнење, истекувања на времето, ограничување на брзината и серверски грешки.
- Актуелност на следењето: Дали прифатените пратки подоцна добиваат употребливи информации за следење.
Прифаќањето на регистрацијата не е доказ за ново скенирање од превозникот. Чувајте го статусот на обработката на API одделно од движењето на пратката и актуелноста на податоците, за инцидентот во интеграцијата да не се помеша со доцнење во доставата.
Евидентирајте ги локалните идентификатори на пакетите, референците на пратките, бројот на обиди, документираните кодови на грешки и идентификаторите на барањата на давателот кога се достапни. Маскирајте ги акредитивите и непотребните лични информации. Користете идентификатори за следење само кога се оперативно неопходни и избегнувајте да ставате необработени идентификатори на пратки во ознаки на метрики со висока кардиналност.
Тестирајте ги овие случаи пред продукција
Користете документирана песочна околина или контролирана тест-околина кога е достапна. Не претпоставувајте дека измислените броеви за следење ќе дадат предвидливи продукциски одговори.
- Испратете валиден пакет со документираниот максимален број ставки, а потоа тестирајте како клиентот спречува преголем пакет.
- Проверете дали броевите за следење со почетни нули преживуваат при серијализација и складирање.
- Тестирајте мешани прифатени и одбиени ставки без повторно испраќање на успешните записи.
- Симулирајте ограничување на брзината и потврдете дека повеќе работници го почитуваат истото ограничување.
- Симулирајте истекување на времето по испраќањето и проверете ја патеката за усогласување.
- Рестартирајте работник помеѓу приемот на одговорот и локалното зачувување.
- Тестирајте ставки со резултати што недостасуваат, се непознати или не можат да се поврзат.
- Потврдете дека невалидните записи стигнуваат до видлива редица за исправка наместо бесконечно да се повторуваат.
Интеграцијата подготвена за продукција може да ја објасни состојбата на секоја испратена пратка, вклучувајќи ги и оние чиј исход моментално е непознат. Намалувањето на бројот на барања е корисно; зачувувањето на таа одговорност е поважната дизајнерска цел.
ЧПП
Колку броеви за следење можам да испратам во едно барање?
Користете го ограничувањето документирано за точната крајна точка и верзијата на API. Проверете ги и големината на барањето, ограничувањата на брзината и сите ограничувања специфични за сметката. Не постои безбеден универзален број што може да се примени на сите API за следење или на различни операции во едно API.
Може ли еден невалиден број за следење да предизвика неуспех на целиот пакет?
Да, зависно од правилата за проверка на крајната точка. Некои API враќаат поединечни одбивања, додека други може да го одбијат барањето пред обработката на ставките. Проверете ги и грешките на ниво на барање и резултатите на ниво на ставка; не претпоставувајте дека секоја крајна точка за пакетни барања поддржува делумно прифаќање.
Дали треба повторно да испратам пакет кога HTTP-одговорот е успешен?
Не автоматски. Прво анализирајте го документираниот статус на апликативно ниво и резултатите за ставките. Зачувајте ги успешните записи и повторете го обидот само за подобните неуспеси. Ако резултатот не може безбедно да се протолкува, класифицирајте го како неизвесен и истражете.
Може ли да мешам превозници во истиот пакет?
Само кога крајната точка ја поддржува таа структура на барањето. Потврдете дали информациите за превозникот се испраќаат по пратка, дали е поддржана автоматска идентификација и што се случува кога идентификацијата е нејасна. Услугата со повеќе превозници сама по себе не ги утврдува правилата за пакетна обработка на секоја крајна точка.
Дали пакетната обработка прави ажурирањата на следењето да пристигнуваат побрзо?
Пакетната обработка може да го намали бројот на барања што ги испраќа вашата апликација, но сама по себе не значи дека настаните од превозникот ќе се појават порано. Регистрацијата, преземањето податоци, достапноста на скенирањата од превозникот и испораката на ажурирањата се одделни делови од работниот тек.
Извори
- 17TRACK Tracking API — официјална почетна точка на производот за програмери кои проценуваат интеграција за следење.
- 17TRACK API документација — референца за договорот на крајната точка специфичен за давателот, ограничувањата, автентикацијата и обработката на одговорите.
- RFC 9110: HTTP Semantics — семантика на HTTP-статусите, идемпотентност, автоматски повторни обиди и Retry-After.
- RFC 6585: Additional HTTP Status Codes — дефиниција на HTTP 429 Too Many Requests и неговото изборно заглавје Retry-After.


