Product3 دقيقة قراءة

Idempotency-Key: إعادات محاولة آمنة لمهام PDF

أرسل Idempotency-Key في طلبات POST تحت /api/v1/. يخزّن PDF123 الردود الناجحة 24 ساعة في ذاكرة العملية ويعيد Idempotency-Replayed: true بدل تكرارها.

By the PDF123 team · Updated 2026-09-30
Idempotency-Key: إعادات محاولة آمنة لمهام PDF

تعدّ مهلات الشبكة وإعادات محاولة العملاء أمراً عادياً في رفوعات PDF متعددة الأجزاء. وبلا مفتاح idempotency يشغّل طلب POST ثانٍ عملية الدمج أو OCR أو الضغط نفسها من الصفر، فيكرّر الرفع ووقت المعالجة. أما مع Idempotency-Key فيستطيع PDF123 إعادة أول رد ناجح بدلاً من ذلك.

ما تفعله البرمجية الوسيطة

تعمل البرمجية الوسيطة في pdfx-server على الاستدعاءات المُعدِّلة وحدها: طلبات POST إلى المسارات تحت /api/v1/ بما في ذلك /api/v1/pipeline. أما GET وبقية الأساليب فتمرّ كما هي. وإن لم يحمل الطلب ترويسة Idempotency-Key أو كانت فارغة بعد التشذيب، جرت العملية عادةً بلا بحث في ذاكرة مؤقتة.

وعند وجود الترويسة:

  1. تفتح الذاكرة المدخل بالمفتاح principal + key، حيث يُشتق principal من X-API-KEY بصيغة key:… وإلا من Authorization بصيغة auth:… وإلا فالقيمة الحرفية anon. وتُجزَّأ القيمتان بـ SHA-256 إلى مفتاح الخريطة. أما جسم الطلب فليس جزءاً من المفتاح.
  2. وعند إصابة في الذاكرة خلال 24 ساعة، تعيد البرمجية الوسيطة الحالة المخزّنة ونوع المحتوى وترتيب المحتوى والجسم، وتضبط الترويسة Idempotency-Replayed: true على الرد.
  3. وعند غياب الإصابة يمضي الطلب. وتُخزَّن الردود الناجحة وحدها في المخزن المؤقت، أما الردود غير الناجحة فلا تُخزَّن للإعادة.
  4. وتُخزَّن أجسام الردود في المخزن المؤقت حتى 100 MiB كي تستطيع الإعادة إرسال بايتات الملف. والجسم الذي يتعذّر تخزينه لا يتخطّى الذاكرة صامتاً: بل يُرجع ذلك الطلب HTTP 500، فيفشل الرد الذي يتجاوز الحد بدل أن يمرّ بلا تخزين.

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

كيف ترسله

اختر سلسلة غامضة مستقرة لكل مهمة منطقية، وUUID مناسب لذلك:

curl -X POST "https://pdf123.xyz/api/v1/misc/compress-pdf" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -F "[email protected]"

ويعمل المستدعون المجهولون وأصحاب مفاتيح API على السواء. أما خطوط المعالجة التي تسلسل العلامة المائية ثم الضغط فينبغي أن ترسل مفتاحاً واحداً لكل طلب HTTP تريد إزالته المكرّرة، بما في ذلك كل خطوة إن أرسلتها منفصلة، أو مفتاحاً واحداً لاستدعاء /api/v1/pipeline واحد.

ولا تحتاج المهام الفردية في المتصفح على صفحات الأدوات (الضغط وOCR وما إليهما) إلى اختراع مفتاح؛ فالترويسة تهمّ العملاء الذين يعيدون المحاولة. وتعرض المهارة المنشورة عند /skills/pdf123.md مفتاح Idempotency-Key في مثال خط معالجة للسبب نفسه.

أنماط عملاء ناجحة

  • ولّد المفتاح قبل أول طلب POST، وأعد استخدامه في محاولات المهلة لتلك المهمة المنطقية نفسها.
  • عند النجاح، افحص وجود الترويسة Idempotency-Replayed: true إن احتجت معرفة ما إذا جاء هذا الرد من الذاكرة أم شغّل العملية من جديد.
  • غيّر المفتاح عند تغيّر الملف أو العملية أو المعاملات، حتى لو بقي principal كما هو.
  • ولـ /api/v1/pipeline يغطي مفتاح واحد طلب خط المعالجة كله لا كل خطوة داخلية.

ما ليست عليه الإعادة

الإعادة ليست طابور مهام متيناً. فالمخزن محلي للعملية (HashMap خلف قفل) بصلاحية 24 ساعة. وبعد انتهاء الصلاحية، أو بعد إعادة تشغيل عملية تُسقط الخريطة من الذاكرة، يشغّل المفتاح نفسه العملية من جديد. ولا تتشارك عمليات النشر متعددة النسخ تلك الخريطة إن لم تضع مخزناً مشتركاً في المقدمة؛ فالبرمجية الوسيطة اليوم لكل عملية.

وتعامل مع الترويسة Idempotency-Replayed: true كدليل على أن هذا الرد جاء من الذاكرة، لا كسجل دائم. فهي لا تعني أن ملف PDF أُعيدت معالجته، ولا تمدّد الصلاحية.

ولمزيد من تفاصيل السطح: المطوّرون ومبنيّ للوكلاء. وتبقى صفحات الأدوات مثل الضغط متاحة لمهام المتصفح الفردية بلا اختراع مفاتيح.

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool