שימוש ב-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 שניות לעדכון משימה, עם זמן קצוב של 25 שניות ל-HTTP. אלה קריאות 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 של יעד אחר או עם זהות דפדפן אחרת.