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

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

Tracking деректерін тапсырыстарды басқару жүйесіне, қойма платформасына немесе клиенттерге арналған tracking бетіне қосатын әзірлеушілер үшін мақсат тек сәтсіз сұраулар санын азайту емес. Мақсат — қайталанатын тіркеулерсіз, қайта сұраулар дауылынсыз, жаңылыстыратын жеткізу хабарламаларынсыз немесе қажетсіз қолдау сұрауларынсыз жөнелтілімдердің күйін сенімді түрде көрсету.

Жауапты таңдамас бұрын ақауды жіктеңіз

Tracking интеграциясында бағалануы тиіс бірнеше бөлек нәтиже бар: желілік сұраудың аяқталған-аяқталмағаны, API операцияны қабылдаған-қабылдамағаны, сұралған әрбір tracking элементінің сәтті болған-болмағаны және жөнелтілім оқиғаларының қолжетімділігі. Осы төрт жағдайдың барлығын бір ғана сәттілік немесе сәтсіздік жалаушасы ретінде қарастыру болдырмауға болатын қателерге әкеледі.

HTTP арқылы алынған сәтті жауап топтамадағы әрбір элементтің сәтті болғанын білдірмейді. Керісінше, tracking оқиғалары жоқ сәтті өңделген іздеу міндетті түрде API қатесі емес. Жауап денесін тексеріп, әр нәтиже үшін провайдер құжаттамасында көрсетілген мағынаны қолданыңыз.

Жағдай	Ұсынылатын әрекет	Өзгеріссіз қайта сұрау керек пе?
Қате пішімделген нөмір немесе жарамсыз сұрау өрісі	Енгізу деректерін тексеріп, түзету	Жоқ
Тіркелгі деректері жоқ немесе жарамсыз	Тіркелгі деректерін, рұқсаттарды және ортаны тексеру	Түзетілгенге дейін емес
Сұрау жиілігі шегіне жету жауабы	Әсер еткен жұмысты кідіртіп, ортақ сұрау қысымын азайту	Қажетті күту уақытынан кейін, қауіпсіз болса
Уақытша сервис ақауы	Шектелген кідірісті қолданып, операция қауіпсіздігін тексеру	Әдетте, қайта сұрау бюджеті шегінде
Тіркеуді жібергеннен кейінгі тайм-аут	Тіркеудің бар-жоғын салыстырып тексеру	Соқыр түрде емес
Қабылданған іздеу, бірақ жөнелтілім оқиғалары жоқ	Құжатталған tracking өмірлік цикліне сәйкес әрекет ету	Жылдам қайта сұраулардың орнына жоспарланған жаңартуды пайдалану

HTTP күй кодтары бастапқы нүкте береді, бірақ нақты провайдерге тән толық шешімдер ағашын көрсетпейді. RFC 9110 HTTP семантикасын анықтайды, ал RFC 6585 429 Too Many Requests кодын анықтайды. Интеграцияңыз құжатталған қолданбалық қате кодтары мен элемент деңгейіндегі нәтижелерді де түсіндіруі керек.

Жарамсыз tracking нөмірлері: қате енгізу деректерін оқиғалардың жоқтығынан ажыратыңыз

«Жарамсыз tracking нөмірі» әртүрлі мәселелерді білдіруі мүмкін: қате пішімделген идентификатор, қолдау көрсетілмейтін тасымалдаушы мен нөмір үйлесімі, міндетті тасымалдаушы өрісінің болмауы немесе провайдерге тән басқа тексеру қатесі. Tracking оқиғалары қайтарылмағандықтан ғана нөмірді жарамсыз деп есептемеңіз.

Идентификаторға зиян келтірмей тексеріңіз

• Tracking нөмірлерін жол ретінде сақтаңыз. Сандық сақтау бастапқы нөлдерді жоюы немесе ұзын идентификаторларды өзгертуі мүмкін.
• Бастапқы енгізу деректерін сақтаңыз. Өзгерістерді бақылауға болатындай етіп бөлек қалыпқа келтірілген мәнді ұстаңыз.
• Қалыпқа келтіруді абайлап орындаңыз. Қажет болған жағдайда шеткі бос орындарды жойыңыз, бірақ құжатталған ережелер рұқсат етпесе, ішкі таңбаларды жоймаңыз және әріп регистрін өзгертпеңіз.
• Міндетті өрістерді жергілікті жерде тексеріңіз. Бос нөмірлерді, тасымалдаушы идентификаторларының жоқтығын және жарамсыз сұрау пішімдерін жібермес бұрын анықтаңыз.
• Әмбебап tracking нөмірі тұрақты өрнегін пайдаланбаңыз. Бір тасымалдаушыға арналған ереже басқа тасымалдаушының жарамды идентификаторларын қабылдамауы мүмкін.
• Өрісте нақты не бар екенін растаңыз. Endpoint оларды нақты қолдамаса, тапсырыс нөмірі, қойма анықтамасы және тасымалдаушының tracking нөмірі бір-бірін алмастырмайды.

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

