استدعاء solvethree من واجهة خلفية تستخدم Flask

1. 1.

   استخدم Python 3.10 أو إصدارًا أحدث

   ثبّت Flask باستخدام python -m pip install flask. وثبّت SDK الرسمي لـ Python باستخدام python -m pip install https://solvethree.com/downloads/solvethree_sdk-0.1.0-py3-none-any.whl.

2. 2.

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

   اضبط SOLVETHREE_API_KEY على مفتاح API لمساحة عملك، وINTEGRATION_KEY على السر الذي سيرسله المستدعي المصرّح له في X-Integration-Key. اضبط CAPTCHA_SITE على اسم المضيف المستهدف، وليس عنوان URL كاملًا، وSOLVETHREE_PROXY على عنوان URL لوكيل HTTP أو HTTPS المستخدم لهذه المهمة. احتفظ بهذه القيم على الخادم.

3. 3.

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

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

يثبّت المثال الإجراء على login ويستخدم مهمة reCAPTCHA Enterprise v3 الافتراضية. غيّر ذلك الإجراء ليتوافق مع العملية المستهدفة قبل تشغيله. لا يمكن للمستدعي تجاوز الموقع أو الإجراء أو الوكيل عبر متن الطلب.

# pip install flask and the official solvethree SDK wheel.
import hmac
import os
from flask import Flask, abort, jsonify, request
from solvethree import Solvethree, SolvethreeError

app = Flask(__name__)

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

@app.before_request
def authorize():
    if not hmac.compare_digest(request.headers.get("x-integration-key", ""), os.environ["INTEGRATION_KEY"]):
        abort(401)

@app.errorhandler(SolvethreeError)
def task_error(error):
    return jsonify(requestId=error.request_id, taskId=error.task_id), 502

@app.errorhandler(ValueError)
def invalid_input(error):
    return jsonify(error="Invalid task input or ID"), 400

@app.post("/captcha/tasks")
def create():
    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"]
    return jsonify(client().create_task(task, wait_ms=0, timeout=20))

@app.get("/captcha/tasks/<task_id>")
def retrieve(task_id):
    return jsonify(client().get_task(task_id, wait_ms=15000, timeout=25))

احفظ المثال باسم app.py. بعد ضبط متغيرات البيئة، شغّله محليًا باستخدام python -m flask --app app run. المساران هما POST /captcha/tasks وGET /captcha/tasks/<task_id>. لا يحتاج Flask إلى URLconf منفصل: تسجّل المزخرفات كلا المسارين. راجع دليل البدء السريع لـ Flask لتفاصيل التشغيل المحلي؛ واحتفظ بإعدادات WSGI الحالية لبيئة الإنتاج.

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

1. 1.

   أنشئ معرّف طلب واحداً لكل مهمة منطقية

   احفظه قبل استدعاء POST /captcha/tasks، ثم أرسله في X-Request-ID إلى جانب X-Integration-Key. استخدم 1–64 حرفاً أو رقماً من ASCII أو شرطة سفلية أو واصلة. لا يحتاج طلب POST هذا إلى جسم للمهمة، لأن الخادم ينشئ المهمة من إعداداته الثابتة.

2. 2.

   الاحتفاظ بمعرّف المهمة المُرجع

   بعد استجابة HTTP ناجحة، احفظ id من النتيجة. استرجع المهمة عبر GET /captcha/tasks/<task_id>، مع إرسال X-Integration-Key مجدداً.

3. 3.

   استعد مهمة لم تتأكد من إنشائها بدلاً من إنشاء مهمة أخرى

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

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

تحقق أولاً من حالة HTTP في استجابة Flask. يعيد المثال 401 عند غياب مفتاح التكامل أو عدم صحته، و400 عند التقاط ValueError، و502 عند التقاط SolvethreeError. يتيح جسم استجابة 502 هذا requestId وtaskId للاستعادة؛ وهو ليس حمولة حالة مهمة، ولا يعني بمفرده أن المهمة فشلت.

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

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

احتفظ بالرمز والوكيل وهوية المتصفح والوجهة المقصودة معاً. تعني المهمة الجاهزة أن solvethree أنشأ حلاً؛ أما القبول فتحدده استجابة الوجهة لطلب التطبيق اللاحق.