Tracking API-də xətaların idarə edilməsi: Yanlış izləmə nömrələrini, sorğu limitlərini və təkrar cəhdləri necə idarə etmək olar

İzləmə API xətalarını etibarsız girişləri, müvəqqəti nasazlıqları, sorğu limitlərini və göndəriş statusu nəticələrini ayırmaqla idarə edin. Etibarsız izləmə nömrələrini dəyişdirmədən yenidən göndərmək əvəzinə rədd edin və ya düzəldin, limit tətbiq edildikdə sorğu həcmini koordinasiya edin və məhdudlaşdırılmış eksponensial gecikmə və təsadüfilik ilə keçici xətaları yenidən sınayın. Qeydiyyat və ya digər yazma sorğusunu təkrarlamazdan əvvəl ilk cəhdin uğurlu olub-olmadığını müəyyən edin.

İzləmə məlumatlarını sifarişlərin idarə edilməsi sistemi, anbar platforması və ya müştəriyə yönəlmiş izləmə səhifəsi ilə əlaqələndirən tərtibatçılar üçün məqsəd sadəcə uğursuz sorğuların sayını azaltmaq deyil. Məqsəd təkrarlanan qeydiyyatlar, yenidən cəhd fırtınaları, yanıltıcı çatdırılma mesajları və lazımsız dəstək müraciətləri olmadan etibarlı göndəriş görünürlüğünü təmin etməkdir.

Cavab seçməzdən əvvəl uğursuzluğu təsnif edin

İzləmə inteqrasiyasında qiymətləndirilməli bir neçə ayrı nəticə var: şəbəkə sorğusunun tamamlanıb-tamamlanmadığı, API-nin əməliyyatı qəbul edib-etmədiyi, tələb olunan hər bir izləmə elementinin uğurlu olub-olmadığı və göndəriş hadisələrinin əlçatan olub-olmadığı. Bu dörd nəticənin hamısını vahid uğur və ya uğursuzluq bayrağı kimi qəbul etmək qarşısı alına bilən xətalara səbəb olur.

HTTP uğur cavabı partiyadakı hər bir elementin uğurlu olduğu anlamına gəlmir. Əksinə, izləmə hadisələri olmadan uğurla işlənmiş axtarış mütləq API xətası deyil. Cavab məzmununu yoxlayın və hər bir nəticə üçün provayderin sənədləşdirilmiş mənasını tətbiq edin.

Vəziyyət	Tövsiyə olunan əməl	Dəyişdirmədən yenidən sınansın?
Səhv formatlı nömrə və ya etibarsız sorğu sahəsi	Girişi yoxlayın və düzəldin	Xeyr
Çatışmayan və ya etibarsız autentifikasiya məlumatları	Məlumatları, icazələri və mühiti yoxlayın	Düzəldilənə qədər xeyr
Sorğu limiti cavabı	Təsirə məruz qalan işi gecikdirin və ümumi sorğu təzyiqini azaldın	Tələb olunan gözləmədən sonra, təhlükəsizdirsə
Müvəqqəti xidmət xətası	Məhdudlaşdırılmış gecikmə tətbiq edin və əməliyyatın təhlükəsizliyini yoxlayın	Adətən, yenidən cəhd büdcəsi daxilində
Qeydiyyat göndərildikdən sonra vaxt aşımı	Qeydiyyatın mövcud olub-olmadığını uzlaşdırın	Kor-koranə yox
Qəbul edilmiş, lakin göndəriş hadisələri olmayan axtarış	Sənədləşdirilmiş izləmə həyat dövrünə əməl edin	Sürətli yenidən cəhdlər deyil, planlaşdırılmış yeniləmədən istifadə edin

HTTP status kodları başlanğıc nöqtəsidir, lakin provayderə xas tam qərar ağacı deyil. RFC 9110 HTTP semantikasını, RFC 6585 isə 429 Too Many Requests kodunu müəyyən edir. İnteqrasiyanız həmçinin sənədləşdirilmiş tətbiq xətası kodlarını və element səviyyəli nəticələri şərh etməlidir.

Etibarsız izləmə nömrələri: səhv girişi çatışmayan hadisələrdən ayırın

