التعامل مع الاستعلام الدوري عن مهام CAPTCHA وانتهاء المهلات

يتحكم waitMs في مدة انتظار طلب API لنتيجة قبل الاستجابة. وهو معامل استعلام في URL، وليس حقلاً في JSON المهمة. تختلف إعدادات الانتظار الافتراضية عند الإنشاء حسب المنتج؛ ولاستطلاع GET حد خاص به.

امنح عميل HTTP وقتًا كافيًا لانتظار الخادم المطلوب مع وقت إضافي لاتصالات الشبكة. قد تؤدي مهلة عميل أقصر من انتظار الخادم إلى قطع الاستجابة قبل أن تتلقى الحالة الحالية للمهمة.

تنشئ الدالة solve في حزم SDK الرسمية المهمة مرة واحدة وتستطلع حتى تحصل على نتيجة جاهزة أو خطأ. تتيح Python الخيارين timeout وpoll_interval بالثواني؛ وتتيح Node.js الخيارين timeoutMs وpollIntervalMs بالمللي ثانية. تستخدم الإعدادات الموثقة مهلة نهائية للحل مدتها ثلاث دقائق وفاصل استطلاع مدته ثانية واحدة.

للتحكم المباشر، توفر Python الدالتين create_task وget_task؛ وتوفر Node.js الدالتين createTask وgetTask. اتبع هذا التسلسل:

1. 1.

   حدد مهلة نهائية وأنشئ مهمة واحدة

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

2. 2.

   احفظ معرّف المهمة المُعاد وافحص حالتها

   قد يعيد الإنشاء نتيجة نهائية بالفعل. أعد الحل عند الحالة ready. عند الحالة failed، افحص errorCode وerror وتوقف؛ تُرد تكلفة عمليات الحل الفاشلة. وحدهما pending وsolving تتطلبان مزيدًا من الاستطلاع.

3. 3.

   استرجع المهمة نفسها ما دام الوقت متاحًا

   استخدم GET /v1/tasks/:id، مع انتظار استطلاع طويل اختياري يصل إلى 15000 مللي ثانية. تعامل مع استجابات HTTP غير الناجحة قبل قراءة حمولة النجاح. إذا ظلت الاستجابة تشير إلى pending أو solving، فكرر الطلب بالمعرّف نفسه، لا بإنشاء مهمة أخرى.

4. 4.

   توقف عند انقضاء المهلة النهائية

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

يسترجع هذا الطلب مهمة موجودة، مع السماح بانتظار الخادم لمدة 15 ثانية ومهلة عميل مدتها 30 ثانية. اضبط TASK_ID على المعرّف المحفوظ واحتفظ بـ SOLVETHREE_API_KEY على الخادم. لا تمثل أي من المهلتين مهلة نهائية إجمالية لحلقة استطلاع متكررة.

curl --fail-with-body --max-time 30 \
  "https://api.solvethree.com/v1/tasks/$TASK_ID?waitMs=15000" \
  -H "Authorization: Bearer $SOLVETHREE_API_KEY"

قد تحتوي استجابة HTTP ناجحة على مهمة لا تزال تحتاج إلى الاستطلاع. الحالتان pending وsolving غير نهائيتين؛ وحدها ready تحتوي على حل قابل للاستخدام. أما failed فهي نهائية وتتضمن errorCode وerror.

{
  "nonterminal": [
    {
      "id": "example-task",
      "status": "pending"
    },
    {
      "id": "example-task",
      "status": "solving"
    }
  ],
  "ready": {
    "id": "example-task",
    "status": "ready",
    "solution": {
      "token": "EXAMPLE_TOKEN",
      "userAgent": "EXAMPLE_USER_AGENT",
      "secChUa": "EXAMPLE_CLIENT_HINTS"
    }
  },
  "failed": {
    "id": "example-task",
    "status": "failed",
    "errorCode": "site-unreachable",
    "error": "target page did not respond"
  }
}

تحتوي استجابة ready المعروضة هنا على رمز reCAPTCHA. تعيد Kasada ترويسات، بينما تعيد TMPT قيمة ملف تعريف ارتباط خامًا بدلاً من ذلك. تعني النتيجة الجاهزة أنه تم إنشاء حل، لا أن الوجهة اللاحقة قبلته. إذا رُفض رمز reCAPTCHA جاهز، فانتقل من تشخيص الاستطلاع إلى التحقق من الرمز المُرسل.

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

1. 1.

   إذا كان لديك معرّف مهمة، فاستأنف استطلاع GET

   استرجع ذلك المعرّف بمهلة نهائية محلية جديدة ومحدودة. انتهاء مهلة GET ليس سببًا لإرسال طلب إنشاء آخر.

2. 2.

   إذا انقطع الإنشاء، فأعد استخدام requestId الخاص به

   أعد إرسال طلب المهمة المطابق تمامًا باستخدام requestId نفسه لاسترداد المهمة الموجودة. يؤدي تغيير مدخلات المهمة مع إعادة استخدام ذلك المعرّف إلى تعارض. راجع الاسترداد باستخدام معرّف الطلب للاطلاع على القواعد الكاملة.

تُنشئ كلتا حزمتَي SDK قيمة requestId عند إغفالها، ولا تعيدان محاولة الإنشاء تلقائيًا مطلقًا. يتيح الخطأ SolvethreeError فيهما معرّفات الاسترداد: request_id وtask_id في Python، أو requestId وtaskId في JavaScript. تحقق من هذه الحقول قبل اتخاذ قرار بإنشاء مهمة منطقية جديدة.

يعيد طلب الاستطلاع خطأ HTTP

افحص حالة HTTP بشكل منفصل عن حالة المهمة. يتيح ApiError في SDK تلك الحالة وأي مدة انتظار قبل إعادة المحاولة.

جرّب هذا: عند حدوث حالات فشل مؤقتة في الاستطلاع، التزم بـ Retry-After ضمن المهلة النهائية الإجمالية للحل. حقلا SDK هما retry_after بالثواني في Python وretryAfterMs بالمللي ثانية في JavaScript.

تعيد المهمة الحالة failed

اقرأ errorCode وerror؛ وتمثل SDK ذلك بالخطأ TaskFailedError.

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

يعيد الاسترجاع HTTP 410

انتهت صلاحية النتيجة المخزنة.

جرّب هذا: توقف عن إعادة محاولة الاسترجاع كما لو كان هذا خطأ استطلاع مؤقتًا. تُحفظ النتائج المكتملة لمدة محدودة، ولا تمثل ذاكرة تخزين مؤقت دائمة للحلول.

لا يؤدي حفظ استجابة جاهزة إلى تمديد صلاحية الرمز أو ملف تعريف الارتباط لدى الموقع المستهدف.