إنتقل إلى المحتوى الرئيسي

منع التكرار

قد تنقطع الشبكة بعد أن ينفّذ الخادم الطلب. لتعيد محاولة عملية كتابة دون تنفيذها مرتين، أرسل الترويسة Idempotency-Key: أي سلسلة فريدة، والأفضل UUID.

curl -X POST "https://api.zaitrack.app/v1/dispatch/jobs" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: 5b0e3f4c-2d1a-4c7e-9f8b-1a2b3c4d5e6f" \
-H "Content-Type: application/json" \
-d @job.json

ما تفعله البوابة​

لكل عملية تقبل المفتاح (تذكر صفحتها في مرجع الواجهة البرمجية Optional أو Required):

  1. الطلب الأول: تحجز البوابة المفتاح لمؤسستك، وتمرّر الطلب، وتحفظ الرد 24 ساعة.
  2. المفتاح نفسه والجسم نفسه: تتلقى الرد المحفوظ مع Idempotency-Replayed: true. لا يُنفَّذ شيء مجددًا.
  3. المفتاح نفسه بجسم مختلف: 409 بالرمز idempotency.body_mismatch.
  4. المفتاح نفسه والطلب الأول ما زال قيد التنفيذ: 409 بالرمز idempotency.in_flight. انتظر وأعد المحاولة.
  5. فشل الطلب الأول بـ 5xx: يُحرَّر المفتاح، فتُنفَّذ إعادة المحاولة به من جديد.

المفاتيح لكل مؤسسة: يمكن لمؤسستين استخدام السلسلة نفسها. الرد الأكبر من 1 MiB لا يُحفظ: يبقى المفتاح مستخدمًا 24 ساعة وتتلقى إعادة المحاولة به idempotency.in_flight، فاستخدم مفتاحًا جديدًا لتشغيل مثل هذا الطلب مجددًا. والحجز الذي لا يصل ردّه الأول أبدًا (فقدت البوابة الطلب) ينتهي بعد 5 دقائق.

حيث يُشترط المفتاح​

POST /v1/commands (إرسال أمر إلى جهاز) يرفض الطلب دونه: 400 بالرمز idempotency.required. وفي غيرها المفتاح اختياري، ويُستحسن في كل عملية إنشاء وكل إجراء.

إن تعذّر الوصول إلى مخزن منع التكرار ترفض البوابة عملية الكتابة (503، idempotency.unavailable) بدل المخاطرة بتنفيذها مرتين.