BroadRouter
ابدأ الآن

مفتاح عدم التكرار (Idempotency key)

آخر تحديث

مفتاح عدم التكرار (idempotency key) قيمة فريدة، غالبًا معرّف عشوائي مثل UUID، يرفقها العميل بطلب يغيّر الحالة، كدفعة أو عملية شراء. فإذا أُرسل الطلب نفسه مرة أخرى بالمفتاح نفسه، أعاد الخادم النتيجة الأصلية بدل تنفيذ الإجراء مرتين.

يُسمّى أيضًا: مفتاح عدم التكرار، مفتاح منع التكرار، مفتاح التكرار الآمن، طلب آمن التكرار، idempotency key، Idempotency-Key header، idempotency token، idempotent request، idempotent retry

تتعطل الشبكات في أسوأ موضع: بعد أن ينفّذ الخادم الإجراء وقبل أن يصلك الرد. ومفتاح عدم التكرار يجعل إعادة المحاولة آمنة.

كيف يعمل

يُنشئ العميل مفتاحًا فريدًا لإجراء واحد مقصود ويرسله مع الطلب. ويحفظ الخادم المفتاح مع النتيجة. فإن وصل المفتاح نفسه مرة أخرى، أعاد الخادم النتيجة المحفوظة بدل تنفيذ الإجراء من جديد.

تعمل مجموعة IETF HTTPAPI على توحيد ذلك في ترويسة الطلب Idempotency-Key (المسودة 08، أكتوبر 2026، ولم تصبح RFC بعد). وتصف المفتاح بأنه “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request” (ترجمة: قيمة فريدة يولّدها العميل، ويستخدمها المورد للتعرّف على المحاولات اللاحقة للطلب نفسه)، وتوصي باستخدام UUID أو معرّف عشوائي مماثل. وحالات الخطأ في المسودة:

الحالة الرمز
المفتاح غائب حيث يكون مطلوبًا 400 Bad Request
الطلب الأصلي لا يزال قيد التنفيذ 409 Conflict
إعادة استخدام المفتاح مع جسم مختلف 422 Unprocessable Content

وتقول AWS Builders’ Library الشيء نفسه من جهة العميل: “APIs with side effects aren’t safe to retry unless they provide idempotency.” (ترجمة: واجهات API ذات الآثار الجانبية ليست آمنة لإعادة المحاولة ما لم توفّر عدم التكرار).

لماذا يهم

إعادة المحاولة مع التراجع الأُسّي ممارسة معتادة، وكثير من حزم SDK تعيد المحاولة تلقائيًا. ودون عدم التكرار، قد تُنشئ إعادة المحاولة بعد انتهاء المهلة طلبَي شراء أو خصمين. أما مع المفتاح فإعادة المحاولة آمنة أيًّا كان ما فعلته المحاولة الأولى. وهذا يجعله أداة أساسية للوكلاء والسكربتات التي تشتري أو تحجز أو تُنشئ أشياء دون إنسان يراقبها.

في BroadNet Inference

تستخدم BroadNet هذا النمط لشراء المفاتيح بالساعة. تقبل POST /portal/keys/hourly الحقل request_id في جسم JSON، ويقول التوثيق: “Idempotency is required for money safety” (ترجمة: عدم التكرار مطلوب لحماية المال):

curl -X POST https://inference.broadnet.ai/portal/keys/hourly \
  -H "Authorization: Bearer <portal-credential>" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"order-20260920-001","label":"kiosk-1"}'

إعادة استخدام request_id لا تُنشئ مفتاحًا آخر ولا تخصم ثمنه. وبعد انتهاء المهلة، أو انقطاع الاتصال، أو استجابة 409 mint_in_progress، أو خطأ 5xx، أعد المحاولة بالقيمة نفسها لـ request_id. ويُرجع التكرار already_issued: true والاسم المستعار للمفتاح؛ ولا يحتوي على المفتاح الخام إلا أول استجابة ناجحة. ويقول التوثيق: “Never generate a replacement id until the original result is known.” (ترجمة: لا تولّد معرّفًا بديلًا قبل أن تُعرف النتيجة الأصلية).

لا توثّق BroadNet مفتاح عدم تكرار لـ /v1/chat/completions ولا للتفريغ الصوتي. راجع رموز الأخطاء وإعادة المحاولة لمعرفة ما يُعاد هناك، وحدود المعدل لتعرف لماذا قد تزيد إعادة المحاولة العمياء خطأ 429 سوءًا.

أسئلة شائعة

متى أُنشئ مفتاح عدم تكرار جديدًا؟

فقط لإجراء جديد مقصود. أعد استخدام المفتاح نفسه في كل إعادة محاولة للإجراء الواحد، ولا تُنشئ مفتاحًا جديدًا قبل أن تعرف نتيجة المحاولة الأولى.

هل تحتاج طلبات المحادثة في نماذج LLM إلى مفتاح عدم تكرار؟

توليد النص لا يترك أثرًا دائمًا، لذا فتكرار طلب المحادثة يكلّف رموزًا مرة أخرى في الغالب لا أكثر. يهم المفتاح في الاستدعاءات التي تخصم مالًا أو تُنشئ موارد. وتوثّقه BroadNet لشراء المفاتيح بالساعة فقط، لا لطلبات المحادثة.

ماذا يحدث إن أعدت استخدام مفتاح مع جسم طلب مختلف؟

تقول مسودة IETF إن على الخادم رفضه بالرمز 422 Unprocessable Content، لأن المفتاح مرتبط أصلًا بطلب مختلف.

اقرأها بصيغة Markdownاسأل ChatGPTاسأل Claudeاسأل Perplexity