Skip to main content
Басты бетБлогНұсқаулықтарБір API сұрауында бірнеше қадағалау нөмірін қалай жіберуге болады (пакет шектеулері және ішінара сәтсіздіктер)

Бір API сұрауында бірнеше қадағалау нөмірін қалай жіберуге болады (пакет шектеулері және ішінара сәтсіздіктер)

17TRACK

Бір API сұрауында бірнеше бақылау нөмірін жіберу үшін пакеттік өңдеуді нақты қолдайтын Tracking API соңғы нүктесін пайдаланыңыз, әр жөнелтімді оның сұрау схемасына сәйкес пішімдеңіз және үлкен тізімдерді құжаттамада көрсетілген шектерге сай пакеттерге бөліңіз. Содан кейін HTTP жауабын да, әр жөнелтімнің нәтижесін де тексеріңіз: HTTP сұрауының сәтті орындалуы барлық бақылау нөмірлерінің қабылданғанын білдірмейді. Тек қайта жіберуге жарамды сәтсіздіктерді қайталап орындаңыз және бүкіл пакетті қайта жібермес бұрын белгісіз нәтижелерді салыстырып тексеріңіз.

Бір API сұрауында бірнеше бақылау нөмірін қалай жіберуге болады

Бұл нұсқаулық жөнелтімдерді бақылауды тапсырыстарды басқару жүйесіне, қойма платформасына, электрондық коммерция қолданбасына немесе ішкі бақылау тақтасына қосатын әзірлеушілерге арналған. Мақсат — тек сұраулар санын азайту емес. Негізгі міндет — қайталанатын жұмысты жасамай және сәтсіз жазбаларды жоғалтпай, әрбір жөнелтімді есепке алу.

Алдымен пакеттік соңғы нүктенің нақты не істейтінін анықтаңыз

Жөнелтімдерді бақылау интеграциясы бірнеше бөлек әрекетті қамтуы мүмкін. Жөнелтімдерді тіркеу, олардың соңғы бақылау ақпаратын алу және кейінгі жаңартуларды қабылдау — бір-бірін алмастыратын әрекеттер емес.

  • Тіркеу: Қызмет оларды бақылауды бастай немесе жалғастыра алуы үшін жөнелтімдерді жіберу.
  • Іздеу: Соңғы нүктенің алу ережелеріне сәйкес жөнелтімдер туралы бақылау ақпаратын сұрау.
  • Жеткізуді жаңарту: Вебхуктар сияқты қолдау көрсетілетін механизм арқылы кейінгі өзгерістерді алу немесе оларды жоспарланған сұраулар арқылы алу.

Қажетті нақты операцияны құжаттамадан тексеріңіз. Бірнеше жазбаны қабылдайтын тіркеу соңғы нүктесі іздеу соңғы нүктесі дәл сондай санды қабылдайтынын, бірдей схеманы пайдаланатынын немесе бірдей сұрау жиілігі шегіне ие екенін білдірмейді.

17TRACK интеграциясы үшін Tracking API өнім бетінен бастаңыз және операцияны, аутентификация әдісін, сұрау пішімін және жауап өрістерін растау үшін ресми API құжаттамасын пайдаланыңыз. Төмендегі мысалдарды осы API келісімшартының орнына емес, іске асыру үлгілері ретінде қарастырыңыз.

Пакет шектері жөнелтімдердің ең көп санымен ғана шектелмейді

Tracking API үшін әмбебап пакет шегі жоқ. Шектер провайдерге, соңғы нүктеге, API нұсқасына және тіркелгі конфигурациясына қарай өзгеруі мүмкін. Пакеттік өңдеуді енгізбес бұрын осы шектеулерді бөлек тіркеңіз.

ШектеуНені растау керекІске асыру салдары
Бір сұраудағы элементтерНақты операция үшін жазбалардың ең көп саныЖібермес бұрын кіріс тізімін бөлу
Сұрау денесінің өлшеміҚұжатталған байт шегі бар-жоғыҚосымша өрістер мен сериализация өлшемін ескеру
Сұрау жиілігіБелгілі бір аралықта рұқсат етілетін сұраулар саныСұрауларды ортақ шектеуіш арқылы реттеу
ПараллельдікБір мезгілдегі сұрауларға қойылатын шектеулерБелсенді жұмысшылар санын шектеу
Пайдалануды есепке алуПайдалану сұрау, жөнелтім немесе басқа бірлік бойынша есептеле меТұтынуды сұраулар көлемінен бөлек есептеу

Мысалы, гипотетикалық соңғы нүкте бір сұрауға 25 жазбаға рұқсат етсе, 63 жазба үшін 25, 25 және 13 жазбадан тұратын үш сұрау қажет. Бұл сандар тек бөліктерге бөлуді көрсету үшін берілген; олар 17TRACK шектері ретінде көрсетілмеген.