“Etibarsız izləmə nömrəsi” müxtəlif problemləri ifadə edə bilər: səhv formatlı identifikator, dəstəklənməyən daşıyıcı və nömrə kombinasiyası, tələb olunan daşıyıcı sahəsinin çatışmaması və ya provayderə xas digər yoxlama xətası. Sadəcə izləmə hadisələri qaytarılmadığı üçün nömrənin etibarsız olduğunu düşünməyin.

İdentifikatora zərər vermədən yoxlayın

• İzləmə nömrələrini sətir kimi saxlayın. Rəqəmsal saxlama başlanğıcdakı sıfırları silə və ya uzun identifikatorları dəyişə bilər.
• Orijinal girişi qoruyun. Çevrilmələrin izlənilə bilməsi üçün ayrıca normallaşdırılmış dəyər saxlayın.
• Ehtiyatla normallaşdırın. Uyğun olduqda kənar boşluqları silin, lakin sənədləşdirilmiş qaydalar buna icazə vermədikcə daxili simvolları silməyin və hərf registrini dəyişməyin.
• Tələb olunan sahələri yerli olaraq yoxlayın. Boş nömrələri, çatışmayan daşıyıcı identifikatorlarını və etibarsız sorğu strukturlarını göndərməzdən əvvəl aşkar edin.
• Universal izləmə nömrəsi regex-indən istifadə etməyin. Bir daşıyıcı üçün hazırlanmış qayda digər daşıyıcıların etibarlı identifikatorlarını rədd edə bilər.
• Sahənin nə ehtiva etdiyini təsdiqləyin. Endpoint onları açıq şəkildə dəstəkləmədikcə sifariş nömrəsi, anbar istinadı və daşıyıcının izləmə nömrəsi bir-birini əvəz etmir.

API girişi açıq şəkildə rədd edirsə, onu avtomatik yenidən cəhd dövrünə yönəltmək əvəzinə düzəlişə göndərin. Hər yoxlama problemini “izləmə uğursuz oldu” kimi ümumiləşdirmək əvəzinə “daşıyıcı identifikatoru tələb olunur” kimi faydalı səbəb göstərin.

“Hadisə yoxdur” vəziyyətini ayrıca hal kimi qəbul edin

Göndərişdə faydalı hərəkət hadisələri əlçatan olmamışdan əvvəl izləmə identifikatoru ola bilər. Düzgün cavab API-nin sənədləşdirilmiş status modelindən və göndəriş kontekstindən asılıdır. İdentifikatorun göndəriş sistemindən gəlib-gəlmədiyini, daşıyıcı seçiminin düzgün olub-olmadığını və cavabın rədd edilmiş giriş əvəzinə gözlənilən məlumatı göstərib-göstərmədiyini yoxlayın.

input_rejected, awaiting_events və temporarily_unavailable kimi fərqli daxili statuslardan istifadə edin. Bunlar standartlaşdırılmış API dəyərləri deyil, təklif olunan tətbiq statuslarıdır. Onlar müvəqqəti məlumat boşluğunun qeyri-dəqiq müştəri mesajına çevrilməsinin qarşısını almağa kömək edir.

Sorğu limitlərini hər işçi üzrə deyil, inteqrasiya üzrə idarə edin

RFC 6585 HTTP 429-u sürət məhdudiyyəti cavabı kimi müəyyən edir və cavabın Retry-After başlığı ehtiva etməsinə icazə verir. Standart universal izləmə API limiti və ya hesablama üsulu müəyyən etmir. Limitlər hesab, autentifikasiya məlumatı, endpoint və ya başqa əhatə dairəsi üzrə sənədləşdirilə bilər; provayderin faktiki qaydalarından istifadə edin.

RFC 9110 Retry-After üçün iki forma müəyyən edir: mənfi olmayan saniyə sayı və ya HTTP tarixi. Hər ikisini təhlil edin. Dəyər tarixdirsə, qalan gözləmə müddətini diqqətlə hesablayın və saat fərqlərini nəzərə alın. Dəyər yoxdursa və ya istifadə edilə bilmirsə, konfiqurasiya edilmiş ehtiyat gecikmə siyasətini tətbiq edin.

Digər işçilər eyni limiti istifadə etməyə davam etdiyi halda bir işçinin müstəqil şəkildə yatması kifayət deyil. Müvafiq autentifikasiya məlumatı və ya hesab üçün sürət nəzarətini ümumi sərhəddə yerləşdirin. Mərkəzi planlaşdırıcı, ümumi token bucket və ya ekvivalent paylanmış nəzarət bu trafiki koordinasiya edə bilər.

