استعادة طلب انتهت مهلته دون الدفع مقابل مهمة أخرى

يحدّد requestId مهمة منطقية واحدة عبر محاولات الإنشاء. ويقبل من 1 إلى 64 حرفاً من حروف ASCII أو الأرقام أو الشرطات السفلية أو الشرطات. اختره قبل إرسال الطلب واحتفظ به مع مدخلات المهمة الأصلية.

1. 1.

   احفظ جسم طلب المهمة

   ضع الطلب كاملاً، بما فيه requestId، في request.json. بالنسبة إلى reCAPTCHA Enterprise، أدرج site كاسم مضيف، وaction، وواحداً فقط من proxy أو proxyCandidates. لا تضف type أو url. أبقِ الملف خاصاً لأنه يحتوي على بيانات اعتماد الوكيل.

2. 2.

   أرسل الملف المحفوظ

   شغّل الأمر أدناه باستخدام مفتاح API لمساحة عملك. احتفظ بالمفتاح على الخادم.

3. 3.

   إذا انتهت مهلة الاتصال، فكرّر الأمر

   استخدم الأمر نفسه وملف request.json دون تغيير. لا تُنشئ requestId آخر ولا تعدّل مدخلات المهمة لمجرد عدم وصول الاستجابة.

# request.json contains one valid task body and a saved requestId.
# Keep the file private: it contains your proxy credentials.
curl --fail-with-body --max-time 30 \
  'https://api.solvethree.com/v1/tasks?waitMs=0' \
  -H "Authorization: Bearer $SOLVETHREE_API_KEY" \
  -H 'Content-Type: application/json' --data-binary @request.json

# If the connection broke, run the identical command with the identical file.
# New task: HTTP 201. Same requestId + same inputs: HTTP 200, existing task.
# Same requestId + changed inputs: HTTP 409.

تعني HTTP 201 إنشاء مهمة جديدة. وتعني HTTP 200 أن الطلب المطابق استعاد المهمة الموجودة. اقرأ معرّف المهمة وحالتها المُعادين في كلتا الحالتين؛ فلا تعني أيٌّ من حالتي HTTP وحدها أن الحل جاهز.

كمثال عملي على تغيير المدخلات، افترض أن قيمة action في الطلب المحفوظ هي login. يؤدي تغييرها إلى checkout مع الإبقاء على requestId نفسه إلى إرجاع HTTP 409، أي تعارض في معرّف الطلب. لاستعادة المهمة الأصلية، استعد الملف الأصلي وأعد إرساله. وإذا كنت تحتاج عمداً إلى المدخلات المعدّلة، فامنح تلك المهمة المنطقية الجديدة requestId جديداً.

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

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

• JavaScript: يوفّر SolvethreeError الحقلين requestId وtaskId.
• Python: يوفّر SolvethreeError الحقلين request_id وtask_id.

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

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

اجلب المهمة المستعادة باستخدام GET /v1/tasks/:id. واصل الاستقصاء ما دامت حالتها pending أو solving. وحدها ready تحتوي على حل قابل للاستخدام.

إذا كانت الحالة failed، فتوقّف عن الاستقصاء وافحص errorCode وerror. تُردّ رسوم عمليات الحل الفاشلة. وهذا يختلف عن رفض موقع ويب لحل مُولّد: تعني ready أن الحل متاح، لا أن الموقع المستهدف قبله.

قد تُرجع النتائج المكتملة HTTP 410 بعد انتهاء مدة الاحتفاظ، لذا فالاستعادة ليست وسيلة لتخزين النتائج بشكل دائم. للاطّلاع على حلقة الاستقصاء نفسها، راجع استقصاء المهام والمهل الزمنية.