Пакеттеу ақылы пайдалануды азайтады деп болжамаңыз. Ол HTTP сұрауларына кететін қосымша шығынды азайтуы мүмкін, бірақ төлемге әсері провайдердің нақты есептеу ережелеріне байланысты. Сол сияқты, жарамды пакет өлшемі шексіз параллель сұрауларға рұқсат бермейді.

Сұрауды құрастырмас бұрын жазбаларды дайындаңыз

Болдырмауға болатын пакеттік сәтсіздіктердің көбі кірісті дайындаудан басталады. Әр жөнелтімді пакетке қоспас бұрын тексеріңіз, бірақ әртүрлі тасымалдаушылардың жарамды бақылау нөмірлерін байқаусызда қабылдамайтын ережелерден аулақ болыңыз.

  1. Бақылау нөмірлерін жол ретінде сақтаңыз. Оларды сандарға түрлендіру бастапқы нөлдерді жоюы немесе ұзын идентификаторларды өзгертуі мүмкін.
  2. Айналасындағы кездейсоқ бос орындарды жойыңыз. Тиісті спецификация мұндай қалыпқа келтіруге рұқсат бермесе, ішкі таңбаларды жоймаңыз және регистрді өзгертпеңіз.
  3. Міндетті өрістерді тексеріңіз. Кейбір жұмыс процестеріне тасымалдаушы идентификаторы немесе қосымша жөнелтілім ақпараты қажет болуы мүмкін. Тек құжатталған өріс атаулары мен мәндерін пайдаланыңыз.
  4. Дубликаттарды жою ауқымын нақты таңдаңыз. Қайталанған бақылау нөмірі әр тасымалдаушы, сатушы немесе тарихи жөнелтім бойынша автоматты түрде дубликат болып саналмайды.
  5. Жергілікті жөнелтім идентификаторын сақтаңыз. 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 тым көп сұрауды білдіреді және оның жауабында RFC 6585 сипаттаған Retry-After тақырыбы болуы мүмкін. Бұл тақырып әрқашан болады деп болжамаңыз. Нақты қайта әрекет кідірісі берілмесе, API құжаттамасына сәйкес шектелген кідіріс саясатын қолданыңыз.

Бірнеше жұмысшының қайталауларын тарату үшін кездейсоқ кідіріс қосыңыз, әрекеттердің ең көп санын немесе қайталау жасын белгілеңіз және әрекеті таусылған жазбаларды тексеру кезегіне жіберіңіз. Шексіз қайталау тұрақты конфигурация мәселесін жасыруы мүмкін.

Неліктен тайм-ауттарға ерекше қарау керек

Тайм-аут қабылданбағанын дәлелдемейді. Байланыс үзілгенге дейін сервер пакетті қабылдаған болуы мүмкін. Сондықтан күйді өзгертетін сұрауды автоматты түрде қайта ойнату жұмысты қайталауы мүмкін.

Егер соңғы нүкте құжатталған идемпотенттілік кілттерін қолдаса, кілт ауқымы мен сақталу мерзімін қоса, оның ережелерін орындаңыз. Идемпотенттілік тақырыбын өзіңіз ойлап тауып, сервер оны қабылдайды деп болжамаңыз. Әйтпесе қайта жібермес бұрын қажетті күйдің бар-жоғын анықтау үшін қолдау көрсетілетін іздеу немесе салыстырып тексеру жұмыс процесін пайдаланыңыз. Жергілікті дубликаттарды жою өз жұмысшыларыңызды үйлестіруге көмектеседі, бірақ сервер жағындағы идемпотенттілікке кепілдік бермейді.

Пакеттерді өңдеудің практикалық жұмыс процесі

Провайдерге тән мәліметтерді адаптерде сақтаңыз, сонда кезек, қайта әрекет жоспарлаушысы және мониторинг логикасы жауаптың бастапқы өріс атауларына тәуелді болмайды.

жазбаларды тексеріп, жергілікті жөнелтім идентификаторларын сақтаңыз
duplicatтарды жоспарланған бизнес ауқымында шешіңіз
жазбаларды құжатталған элемент және жүктеме шектерін пайдаланып бөліңіз

шектелген жұмысшылар пулы арқылы әр пакет үшін:
    жібермес бұрын әрекет жазбасын сақтаңыз
    ортақ сұрау жиілігін шектеуішін күтіңіз
    провайдерге тән адаптер арқылы жіберіңіз

    егер нәтиже белгісіз болса:
        салыстырып тексеру кезегіне қосыңыз
        жалғастырыңыз

    сұрау деңгейіндегі және элемент деңгейіндегі нәтижелерді жіктеңіз
    жіберілген әр жазба үшін бір нәтиже сақтаңыз
    тек жарамды сәтсіздіктерді қайталауға жоспарлаңыз
    жарамсыз немесе әрекеті таусылған жазбаларды тексеруге жіберіңіз

