استخدام solvethree في دالة عرض Django

1. 1.

   ثبّت في بيئة Django

   تتطلب SDK الرسمية Python 3.10+. في البيئة التي تشغّل Django، استخدم python -m pip install https://solvethree.com/downloads/solvethree_sdk-0.1.0-py3-none-any.whl.

2. 2.

   ضبط متغيرات بيئة الخادم

   اضبط SOLVETHREE_API_KEY على مفتاح API لمساحة عملك، وCAPTCHA_SITE على اسم مضيف الوجهة، وليس عنوان URL كاملاً، وSOLVETHREE_PROXY على الوكيل المستخدم للحل والإرسال اللاحق إلى الوجهة. احتفظ بمفتاح API وبيانات اعتماد الوكيل على الخادم.

3. 3.

   فعّل ملف تعريف الموقع

   اضبط في لوحة التحكم ملف تعريف نشطاً لاسم المضيف هذا، ومتاحاً لمساحة عملك. إرسال اسم مضيف وإجراء لا ينشئ ملف تعريف. راجع إعداد ملف تعريف الموقع.

يثبّت المثال الإجراء على login ولا يأخذ أي إعدادات للوجهة من الجهة المستدعية. غيّر هذا الإجراء إذا كانت الوجهة المضبوطة تتطلب إجراءً آخر. يستخدم الطلب الوضع الافتراضي enterprise-v3؛ ويحتاج إلى site وaction وواحد فقط من proxy أو proxyCandidates، وليس type أو url.

# views.py in an existing Django project with authentication/CSRF configured.
import os
from django.contrib.auth.decorators import login_required
from django.http import JsonResponse
from django.views.decorators.http import require_GET, require_POST
from solvethree import Solvethree, SolvethreeError

def client():
    return Solvethree(os.environ["SOLVETHREE_API_KEY"])

@login_required
@require_POST
def create_captcha(request):
    task = {"site": os.environ["CAPTCHA_SITE"], "action": "login", "proxy": os.environ["SOLVETHREE_PROXY"]}
    if request.headers.get("X-Request-ID"):
        task["requestId"] = request.headers["X-Request-ID"]
    try:
        return JsonResponse(client().create_task(task, wait_ms=0, timeout=20))
    except ValueError:
        return JsonResponse({"error": "Invalid task input"}, status=400)
    except SolvethreeError as error:
        return JsonResponse({"requestId": error.request_id, "taskId": error.task_id}, status=502)

@login_required
@require_GET
def get_captcha(request, task_id):
    try:
        return JsonResponse(client().get_task(task_id, wait_ms=15000, timeout=25))
    except ValueError:
        return JsonResponse({"error": "Invalid task ID"}, status=400)
    except SolvethreeError as error:
        return JsonResponse({"requestId": error.request_id, "taskId": error.task_id}, status=502)

# urls.py: import these views and add to urlpatterns:
# path("captcha/tasks", create_captcha),
# path("captcha/tasks/<str:task_id>", get_captcha),

تستخدم create_task القيمة wait_ms=0، لذا تعيد المهمة دون انتظار اكتمال الحل. مهلة استدعاء HTTP الخاص بها هي 20 ثانية. ويمكن لدالة عرض الاسترجاع انتظار تحديث المهمة لمدة تصل إلى 15 ثانية، مع مهلة HTTP قدرها 25 ثانية. هذه استدعاءات SDK متزامنة: يظل طلب الاسترجاع يشغل عامل Django الخاص به أثناء الانتظار.

يقصر login_required الوصول على المستخدمين الذين سجّلوا الدخول؛ وتسمح مُزيّنات الطرق باستخدام POST للإنشاء وGET للاسترجاع. أبقِ حماية CSRF المعتادة في Django وأرفق رمز CSRF الخاص بها عند إرسال POST. لا تضف csrf_exempt.

1. 1.

   حدّث URLconf الحالي

   استورد path من django.urls، واستورد create_captcha وget_captcha من وحدة دوال العرض في تطبيقك. أضف إدخالَي المسار الظاهرين أسفل المثال إلى urlpatterns الحالية. إذا كنت تستخدم URLconf خاصاً بالتطبيق، فتأكد من تضمينه في URLconf الخاص بالمشروع.

2. 2.

   شغّل خادم التطوير

   مع إتاحة متغيرات البيئة للعملية، شغّل python manage.py runserver من المجلد الذي يحتوي على manage.py. استخدم تدفق تسجيل الدخول الحالي في مشروعك قبل استدعاء نقاط النهاية.

3. 3.

   استخدم المسارات المسجّلة

   من دون بادئة URL حاوية، يكون الإنشاء عبر POST إلى /captcha/tasks والاسترجاع عبر GET إلى /captcha/tasks/<task_id>. لا تنتهي المسارات المقدَّمة بشرطة مائلة. أدرج أي بادئة يضيفها URLconf الخاص بمشروعك.

1. 1.

   احفظ معرّفاً قبل إرسال POST

   اختر X-Request-ID جديداً لكل مهمة منطقية واحتفظ به حتى تُحسم نتيجة الإنشاء. استخدم 1–64 حرفاً أو رقماً من ASCII أو شرطة سفلية أو واصلة. تمرّر دالة العرض هذه الترويسة بوصفها requestId للمهمة.

2. 2.

   تحقق من نجاح HTTP قبل حالة المهمة

   يعيد المثال HTTP 400 لأخطاء التحقق من صحة المدخلات التي يتم التقاطها، و502 لأخطاء SDK التي يتم التقاطها. تحتوي الاستجابة الناجحة على حمولة المهمة؛ اقرأ id وstatus منها. يعني نجاح HTTP أن الطلب نجح، لا أن الرمز جاهز.

3. 3.

   واصل الاسترجاع حتى تنتهي المهمة

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

4. 4.

   استعد مهمة لم تتأكد من إنشائها

   إذا انتهت مهلة POST أو أعاد خطأ SDK، فلا تنشئ فوراً مهمة أخرى بمعرّف جديد. استرجع المهمة الحالية إذا كان معرّفها معروفاً. وإلا، فكرّر POST باستخدام X-Request-ID الأصلي ومدخلات المهمة دون تغيير لاستعادتها. تؤدي إعادة استخدام هذا المعرّف مع مدخلات مختلفة إلى تعارض، بما في ذلك تغيير اسم المضيف المضبوط أو الإجراء أو الوكيل.

تتضمن استجابة خطأ SDK القيمتين requestId وtaskId من الاستثناء لأغراض التشخيص. احتفظ بقيمة X-Request-ID الأصلية الخاصة بالجهة المستدعية على نحو منفصل، كي لا تعتمد الاستعادة على تلقّي تلك الاستجابة. راجع أخطاء CAPTCHA API لمعالجة حالات الفشل.

لا تحتوي على حل قابل للاستخدام إلا مهمة ready. القيمة التي يجب إرسالها إلى الوجهة المقصودة هي solution.token، وليست معرّف المهمة. استخدم هوية المتصفح المُعادة في solution.userAgent وsolution.secChUa، مع الوكيل الأصلي المضبوط في SOLVETHREE_PROXY.

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