«Оқиғалар жоқ» күйін бөлек өңдеңіз

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

input_rejected, awaiting_events және temporarily_unavailable сияқты бөлек ішкі күйлерді пайдаланыңыз. Бұл ұсынылған қолданба күйлері, стандартталған API мәндері емес. Олар уақытша деректер алшақтығының клиентке дәл емес хабарламаға айналуына жол бермейді.

Сұрау жиілігі шектеулерін әрбір worker үшін емес, бүкіл интеграция деңгейінде басқарыңыз

RFC 6585 HTTP 429 кодын сұрау жиілігін шектеу жауабы ретінде анықтайды және оның құрамында Retry-After тақырыбы болуы мүмкін екенін көрсетеді. Стандарт tracking API үшін әмбебап рұқсат көлемін немесе есептеу әдісін белгілемейді. Шектеулер тіркелгі, тіркелгі деректері, endpoint немесе басқа ауқым бойынша құжатталуы мүмкін; провайдердің нақты ережелерін пайдаланыңыз.

RFC 9110 Retry-After үшін екі пішімді көрсетеді: теріс емес секундтар саны немесе HTTP күні. Екеуін де талдаңыз. Егер мән күн болса, қалған күту уақытын мұқият есептеп, сағат айырмашылықтарын ескеріңіз. Мән жоқ немесе жарамсыз болса, конфигурацияланған резервтік кідіріс саясатын қолданыңыз.

Басқа worker-лер сол рұқсатты пайдалануды жалғастырған кезде бір worker-дің өздігінен ұйықтауы жеткіліксіз. Сұрау жиілігін тиісті тіркелгі деректері немесе тіркелгі үшін ортақ шекарада басқарыңыз. Орталық жоспарлаушы, ортақ token bucket немесе балама үлестірілген басқару мұндай трафикті үйлестіре алады.

1. Әсер еткен ауқымды анықтаңыз. Шектеудің қай endpoint-ке, тіркелгі деректеріне немесе тіркелгіге қатысты екенін анықтаңыз.
2. Сервердің күту нұсқауын сақтаңыз. Жарамды Retry-After мәні рұқсат ететін уақыттан ерте қайта сұрауды жоспарламаңыз.
3. Кезектегі әсер еткен жұмысты кідіртіңіз. Шектеулер шынымен тәуелсіз болғанда, қатысы жоқ трафикті бұғаттамаңыз.
4. Параллелизмді немесе сұрау жиілігін азайтыңыз. Сұрау үлгісін өзгертпей бір рет күту сол мәселені қайта тудыруы мүмкін.
5. Аралық сақтай отырып жалғастырыңыз. Күту аяқталғанда бүкіл кезекті бір уақытта босатпаңыз.

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

Кідіріс пен кездейсоқ ауытқуды пайдаланып, шектелген қайта сұрауларды қолданыңыз

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

Практикалық резервтік тәсіл — шектелген экспоненциалды кідіріс пен толық кездейсоқ ауытқу:

backoff_window = min(max_delay, base_delay * 2^retry_index)
jitter_delay = random(0, backoff_window)
next_delay = max(valid_retry_after_delay, jitter_delay)

Мұнда retry_index бірінші қайта сұрау үшін нөлден басталады, ал жоқ Retry-After қосымша ең аз күту уақытын қоспайды. Бұл міндетті HTTP алгоритмі емес, іске асыру шешімдері. Жұмыс жүктемеңізге және провайдердің нұсқауларына сәйкес бастапқы кідірісті, шекті, әрекет санын және жалпы соңғы мерзімді таңдаңыз.

Кездейсоқ ауытқу барлық worker-дің бір кесте бойынша қайталауының орнына сұрауларды уақыт аралығына таратады. Кідіріс шегі экспоненциалды құрамдасты шектейді; ол сервер сұраған жарамды, ұзағырақ күту уақытын алмастырмауы керек. Егер бұл күту уақыты job соңғы мерзімінен асып кетсе, ерте қайта сұраудың орнына саясатқа сәйкес job-ты кейінге қалдырыңыз немесе тоқтатыңыз.

Әрбір қайта сұрау тізбегіне аяқталу шегін беріңіз