1. Təsirə məruz qalan əhatə dairəsini müəyyən edin. Limitin hansı endpoint, autentifikasiya məlumatı və ya hesaba tətbiq olunduğunu müəyyənləşdirin.
2. Serverin gözləmə göstərişinə əməl edin. Etibarlı Retry-After dəyərinin icazə verdiyindən daha erkən yenidən cəhd planlaşdırmayın.
3. Təsirə məruz qalan növbədəki işi gecikdirin. Limitlər həqiqətən müstəqildirsə, əlaqəsiz trafiki bloklamayın.
4. Paralelliyi və ya sorğu tezliyini azaldın. Sorğu modelini dəyişdirmədən yalnız bir dəfə gözləmək eyni problemi yenidən yarada bilər.
5. Fasilələrlə davam edin. Gözləmə başa çatdıqda bütün yığılmış işləri eyni vaxtda buraxmayın.

Dəstəkləndikdə partiyalı sorğuların istifadəsi sorğuların sayını azalda bilər, lakin sənədləşdirilmiş partiya ölçüsü və hesablama qaydalarına əməl edilməlidir. Bir partiyanın limitdən bir vahid istifadə etdiyini düşünməyin. Eyni şəkildə, qarşısı alına bilən sorğuları azaltmaq üçün mövcud olduqda webhook-lardan istifadə edin, lakin inteqrasiyanızın tələb etdiyi uzlaşdırma prosesini qoruyun.

Gecikmə və təsadüfilik ilə məhdudlaşdırılmış yenidən cəhdlərdən istifadə edin

Uğursuzluq sorğunu dəyişdirmədən aradan qalxa bilərsə və əməliyyatın təkrarlanması təhlükəsizdirsə, yenidən cəhdlər uyğundur. Müvəqqəti bağlantı xətaları və seçilmiş server xətaları bu kateqoriyaya aid ola bilər. Səhv formatlı məzmun, etibarsız autentifikasiya məlumatı və ya daimi icazə problemi isə adətən düzəliş tələb edir.

Praktik ehtiyat variantı tam təsadüfiliklə məhdudlaşdırılmış eksponensial gecikmədir:

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)

Burada retry_index ilk yenidən cəhd üçün sıfırdan başlayır və çatışmayan Retry-After əlavə minimum gözləmə yaratmır. Bunlar məcburi HTTP alqoritmi deyil, tətbiq seçimləridir. Əsas gecikməni, yuxarı həddi, cəhd limitini və ümumi son müddəti iş yükünüzə və provayderin təlimatlarına əsasən seçin.

Təsadüfilik hər işçinin eyni cədvəl üzrə təkrar etməsi əvəzinə sorğuları zamana yayır. Gecikmə həddi eksponensial komponenti məhdudlaşdırır; daha uzun və etibarlı server gözləməsini ləğv etməməlidir. Bu gözləmə işinizin son müddətini keçirsə, erkən yenidən cəhd etmək əvəzinə siyasətə uyğun olaraq işi təxirə salın və ya dayandırın.

Hər yenidən cəhd zəncirinə son hədd qoyun

• Cəhd limiti: əlavə sorğuların sayını məhdudlaşdırın.
• Keçən vaxt limiti: faydalı emal müddətini keçmiş işi yenidən sınamağı dayandırın.
• Aydın məsuliyyət: yenidən cəhdlərə hansı təbəqənin nəzarət etdiyini seçin ki, HTTP müştərisinin və növbənin cəhdləri gözlənilmədən çoxalmasın.
• Davamlı planlaşdırma: qısaömürlü proseslərdə uzun müddət yatmağa güvənmək əvəzinə gecikdirilmiş işləri saxlayın.
• Bərpa yolu: tükənmiş işləri səbəb və növbəti əməl ilə nəzərdən keçirilə bilən uğursuz işlər növbəsinə göndərin.

Uzunmüddətli nasazlıq zamanı adi çağırışları müvəqqəti dayandıran və nəzarətli bərpa yoxlamalarına icazə verən circuit breaker mexanizmini nəzərdən keçirin. Bu, tətbiqin dayanıqlılığı nümunəsidir və hər hansı konkret izləmə provayderinin bunu tələb etdiyini göstərmir.

Qeyri-müəyyən yazma əməliyyatlarını yenidən göndərməzdən əvvəl həll edin

Vaxt aşımı tətbiqinizin tam cavab almadığını bildirir. Bu, serverin sorğunu rədd etdiyini və ya heç vaxt emal etmədiyini sübut etmir. İzləmə nömrələrini qeydiyyata alarkən və ya izləmə konfiqurasiyasını dəyişərkən bu fərq əhəmiyyətlidir.

RFC 9110 idempotent metodları izah edir və təkrarlanmanın təhlükəsiz olduğunu və ya ilkin əməliyyatın tətbiq edilmədiyini bilmək üçün əsas olmadan idempotent olmayan sorğuların avtomatik təkrarlanmasına qarşı xəbərdarlıq edir. Hər izləmə endpoint-inin yalnız oxuma axtarışı kimi davrandığını düşünmək əvəzinə, sənədləşdirilmiş əməliyyat semantikasını qiymətləndirin.

• Mövcud olduqda provayderin sənədləşdirdiyi idempotentlik mexanizmindən onun əhatə dairəsi və saxlanma qaydalarına uyğun istifadə edin.
• Eyni məntiqi əməliyyatın yenidən cəhdləri üçün eyni idempotentlik açarını saxlayın; ixtiyari xüsusi başlığın qəbul ediləcəyini düşünməyin.
• Dəstəklənirsə, qeyri-müəyyən yazmanı təkrarlamazdan əvvəl mövcud qeydiyyatı yoxlayın.
• Provayderin sənədləşdirilmiş göndəriş identikliyinə uyğun yerli unikallıq məhdudiyyətindən istifadə edin.
• Əməliyyatın nəticəsini saxlayın ki, növbənin yenidən çatdırılması avtomatik olaraq başqa yazma əməliyyatına səbəb olmasın.

Partiyalı əməliyyatlar üçün hər bir elementin nəticəsini saxlayın. Yalnız müvəqqəti uğursuz kimi təsnif edilən elementləri yenidən sınayın və nəticələri naməlum qalan elementləri uzlaşdırın. Bütün partiyanın yenidən icrası uğurlu işi təkrarlaya və sorğu limitindən lazımsız istifadə edə bilər.

Siyasəti izləmə provayderinizə tətbiq edin

17TRACK inteqrasiyası üçün provayderə xas müqavilənin başlanğıc nöqtəsi kimi Tracking API səhifəsindən və rəsmi API sənədlərindən istifadə edin. Ümumi HTTP təlimatından irəli gələn fərziyyələri kodlaşdırmaq əvəzinə xəta təsnifatçınızı konfiqurasiya edilə bilən saxlayın.

Tətbiqdən əvvəl müvafiq endpoint-in sorğu sxemini, cavab zərfini, element səviyyəli xətaların mənalarını, sorğu limiti əhatə dairəsini, partiya məhdudiyyətlərini və dublikat göndəriş qaydalarını təsdiqləyin. Hadisə çatdırılmasından istifadə etdikdə təsdiqləmə, autentifikasiya və yenidən çatdırılma tələblərini də yoxlayın. Bu təlimat konkret 17TRACK sorğu limiti, yenidən cəhd cədvəli və ya idempotentlik funksiyası müəyyən etmir.

Təsdiqlənmiş hər qaydanı provayder cavabından tətbiq əməliyyatına xəritələndirmədə qeyd edin: girişi düzəltmək, konfiqurasiyanı bərpa etmək, gözləmək, uzlaşdırmaq və ya eskalasiya etmək. Tanınmayan xəta diaqnostik konteksti qorumalı və qeyri-məhdud yenidən cəhdlərə yönəlmək əvəzinə məhdudlaşdırılmış ehtiyat yolu izləməlidir.

Bərpa keyfiyyətini izləyin və uğursuzluq yollarını yoxlayın

Əməliyyatı, endpoint-i, HTTP statusunu, tətbiq xətası kodunu, cəhd nömrəsini, gecikməni, növbəti planlaşdırılmış əməliyyatı və təqdim edildikdə provayder sorğu identifikatorunu qeyd edin. API açarlarını, lazımsız ünvan məlumatlarını və məhdudiyyətsiz cavab məzmununu qeydə almaqdan çəkinin. Tam dəyərlər lazım olmadıqda izləmə identifikatorlarını maskalayın və ya heşləyin.

