Soʻrov va idempotentlik

Soʻrov — haqiqat manbai

GET /serving-tasks/?status=offered — ishni shu tarzda topasiz. Vebhuklar, agar roʻyxatdan oʻtkazilgan boʻlsa, kechikishni kamaytirish vositasi — haqiqat emas. Parkingiz smenada ekan, Sitora bergan chastotada soʻrang.

Bitta sahifa koʻpi bilan limit ta vazifa qaytaradi — sukut boʻyicha 50, eng koʻpi 100. Band kassada takliflar bitta sahifa koʻrsatganidan koʻproq boʻlishi mumkin, shuning uchun qisqa roʻyxatni tinch oshxona deb oʻqimang, limit ni koʻtaring. Vebhuk yetkazishlari roʻyxati ham shu parametrni qabul qiladi: sukut boʻyicha 100, eng koʻpi 200.

Soʻrov chastotasini Sitora belgilaydi

Har bir vazifalar roʻyxati javobi — 200 ham, 304 ham — keyingi soʻrovdan oldin necha soniya kutishni aytadi:

X-Sitora-Poll-After: 2
Retry-After: 2

Ikkala sarlavha ham bir xil sonni olib yuradi. Shuncha kuting va yana soʻrang.

Intervalni kodga qattiq yozmang. Sitora uni sizning relizingizsiz butun park boʻylab koʻtarishi mumkin — quvvat muammosi shu tarzda trafikni rad etish bilan emas, parklarni sekinlatish bilan hal qilinadi. Bugun vazifalar roʻyxati ikki soniya soʻraydi.

Muvaffaqiyatli javobdagi Retry-After — bu surʼat, xato emas. Uni olib yurgan 200 yoki 304 aynan shuni bildiradi: mana javob va mana qachon qaytish kerak.

Heartbeat va park holati suratiga bu surʼat qoʻllanmaydi. Heartbeatʼni oʻz taymeringiz boʻyicha, taxminan 30 soniyada bir marta yuborishda davom eting — heartbeat va park holati buni tasvirlaydi.

ETag

Vazifalar roʻyxati ETag olib yuradi. Uni If-None-Match sifatida qaytarib yuboring; oʻzgarmagan roʻyxat tanasiz 304 Not Modified qaytaradi. Bu zich soʻrov sikllarini ikkala tomon uchun deyarli bepul qiladi — albatta amalga oshiring.

Vebhuk yetkazishlari roʻyxati ETag olib yurmaydi. Uni since_id bilan varaqlang.

Chastota cheklovlari

Cheklovlar qatʼiy va har bir hisob maʼlumoti boʻyicha hisoblanadi:

Yuza	Chegara
Vazifalarni soʻrash	daqiqasiga 60 (~1/s)
Vazifani qabul qilish/xabar berish	daqiqasiga 120
Heartbeat	daqiqasiga 30

Koʻproq kerak boʻlgan kontroller band emas, notoʻgʻri ishlayapti. 429 — bu Sitoraning rad etishi, surʼat emas: uning Retry-After sarlavhasiga rioya qilish shart, unga tushishning oʻzi esa siklingiz yuqoridagi chastota sarlavhasini eʼtiborsiz qoldirganini bildiradi.

Idempotentlik

Har bir oʻzgartirish Idempotency-Key sarlavhasini (yoki tanadagi client_idempotency_key maydonini) qabul qiladi. Bir xil kalitli takroriy soʻrov dastlabki natijani qaytaradi va yangi hech nima yozmaydi.

Doim yuboring. Tarmoq soʻrov oʻrtasida uziladi; kalit bilan siz bemalol qayta urinishingiz va daʼvo yoki xabarni hech qachon ikki marta qoʻllamasligingiz mumkin.

Har bir amalga bitta kalit ishlating, har bir vazifaga bitta emas: bir xil mantiqiy amalning qayta urinishlari uchun oʻsha kalitni, har bir yangi amal uchun esa yangi kalitni. Oʻsha vazifaning boshqa oʻtishiga allaqachon sarflangan kalit idempotency_key_reused bilan 409 qaytariladi. Kalitlar 128 belgi bilan cheklangan.

Soʻrov tanalari ham chegaralangan — ixtiyoriy telemetry va heartbeat summary obyektlari eng koʻpi 4 KB, 5 darajadan chuqur boʻlmagan va bitta obyekt yoki massivda 50 tadan koʻp boʻlmagan yozuvli JSON obyektlari boʻlishi kerak.

Xato konverti

Robototexnika yuzasining oʻzi koʻtargan rad etish bitta shaklni qaytaradi:

{ "detail": "Odam oʻqiy oladigan izoh.", "code": "machine_readable_code" }

HTTP holati	Kodlar
400	unknown_status (status filtridagi notanish qiymat), invalid_limit, invalid_since_id, unknown_failure_code
404	task_not_found, delivery_not_found
409	already_claimed, robotics_paused, platform_frozen, arrival_dwell_pending, idempotency_key_reused, task_<current_status> tartib ziddiyatlari
410	offer_expired
503	content_key_missing — Sitoraning bu oʻrnatmasi notoʻgʻri sozlangan, qayta urinish yordam bermaydi

code boʻyicha shoxlang, detail matni boʻyicha emas — detail soʻzlashuvi oʻzgarishi mumkin; kodlar shartnomaviy.

code siz rad etishlar

Uchta rad etish soʻrovingiz robototexnika yuzasiga yetib borgunicha javob beriladi, shuning uchun ularda code maydoni yoʻq. body["code"] ni shartsiz oʻqiydigan mijoz uchalasida ham qulaydi — bu maydonni ehtiyotkorlik bilan oʻqing.

• Notoʻgʻri tana maydon tekshiruvi bilan rad etiladi va javob tanasi muammoli maydon nomi boʻyicha kalitlanadi: {"status": ["\"loaded\" is not a valid choice."]}.
• 401 va 403 {"detail": "..."} qaytaradi. 401 kalit yaroqsiz yoki bekor qilinganini bildiradi. 403 kalit toʻgʻri, ammo u bilan harakat qilib boʻlmasligini bildiradi: yo parkingiz vakolatini yoʻqotgan — sertifikat, faollashuv yoki tarif huquqi — yoki kalit oʻsha endpoint uchun scopega ega emas. Sabab matnda nomlanadi.
• 429 Retry-After sarlavhasi bilan {"detail": "..."} qaytaradi.