• Әрекет санының шегі: қосымша сұраулар санын шектеңіз.
• Өткен уақыт шегі: пайдалы өңдеу терезесінен асып кеткен жұмысты қайта сұрауды тоқтатыңыз.
• Нақты жауапкершілік: қайта сұрауларды қай қабат басқаратынын таңдаңыз, сонда HTTP-клиент қайта сұраулары мен кезек қайта сұраулары күтпеген жерден көбеймейді.
• Тұрақты жоспарлау: қысқа өмір сүретін процестер ішінде ұзақ ұйқыға сенудің орнына, кідіртілген job-тарды сақтаңыз.
• Қалпына келтіру жолы: әрекеттері мен себебі көрсетілген, тексеруге болатын сәтсіз job кезегіне шегі асқан job-тарды жіберіңіз.

Ұзаққа созылған ақау кезінде күнделікті шақыруларды уақытша тоқтатып, бақыланатын қалпына келтіру тексерулеріне рұқсат беретін circuit breaker механизмін қарастырыңыз. Бұл қолданбаның тұрақтылығын арттыру үлгісі, нақты tracking провайдері оны міндетті түрде талап етеді деген дәлел емес.

Қайта жібермес бұрын белгісіз жазу операцияларын шешіңіз

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

RFC 9110 идемпотентті әдістерді түсіндіреді және бастапқы операцияның қолданылмағанын немесе қайталау қауіпсіз екенін білуге негіз болмайынша, идемпотентті емес сұрауларды автоматты түрде қайталаудан сақтандырады. Әрбір tracking endpoint тек оқуға арналған іздеу сияқты әрекет етеді деп болжамай, құжатталған операция семантикасын бағалаңыз.

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

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

Саясатты tracking провайдеріңізге қолданыңыз

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

Іске асыру алдында тиісті endpoint сұрау схемасын, жауап конвертін, элемент деңгейіндегі қате мағыналарын, сұрау жиілігі шегінің ауқымын, топтама шектеулерін және қайталанатын жіберілімдер ережелерін растаңыз. Оқиғаларды жеткізуді пайдалансаңыз, растау, аутентификация және қайта жеткізу талаптарын да тексеріңіз. Бұл нұсқаулық 17TRACK үшін сандық сұрау жиілігі шегін, қайта сұрау кестесін немесе идемпотенттілік мүмкіндігін белгілемейді.

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

Қалпына келтіру сапасын бақылаңыз және ақау жолдарын тексеріңіз

Операцияны, endpoint-ті, HTTP күйін, қолданбалық қате кодын, әрекет нөмірін, кідірісті, келесі жоспарланған әрекетті және берілген жағдайда провайдердің сұрау идентификаторын журналға жазыңыз. API кілттерін, қажетсіз мекенжай ақпаратын немесе шектелмеген жауап денелерін жазудан аулақ болыңыз. Толық мәндер қажет емес жерде tracking идентификаторларын бүркемелеңіз немесе хэштеп сақтаңыз.

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

Релиз алдында қате пішімделген енгізу деректерін, оқиғалары жоқ жарамды идентификаторларды, Retry-After тақырыбының екі пішімін, жоқ тақырыптарды, топтаманың ішінара сәтсіздіктерін, жазудан кейінгі тайм-ауттарды және кезектің қайта жеткізілуін тексеріңіз. Сондай-ақ қайта сұрау бюджетін тауыстыратындай ұзақ ақауды модельдеңіз. Жұмыс болжамды түрде тоқтағанда немесе кейінге қалдырылғанда, сәтті элементтер қажетсіз қайта ойнатылмағанда және сәтсіз элементтер қалпына келтірілетін күйде қалғанда ғана тест сәтті өтті деп есептеледі.

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

Жарамсыз tracking нөмірін автоматты түрде қайта сұрау керек пе?

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

HTTP 200 топтамалық сұраудың толық сәтті болғанын білдіре ме?

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

Tracking интеграциясы қанша қайта сұрау әрекетіне рұқсат беруі керек?

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

Тайм-аут жөнелтілімді бірден сәтсіз деп белгілеуі керек пе?

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

Қайта сұраулар таусылғанда не болуы керек?

Job-ты диагностикалық мәнмәтінімен бірге тұрақты сәтсіз job немесе тексеру кезегіне жылжытыңыз. Қалпына келтіру үшін енгізу деректерін түзету, тіркелгі деректерін қалпына келтіру, провайдердің көмегі немесе кейінірек бақыланатын қайта ойнату қажет пе екенін анықтаңыз. Оны үнсіз жоймаңыз немесе сол шексіз қайта сұрау циклін қайта бастамаңыз.

Дереккөздер

• RFC 9110: HTTP Semantics — HTTP күй семантикасы, идемпотентті әдістер, автоматты қайта сұрау мәселелері және Retry-After өрісі.
• RFC 6585: Additional HTTP Status Codes — 429 Too Many Requests анықтамасы және оның қосымша Retry-After тақырыбы.
• 17TRACK Tracking API — tracking API өніміне арналған ресми бастапқы бет.
• 17TRACK API documentation — провайдерге тән интеграция талаптарын тексеруге арналған анықтамалық.