Etibarsız giriş nisbətlərini, sürət məhdudiyyətlərini, növbə yaşını, tükənmiş yenidən cəhdləri və son uğurlu sinxronizasiyanı ayrıca izləyin. İnteqrasiyada HTTP xəta nisbəti aşağı olduğu halda belə köhnəlmiş göndəriş məlumatı təqdim edilə bilər. Müştəriyə yönəlmiş səhifələr son məlum göndəriş statusunu saxlamalı və yeniləmə uğursuzluğunu daşıyıcı tərəfindən bildirilmiş çatdırılma istisnasından ayırmalıdır.

Buraxılışdan əvvəl səhv formatlı girişi, hadisələri olmayan etibarlı identifikatorları, Retry-After-ın hər iki formasını, çatışmayan başlıqları, qismən partiya xətalarını, yazmalardan sonra vaxt aşımını və növbənin yenidən çatdırılmasını yoxlayın. Həmçinin yenidən cəhd büdcəsini tükəndirəcək qədər uzun davam edən nasazlığı simulyasiya edin. Test yalnız işin proqnozlaşdırılan şəkildə dayandırıldığı və ya təxirə salındığı, uğurlu elementlərin lazımsız yerə təkrarlanmadığı və uğursuz elementlərin bərpa edilə bildiyi halda keçmiş sayılır.

Tez-tez verilən suallar

Etibarsız izləmə nömrəsi avtomatik yenidən sınanmalıdır?

API girişi açıq şəkildə etibarsız kimi rədd etdikdə xeyr. Əvvəlcə nömrəni, daşıyıcı seçimini və ya tələb olunan sahələri düzəldin. Cavab bunun əvəzinə göndəriş hadisələrinin hələ əlçatan olmadığını bildirirsə, onu yoxlama xətası kimi qəbul etmək əvəzinə sənədləşdirilmiş yeniləmə iş prosesindən istifadə edin.

HTTP 200 partiya sorğusunun tam uğurlu olması deməkdir?

Mütləq deyil. Əməliyyat səviyyəli və element səviyyəli nəticələr üçün provayderin cavab sxemini yoxlayın. Uğurları saxlayın və uğursuzluqları ayırın ki, bir elementin yenidən sınanması qalanlarını lazımsız yerə təkrarlamasın.

İzləmə inteqrasiyası neçə yenidən cəhdə icazə verməlidir?

Universal say yoxdur. Provayderin təlimatlarına, əməliyyatın təhlükəsizliyinə və nəticənin nə qədər müddət faydalı qalmasına əsasən həm cəhd limiti, həm də keçən vaxt büdcəsi müəyyən edin. Planlaşdırılmış fon sinxronizasiyası interaktiv müştəri sorğusundan fərqli bərpa müddətinə dözə bilər.

Vaxt aşımı göndərişi dərhal uğursuz kimi işarələməlidir?

Xeyr. Sorğu vaxtının bitməsi inteqrasiya nəticəsidir, göndəriş hadisəsi deyil. Son məlum izləmə statusunu qoruyun, təhlükəsiz bərpa planlaşdırın və bağlantı problemini çatdırılma uğursuzluğu bildirişinə çevirməyin.

Yenidən cəhdlər tükəndikdə nə baş verməlidir?

İşi diaqnostik konteksti ilə davamlı uğursuz işlər və ya nəzərdən keçirmə növbəsinə köçürün. Bərpanın düzəldilmiş giriş, bərpa edilmiş autentifikasiya məlumatları, provayder dəstəyi və ya sonradan nəzarətli təkrar icra tələb edib-etmədiyini müəyyənləşdirin. İşi səssizcə silməyin və eyni qeyri-məhdud yenidən cəhd dövrünü yenidən başlatmayın.

Mənbələr

• RFC 9110: HTTP Semantikası — HTTP status semantikası, idempotent metodlar, avtomatik yenidən cəhd mülahizələri və Retry-After sahəsi.
• RFC 6585: Əlavə HTTP Status Kodları — 429 Too Many Requests kodunun və onun ixtiyari Retry-After başlığının tərifi.
• 17TRACK Tracking API — izləmə API məhsulu üçün rəsmi giriş nöqtəsi.
• 17TRACK API sənədləri — provayderə xas inteqrasiya tələblərini yoxlamaq üçün istinad.