Bir API sorğusunda bir neçə izləmə nömrəsini necə göndərmək olar (toplu əməliyyat limitləri və qismən uğursuzluqlar)
Bir API sorğusunda bir neçə izləmə nömrəsi göndərmək üçün toplu qəbul etdiyini açıq şəkildə göstərən Tracking API endpoint-indən istifadə edin, hər göndərişi onun sorğu sxeminə uyğun formatlaşdırın və daha böyük siyahıları sənədləşdirilmiş limitlər daxilində toplulara bölün. Sonra həm HTTP cavabını, həm də hər göndərişin nəticəsini yoxlayın: uğurlu HTTP sorğusu hər izləmə nömrəsinin qəbul edildiyi demək deyil. Yalnız uyğun uğursuzluqları yenidən cəhd edin və bütün toplunu yenidən göndərməzdən əvvəl qeyri-müəyyən nəticələri uyğunlaşdırın.

Bu təlimat göndəriş izləməsini sifariş idarəetmə sistemi, anbar platforması, e-ticarət tətbiqi və ya daxili panelə qoşan tərtibatçılar üçündür. Məqsəd sadəcə daha az sorğu göndərmək deyil. Məqsəd dublikat iş yaratmadan və uğursuz qeydləri itirmədən hər göndərişi nəzərə almaqdır.
Əvvəlcə batch endpoint-in əslində nə etdiyini müəyyənləşdirin
İzləmə inteqrasiyası bir neçə fərqli əməliyyatı əhatə edə bilər. Göndərişləri qeydiyyatdan keçirmək, onların ən son izləmə məlumatlarını əldə etmək və sonrakı yeniləmələri qəbul etmək bir-birini əvəz etmir.
- Qeydiyyat: Xidmətin göndərişləri izləməyə başlaması və ya izləməni davam etdirməsi üçün göndərişləri təqdim edin.
- Axtarış: Endpoint-in əldəetmə qaydalarına uyğun olaraq göndərişlər barədə izləmə məlumatı tələb edin.
- Çatdırılmanın yenilənməsi: Webhook kimi dəstəklənən mexanizm vasitəsilə sonrakı dəyişiklikləri qəbul edin və ya planlaşdırılmış sorğularla əldə edin.
Ehtiyacınız olan dəqiq əməliyyat üçün sənədləri yoxlayın. Bir neçə qeydi qəbul edən qeydiyyat endpoint-i axtarış endpoint-inin də eyni sayda qeydi qəbul etdiyini, eyni sxemdən istifadə etdiyini və ya eyni sürət limitini paylaşdığını göstərmir.
17TRACK inteqrasiyası üçün Tracking API məhsul səhifəsi ilə başlayın və əməliyyatı, autentifikasiya metodunu, sorğu formatını və cavab sahələrini təsdiqləmək üçün rəsmi API sənədlərindən istifadə edin. Aşağıdakı nümunələri həmin API müqaviləsinin əvəzi deyil, tətbiq nümunələri kimi qəbul edin.
Batch limitləri yalnız göndərişlərin maksimum sayı deyil
Tracking API üçün universal batch limiti yoxdur. Limitlər provayderə, endpoint-ə, API versiyasına və hesab konfiqurasiyasına görə fərqlənə bilər. Batch tətbiq etməzdən əvvəl bu məhdudiyyətləri ayrıca qeyd edin.
| Məhdudiyyət | Nə təsdiqlənməlidir | Tətbiq nəticəsi |
|---|---|---|
| Sorğu başına elementlər | Konkret əməliyyat üçün maksimum qeyd sayı | Göndərməzdən əvvəl giriş siyahısını bölün |
| Sorğu gövdəsinin ölçüsü | Sənədləşdirilmiş bayt limiti | İstəyə bağlı sahələri və seriyalaşdırma ölçüsünü nəzərə alın |
| Sorğu tezliyi | Müəyyən interval ərzində icazə verilən sorğu sayı | Sorğuları ümumi limiter vasitəsilə tənzimləyin |
| Paralellik | Eyni vaxtda sorğularla bağlı məhdudiyyət | Aktiv işçilərin sayını məhdudlaşdırın |
| İstifadənin hesablanması | İstifadənin sorğuya, göndərişə və ya başqa vahidə görə hesablanması | Sərfiyyatı sorğu həcmindən ayrıca qiymətləndirin |
Məsələn, fərz edilən endpoint sorğu başına 25 qeydə icazə verirsə, 63 qeyd üçün 25, 25 və 13 qeyddən ibarət üç sorğu tələb olunur. Bu rəqəmlər yalnız qruplaşdırmanı göstərir; onlar 17TRACK limitləri deyil.
Batch-lərin ödənişli istifadəni azaltdığını düşünməyin. Onlar HTTP sorğularının əlavə xərclərini azalda bilər, lakin ödənişlərə təsir provayderin faktiki hesablaşma qaydalarından asılıdır. Eyni şəkildə, etibarlı batch ölçüsü limitsiz paralel sorğulara icazə vermir.
Sorğu yaratmazdan əvvəl qeydləri hazırlayın
Qarşısı alına bilən batch uğursuzluqlarının əksəriyyəti giriş məlumatlarının hazırlanmasından başlayır. Hər göndərişi batch-ə əlavə etməzdən əvvəl yoxlayın, lakin müxtəlif daşıyıcılardan gələn qanuni izləmə nömrələrini səhvən rədd edən qaydalardan qaçın.
- İzləmə nömrələrini sətir kimi saxlayın. Onları rəqəmə çevirmək başlanğıc sıfırlarını silə və ya uzun identifikatorları dəyişdirə bilər.
- Təsadüfi ətraf boşluqları silin. Müvafiq spesifikasiya normallaşdırmaya icazə vermədikcə daxili simvolları silməyin və registri dəyişməyin.
- Tələb olunan sahələri yoxlayın. Bəzi iş axınlarında daşıyıcı identifikatoru və ya əlavə göndəriş məlumatı tələb oluna bilər. Yalnız sənədləşdirilmiş sahə adlarından və dəyərlərindən istifadə edin.
- Aydın deduplikasiya əhatəsi seçin. Təkrarlanan izləmə nömrəsi hər daşıyıcı, satıcı və ya tarixi göndəriş üzrə avtomatik olaraq dublikat sayılmır.
- Yerli göndəriş identifikatorunu saxlayın. API fərdi istinad sahələrini qəbul etməsə belə, göndərilən element ilə sifariş və ya göndəriş qeydi arasındakı əlaqəni saxlayın.
Bir neçə şəbəkə üzrə Carrier Tracking üçün daşıyıcını yalnız izləmə nömrəsinin uzunluğuna və ya prefiksinə əsasən müəyyən etməyin; konkret iş axınınızda bu nəticə etibarlı deyilsə, belə etməyin. API daşıyıcının müəyyənləşdirilməsini dəstəkləyirsə, onun sənədləşdirilmiş qeyri-müəyyənliklə işləmə qaydasına əməl edin.
Nümunəvi sorğu strukturu
Aşağıdakı JSON batch yükünün konsepsiyasını göstərir. Wrapper, xüsusiyyət adları və identifikatorlar nümunəvidir, 17TRACK sorğu sxemi deyil. Bəzi API-lər massivdən ibarət obyekt əvəzinə birbaşa üst səviyyəli massiv gözləyir.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Yükü sətirləri birləşdirmək əvəzinə JSON seriyalaşdırıcısı vasitəsilə yaradın. Autentifikasiya məlumatlarını sənədləşdirilmiş mexanizmlə göndərin və onları mənbə kodu idarəetməsindən, brauzerə çatdırılan koddan və adi jurnallardan uzaq saxlayın.
Cavabı iki səviyyədə emal edin
Batch sorğusunun nəqliyyat səviyyəsində və tətbiq səviyyəsində nəticəsi olur. İnteqrasiyanız hər ikisini qiymətləndirməlidir.
Səviyyə 1: Sorğu istifadə edilə bilən cavab aldı?
HTTP statusu, cavab başlıqları və cavab gövdəsi ilə başlayın. Autentifikasiya xətaları, səhv formatlaşdırılmış sorğular, sürət məhdudiyyəti və server xətaları elementlərin normal emalına mane ola bilər. Şəbəkə taym-autu fərqlidir: müştəri serverin sorğunu qəbul edib-etmədiyini və ya emal edib-etmədiyini bilməyə bilər.
HTTP semantikası RFC 9110 ilə müəyyən edilir. Bununla belə, tətbiq səviyyəsindəki nəticə sahələrinin faktiki göndəriş nəticələrinə necə uyğun gəldiyini provayderin sənədləri müəyyənləşdirir.
Səviyyə 2: Hər göndərişə nə oldu?
Cavab element səviyyəsində nəticələri dəstəkləyirsə, təqdim edilmiş hər qeydi təsnif edin. HTTP 200 statusunun bütün qeydlərin uğurlu olduğu demək olduğunu və ya müqavilə bunu açıq şəkildə təmin etmədikcə nəticə siyahısının sorğu sırasını qoruduğunu düşünməyin.
- Qəbul edildi: Əməliyyat endpoint-in sənədləşdirilmiş tərifinə uyğun olaraq uğurla başa çatdı.
- Daimi giriş uğursuzluğu: Yenidən cəhd etməzdən əvvəl qeydi düzəldin və ya araşdırın.
- Yenidən cəhd edilə bilən uğursuzluq: Provayderin yenidən cəhd təlimatına uyğun olaraq növbəti cəhdi planlaşdırın.
- Naməlum nəticə: Cavab yoxdur, natamamdır və ya təqdim edilmiş qeydlə təhlükəsiz şəkildə uyğunlaşdırıla bilmir.
“Artıq qeydiyyatdan keçib” və ya oxşar dublikatla bağlı cavabları sənədləşdirilmiş mənasını anlayana qədər ayrıca saxlayın. Onlar istənilən vəziyyətin artıq mövcud olduğunu göstərə bilər, lakin avtomatik olaraq uğurlu sahiblik, konfiqurasiya və ya abunə təsdiqi kimi qəbul edilməməlidir.
Cavabı emal etdikdən sonra hər giriş qeydi dəqiq bir yerli nəticəyə malik olmalıdır. Faydalı uyğunlaşdırma yoxlaması belədir: təqdim edilmiş qeydlər qəbul edilmiş qeydlər və daimi uğursuzluqlar, yenidən cəhd edilə bilən uğursuzluqlar və naməlum nəticələrin cəminə bərabərdir. Bu, yerli uçot qaydasıdır, tələb olunan API cavab formatı deyil.
Uğurlu qeydləri təkrar göndərmədən qismən uğursuzluqları idarə edin
Təsəvvür edin ki, nümunəvi batch-də on göndəriş var: yeddisi qəbul edilir, ikisində tələb olunan sahələr etibarsızdır və birində sənədləşdirilmiş müvəqqəti xəta baş verir. Yeddi uğurlu nəticəni yadda saxlayın, iki etibarsız qeydi düzəlişə yönləndirin və yalnız müvəqqəti xətanı yenidən cəhd edin.
Bütün on qeydi yenidən göndərmək lazımsız trafik yaradır və dublikatların idarəsini çətinləşdirə bilər. Bu, ilkin rədd edilməni sonrakı dublikat cavabından ayırmağı da çətinləşdirir.
| Nəticə | Tövsiyə olunan əməl |
|---|---|
| Etibarsız sahə və ya dəstəklənməyən dəyər | Girişi düzəldin; dəyişiklik etmədən yenidən cəhd etməyin |
| Autentifikasiya və ya icazə xətası | Təsirə məruz qalan işi dayandırın və məlumatları və ya giriş icazəsini düzəldin |
| Sürət limiti cavabı | Sənədləşdirilmiş təlimata və uyğun cavab başlıqlarına əsasən gecikdirin |
| Müvəqqəti element səviyyəli xəta | Məhdud cəhd sayı və artan gecikmə ilə həmin elementə yenidən cəhd edin |
| Təqdimatdan sonra taym-aut | Qeyri-müəyyən kimi işarələyin; uyğunlaşdırın və ya sənədləşdirilmiş təhlükəsiz yenidən cəhd zəmanətlərindən istifadə edin |
| Tanınmayan və ya natamam nəticə | Sübutları saxlayın və uğuru fərz etmək əvəzinə araşdırın |
HTTP 429 həddən artıq çox sorğu olduğunu bildirir və cavabda RFC 6585-də təsvir edildiyi kimi Retry-After başlığı ola bilər. Bu başlığın həmişə mövcud olduğunu düşünməyin. Açıq yenidən cəhd gecikməsi verilmədikdə, API sənədlərinə uyğun məhdud artan gecikmə siyasətindən istifadə edin.
Bir neçə işçinin yenidən cəhdlərini yaymaq üçün təsadüfilik əlavə edin, maksimum cəhd sayını və ya yenidən cəhd müddətini təyin edin və tükənmiş qeydləri yoxlama növbəsinə göndərin. Sonsuz yenidən cəhd davamlı konfiqurasiya problemini gizlədə bilər.
Nə üçün taym-autlara xüsusi yanaşmaq lazımdır
Taym-aut rədd edilməni sübut etmir. Bağlantı kəsilməzdən əvvəl server batch-i qəbul etmiş ola bilər. Buna görə vəziyyəti dəyişən sorğunun avtomatik təkrar göndərilməsi işi təkrarlaya bilər.
Endpoint sənədləşdirilmiş idempotensiya açarlarını dəstəkləyirsə, açarın əhatə dairəsi və saxlanma müddəti daxil olmaqla onun qaydalarına əməl edin. İdempotensiya başlığı uydurub serverin ona əməl edəcəyini düşünməyin. Əks halda, yenidən göndərməzdən əvvəl istənilən vəziyyətin mövcud olub-olmadığını müəyyənləşdirmək üçün dəstəklənən axtarış və ya uyğunlaşdırma iş axınından istifadə edin. Yerli deduplikasiya öz işçilərinizi koordinasiya etməyə kömək edir, lakin server tərəfli idempotensiyaya zəmanət vermir.
Praktik batch emalı iş axını
Provayderə xas detalları adapterdə saxlayın ki, növbə, yenidən cəhd planlayıcısı və monitorinq məntiqi xam cavab sahələrinin adlarından asılı olmasın.
qeydləri yoxlayın və yerli göndəriş identifikatorlarını saxlayın
təyin edilmiş biznes əhatəsi daxilində dublikatları həll edin
sənədləşdirilmiş element və yük limitlərindən istifadə edərək qeydləri bölün
məhdud işçi hovuzu vasitəsilə hər batch üçün:
göndərməzdən əvvəl cəhd qeydini saxlayın
ümumi sürət limitini gözləyin
provayderə xas adapterdən istifadə edərək göndərin
nəticə qeyri-müəyyəndirsə:
uyğunlaşdırma növbəsinə əlavə edin
davam edin
sorğu və element səviyyəli nəticələri təsnif edin
təqdim edilmiş hər qeyd üçün bir nəticə saxlayın
yalnız uyğun uğursuzluqları yenidən cəhd üçün planlaşdırın
etibarsız və ya tükənmiş qeydləri yoxlamaya yönləndirin
Nəticələrin saxlanmasını və yenidən cəhdlərin planlaşdırılmasını bərpa edilə bilən edin. Məsələn, davamlı iş qeydi və ya tranzaksiyalı növbələmə nümunəsi proses qəzasının yenidən cəhd qərarının itirilməsinin qarşısını ala bilər. İşçilər yenidən başladıqda, göndərilməmiş işi uzaqdakı nəticəsi hələ qeyri-müəyyən olan işdən ayıra bilməlidirlər.
Batch ölçüsünü kod bazasına səpələnmiş sabit deyil, müvafiq endpoint-ə bağlı konfiqurasiya edilə bilən parametr kimi istifadə edin. Problemləri araşdırarkən və ya problemli qeydləri ayırarkən daha kiçik batch faydalı ola bilər; icazə verilən ən böyük batch avtomatik olaraq ən yaxşı iş ölçüsü deyil.
Yalnız HTTP işləkliyini deyil, göndəriş nəticələrini də monitorinq edin
API Monitoring göndərişlərin nəzərdə tutulan vəziyyətə çatıb-çatmadığını göstərməlidir. Yalnız HTTP uğur faizlərini göstərən panel başqa cür uğurlu cavabların daxilindəki qismən uğursuzluqları qaçıra bilər.
- Elementlərin qəbul faizi: Təkrar cəhdlərin necə nəzərə alındığı aydın şəkildə müəyyən edilməklə, qəbul edilmiş qeydlərin təqdim edilmiş qeydlərə nisbəti.
- Uğursuzluqların bölgüsü: Endpoint, sənədləşdirilmiş xəta kodu və müvafiq daşıyıcı kontekstinə görə saylar.
- Naməlum nəticələr: Uyğunlaşdırılmamış qeydlər və onların nə qədər müddətdir həll olunmamış qalması.
- Yenidən cəhd növbəsi: Gözləyən cəhdlər, ən köhnə cəhdin yaşı və tükənmiş cəhdlər.
- Sorğu sağlamlığı: Gecikmə, taym-outlar, sürət məhdudiyyəti və server xətaları.
- İzləmə yeniliyi: Qəbul edilmiş göndərişlərin sonradan istifadə edilə bilən izləmə məlumatı alıb-almaması.
Qeydiyyatın qəbul edilməsi yeni daşıyıcı skanının sübutu deyil. API emal statusunu göndərişin hərəkətindən və məlumatların yeniliyindən ayrı saxlayın ki, inteqrasiya hadisəsi çatdırılma gecikməsi ilə qarışdırılmasın.
Yerli batch identifikatorlarını, göndəriş istinadlarını, cəhd saylarını, sənədləşdirilmiş xəta kodlarını və mövcud olduqda provayder sorğu identifikatorlarını jurnala yazın. Giriş məlumatlarını və lazımsız şəxsi məlumatları redaktə edin. İzləmə identifikatorlarından yalnız əməliyyat baxımından zəruri olduqda istifadə edin və xam göndəriş identifikatorlarını yüksək kardinaliteli metrik etiketlərə yerləşdirməyin.
İstehsala keçməzdən əvvəl bu halları yoxlayın
Mövcud olduqda sənədləşdirilmiş sandbox və ya nəzarət edilən test mühitindən istifadə edin. Uydurulmuş izləmə nömrələrinin istehsalda proqnozlaşdırılan cavablar yaradacağını düşünməyin.
- Sənədləşdirilmiş element limitində etibarlı batch göndərin, sonra müştərinizin həddən artıq böyük batch-in qarşısını necə aldığını yoxlayın.
- Başlanğıc sıfırları olan izləmə nömrələrinin seriyalaşdırma və saxlanma zamanı qorunduğunu yoxlayın.
- Uğurlu qeydləri yenidən cəhd etmədən qəbul edilmiş və rədd edilmiş elementlərin qarışıq olduğu batch-i yoxlayın.
- Sürət məhdudiyyətini simulyasiya edin və bir neçə işçinin eyni limitə əməl etdiyini təsdiqləyin.
- Təqdimatdan sonra taym-autu simulyasiya edin və uyğunlaşdırma yolunu yoxlayın.
- Cavabın alınması ilə yerli saxlanma arasında işçini yenidən başladın.
- Çatışmayan, tanış olmayan və ya uyğunlaşdırıla bilməyən element nəticələrini yoxlayın.
- Etibarsız qeydlərin sonsuz yenidən cəhd əvəzinə görünən düzəliş növbəsinə çatdığını təsdiqləyin.
İstehsala hazır inteqrasiya təqdim edilmiş hər göndərişin vəziyyətini, nəticəsi müvəqqəti olaraq naməlum olanları da izah edə bilməlidir. Sorğuların sayını azaltmaq faydalıdır; lakin bu hesabatlılığı qorumaq daha vacib dizayn məqsədidir.
FAQ
Bir sorğuda neçə izləmə nömrəsi göndərə bilərəm?
Dəqiq endpoint və API versiyası üçün sənədləşdirilmiş limitdən istifadə edin. Həmçinin sorğu ölçüsünü, sürət limitlərini və hesaba xas məhdudiyyətləri yoxlayın. İzləmə API-ləri və ya bir API daxilindəki müxtəlif əməliyyatlar üçün tətbiq edilə bilən təhlükəsiz universal rəqəm yoxdur.
Bir etibarsız izləmə nömrəsi bütün batch-in uğursuz olmasına səbəb ola bilərmi?
Bəli, bu endpoint-in yoxlama qaydalarından asılıdır. Bəzi API-lər fərdi rədd cavabları qaytarır, digərləri isə elementlərin emalından əvvəl sorğunu rədd edə bilər. Həm sorğu səviyyəli xətaları, həm də element səviyyəli nəticələri yoxlayın; hər batch endpoint-in qismən qəbulu dəstəklədiyini düşünməyin.
HTTP cavabı uğurlu olduqda batch-i yenidən göndərməliyəmmi?
Avtomatik olaraq yox. Əvvəlcə sənədləşdirilmiş tətbiq səviyyəli statusu və element nəticələrini təhlil edin. Uğurlu qeydləri saxlayın və yalnız uyğun uğursuzluqları yenidən cəhd edin. Nəticə təhlükəsiz şəkildə şərh edilə bilmirsə, onu qeyri-müəyyən kimi təsnif edin və araşdırın.
Eyni batch-də müxtəlif daşıyıcıları qarışdıra bilərəmmi?
Yalnız endpoint bu sorğu strukturunu dəstəklədikdə. Daşıyıcı məlumatının hər göndəriş üzrə verilib-verilmədiyini, avtomatik müəyyənləşdirmənin dəstəklənib-dəstəklənmədiyini və müəyyənləşdirmə qeyri-müəyyən olduqda nə baş verdiyini təsdiqləyin. Çoxdaşıyıcılı xidmət öz-özlüyündə hər endpoint-in batch qaydalarını müəyyən etmir.
Batch göndərmək izləmə yeniləmələrinin daha tez gəlməsini təmin edirmi?
Batch tətbiqinizin göndərdiyi sorğuların sayını azalda bilər, lakin özü-özlüyündə daşıyıcı hadisələrinin daha tez görünməsinə səbəb olmur. Qeydiyyat, məlumatların əldə edilməsi, daşıyıcı skanının mövcudluğu və yeniləmələrin çatdırılması iş axınının ayrı-ayrı hissələridir.
Mənbələr
- 17TRACK Tracking API — izləmə inteqrasiyasını qiymətləndirən tərtibatçılar üçün rəsmi məhsul giriş nöqtəsi.
- 17TRACK API sənədləri — provayderə xas endpoint müqaviləsi, limitlər, autentifikasiya və cavab emalı üçün istinad.
- RFC 9110: HTTP Semantikası — HTTP status semantikası, idempotensiya, avtomatik yenidən cəhdlər və Retry-After.
- RFC 6585: Əlavə HTTP Status Kodları — HTTP 429 Too Many Requests və onun istəyə bağlı Retry-After başlığının tərifi.


