التكرار الآمن

نظرة سريعة#

العميل الذي يفقد إجابة طلب POST لا يعرف هل أُنشئ العنصر. إرسال Idempotency-Key نفسه في إعادة المحاولة يجعل الطلب الثاني يعيد الإجابة الأولى بدل إنشاء عنصر ثانٍ.

«الطلب نفسه» يعني الطريقة والمسار والمستدعي والمسار مع سلسلة الاستعلام والجسم نفسها.

ما يُخزَّن#

• ما أجابت به خدمة المزوّد فقط، بحالة من 200 إلى 499 عدا 408 و429.
• إجابة 5xx لا تُخزَّن: يعيد العميل المحاولة بالمفتاح نفسه فيُنفَّذ الطلب من جديد.
• جسم الاستجابة الأكبر من 64 KB لا يُخزَّن، وجسم الطلب الأكبر من 64 KB لا يُعالَج إطلاقاً: لا إعادة إجابة ولا 409 ولا 422. قسّم الحمولة الكبيرة بدلاً من ذلك.
• رفض البوابة نفسها، مثل حصة مستنفدة، لا يُخزَّن أبداً.
• قد تُرى 409 في إعادة محاولة تصل في الأجزاء من الثانية بين الاستجابة وتخزينها؛ ينتظر العميل ويعيد المحاولة.

أي طلبات POST#

ينشئ POST عنصراً حين يجيب بـ 201، أو حين يبدأ operationId الخاص به بـ create أو add أو register أو submit أو subscribe أو invite أو issue أو generate، أو حين يحمل x-api360-creates-resource: true. وتعني x-api360-creates-resource: false إجراءً يشبه الإنشاء ولا ينشئ. أما GET وPUT وDELETE فآمنة التكرار أصلاً ولا تحتاج مفتاحاً.

في التعريف#

وثّق الترويسة على كل POST من هذا النوع، اختيارية ومحدودة، وأعلن حالتَي التعارض:

parameters:
  - name: Idempotency-Key
    in: header
    required: false
    description: Send the same key to retry this request safely. Valid for 24 hours.
    schema: { type: string, minLength: 1, maxLength: 255 }
responses:
  "201": { description: Created. }
  "409": { $ref: "#/components/responses/Error" }
  "422": { $ref: "#/components/responses/Error" }

رموز أخطاء البوابة لهذه الحالات هي idempotency_key_conflict (409) وidempotency_key_mismatch (422) وidempotency_key_invalid (400).

واجهات نطاقات المنصة نفسها (الحسابات والفوترة والفهرس وغيرها) ليست خلف هذه الميزة في البوابة، لذلك لا تطلب القواعد من تعريفاتها توثيق الترويسة.

تتحقق منه#

القاعدتان مفعّلتان في الملف الشخصي للمزوّد ومعطّلتان في ملف المنصة.

انظر أيضاً#

• الأخطاء: غلاف 409 و422.
• الأخطاء ورموز الحالة وإعادة المحاولة: أي الأعطال يعيد العميل المحاولة عندها.