Нәтижелерді сақтауды және қайта әрекет жоспарлауды қалпына келтірілетін етіңіз. Мысалы, тұрақты тапсырма жазбасы немесе транзакциялық кезекке қою үлгісі процесс істен шыққанда қайта әрекет туралы шешімнің жоғалуына жол бермейді. Жұмысшылар қайта іске қосылғанда, олар жіберілмеген жұмысты қашықтағы нәтижесі әлі белгісіз жұмыстан ажырата алуы керек.

Пакет өлшемін код базасына шашыраған тұрақты мән емес, тиісті соңғы нүктеге байланысты конфигурацияланатын параметр ретінде пайдаланыңыз. Мәселелерді тексеру немесе проблемалы жазбаларды оқшаулау кезінде кішірек пакет пайдалы болуы мүмкін; рұқсат етілген ең үлкен пакет автоматты түрде ең жақсы жұмыс өлшемі болмайды.

Тек HTTP жұмыс уақытын емес, жөнелтім нәтижелерін бақылаңыз

API Monitoring жөнелтімдердің көзделген күйге жетіп жатқанын көрсетуі керек. Тек HTTP сәттілік көрсеткіштерін көрсететін бақылау тақтасы сәтті көрінетін жауаптардың ішіндегі ішінара сәтсіздіктерді байқамай қалуы мүмкін.

  • Элементтерді қабылдау көрсеткіші: Қайталауларды өңдеу тәртібі нақты анықталған жағдайда қабылданған жазбалардың жіберілген жазбаларға қатынасы.
  • Сәтсіздіктердің бөлінуі: Соңғы нүкте, құжатталған қате коды және тиісті тасымалдаушы контексті бойынша санақ.
  • Белгісіз нәтижелер: Салыстырып тексерілмеген жазбалар және олардың қанша уақыт шешілмей тұрғаны.
  • Қайталау кезегі: Күтудегі қайталаулар, ең ескі қайталаудың жасы және таусылған әрекеттер.
  • Сұрау күйі: Кідіріс, тайм-ауттар, сұрау жиілігін шектеу және сервер қателері.
  • Бақылау деректерінің жаңалығы: Қабылданған жөнелтімдер кейін пайдалануға жарамды бақылау ақпаратын ала ма.

Тіркеудің қабылдануы жаңа тасымалдаушы сканының дәлелі емес. API өңдеу күйін жөнелтім қозғалысы мен деректердің жаңалығынан бөлек сақтаңыз, сонда интеграция оқиғасы жеткізу кідірісімен шатастырылмайды.

Жергілікті пакет идентификаторларын, жөнелтім сілтемелерін, әрекет санын, құжатталған қате кодтарын және қолжетімді болса провайдердің сұрау идентификаторларын журналға жазыңыз. Тіркелгі деректері мен қажетсіз жеке ақпаратты жасырыңыз. Бақылау идентификаторларын тек операциялық тұрғыдан қажет жерде пайдаланыңыз және бастапқы жөнелтім идентификаторларын жоғары кардиналдылықтағы метрика белгілеріне орналастырмаңыз.

Өндіріске дейін осы жағдайларды тексеріңіз

Қолжетімді болса, құжатталған sandbox немесе бақыланатын тест ортасын пайдаланыңыз. Ойдан шығарылған бақылау нөмірлері өндірісте болжамды жауап береді деп есептемеңіз.

  1. Құжатталған элемент шегінде жарамды пакетті жіберіңіз, содан кейін клиентіңіздің шектен асатын пакетті қалай болдырмайтынын тексеріңіз.
  2. Бастапқы нөлдері бар бақылау нөмірлерінің сериализация мен сақтаудан кейін сақталатынын тексеріңіз.
  3. Қабылданған және қабылданбаған элементтер аралас жағдайды сәтті жазбаларды қайталамай тексеріңіз.
  4. Сұрау жиілігін шектеуді модельдеп, бірнеше жұмысшының бірдей шекті сақтайтынын растаңыз.
  5. Жібергеннен кейінгі тайм-аутты модельдеп, салыстырып тексеру жолын тексеріңіз.
  6. Жауап алынғаннан және жергілікті сақталғаннан кейін жұмысшыны қайта іске қосыңыз.
  7. Жоқ, таныс емес немесе сәйкестендірілмейтін элемент нәтижелерін тексеріңіз.
  8. Жарамсыз жазбалардың шексіз қайталанудың орнына көрінетін түзету кезегіне түсетінін растаңыз.

Өндіріске дайын интеграция нәтижесі уақытша белгісіз болған жөнелтімдерді қоса алғанда, жіберілген әр жөнелтімнің күйін түсіндіре алады. Сұраулар санын азайту пайдалы, бірақ осы есептілікті сақтау — маңыздырақ жобалау мақсаты.

Жиі қойылатын сұрақтар

Бір сұрауда қанша бақылау нөмірін жібере аламын?

Нақты соңғы нүкте мен 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 тақырыбы.