Utiliser solvethree dans une vue Django

1. 1.

   Installez le SDK dans l’environnement Django

   Le SDK officiel nécessite Python 3.10+. Dans l’environnement qui exécute Django, utilisez python -m pip install https://solvethree.com/downloads/solvethree_sdk-0.1.0-py3-none-any.whl.

2. 2.

   Définir les variables d’environnement du serveur

   Définissez SOLVETHREE_API_KEY sur la clé API de votre espace de travail, CAPTCHA_SITE sur le nom d’hôte cible, et non une URL complète, et SOLVETHREE_PROXY sur le proxy utilisé pour la résolution et l’envoi ultérieur à la cible. Conservez la clé API et les identifiants du proxy sur le serveur.

3. 3.

   Activez le profil du site

   Configurez dans la console un profil actif pour ce nom d’hôte, accessible à votre espace de travail. L’envoi d’un nom d’hôte et d’une action ne crée pas de profil. Consultez la configuration du profil de site.

L’exemple fixe l’action à login et n’accepte aucun paramètre de cible de l’appelant. Modifiez cette action si votre cible configurée en exige une autre. La requête utilise le mode par défaut enterprise-v3 ; elle nécessite site, action et exactement un des champs proxy ou proxyCandidates, et non type ou 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 utilise wait_ms=0 et renvoie donc la tâche sans attendre la fin de la résolution. Son appel HTTP a un délai d’expiration de 20 secondes. La vue de récupération peut attendre jusqu’à 15 secondes une mise à jour de la tâche, avec un délai d’expiration HTTP de 25 secondes. Il s’agit d’appels synchrones au SDK : la requête de récupération occupe toujours son worker Django pendant l’attente.

login_required restreint l’accès aux utilisateurs connectés ; les décorateurs de méthode autorisent POST pour la création et GET pour la récupération. Conservez la protection CSRF habituelle de Django et incluez son jeton CSRF lors de l’envoi POST. N’ajoutez pas csrf_exempt.

1. 1.

   Mettez à jour l’URLconf existante

   Importez path depuis django.urls, puis create_captcha et get_captcha depuis le module de vues de votre application. Ajoutez les deux entrées de route présentées en bas de l’exemple à la liste urlpatterns existante. Si vous utilisez une URLconf d’application, assurez-vous que l’URLconf du projet l’inclut.

2. 2.

   Démarrez le serveur de développement

   Avec les variables d’environnement accessibles au processus, exécutez python manage.py runserver depuis le répertoire contenant manage.py. Utilisez le parcours de connexion existant de votre projet avant d’appeler les points de terminaison.

3. 3.

   Utilisez les chemins enregistrés

   Sans préfixe d’URL englobant, la création se fait par POST /captcha/tasks et la récupération par GET /captcha/tasks/<task_id>. Les routes fournies n’ont pas de barre oblique finale. Incluez tout préfixe introduit par l’URLconf de votre projet.

1. 1.

   Enregistrez un identifiant avant d’envoyer le POST

   Choisissez un nouveau X-Request-ID pour chaque tâche logique et conservez-le jusqu’à ce que l’issue de la création soit connue. Utilisez 1–64 lettres ASCII, chiffres, traits de soulignement ou traits d’union. La vue transmet cet en-tête comme requestId de la tâche.

2. 2.

   Vérifiez la réussite HTTP avant le statut de la tâche

   L’exemple renvoie HTTP 400 pour les erreurs de validation des entrées interceptées et 502 pour les erreurs du SDK interceptées. Une réponse réussie contient les données de la tâche ; lisez ses champs id et status. Une réussite HTTP signifie que la requête a réussi, pas qu’un jeton est prêt.

3. 3.

   Récupérez la tâche jusqu’à sa fin

   Appelez le point de terminaison GET avec l’identifiant de tâche renvoyé. Continuez pour pending ou solving. Pour ready, utilisez la solution. Pour failed, arrêtez les interrogations et examinez errorCode et error ; les résolutions échouées sont remboursées. Corrigez les entrées invalides plutôt que de les réessayer sans modification.

4. 4.

   Récupérez une tâche dont la création est incertaine

   Si le POST expire ou renvoie une erreur du SDK, ne créez pas immédiatement une autre tâche avec un nouvel identifiant. Récupérez la tâche existante si son identifiant est connu. Sinon, répétez le POST avec le X-Request-ID d’origine et les mêmes paramètres de tâche pour la récupérer. Réutiliser cet identifiant avec des paramètres différents provoque un conflit, y compris en cas de modification du nom d’hôte, de l’action ou du proxy configurés.

La réponse d’erreur du SDK inclut les champs requestId et taskId de l’exception pour faciliter le diagnostic. Conservez séparément le X-Request-ID d’origine de l’appelant afin que la récupération ne dépende pas de la réception de cette réponse. Consultez les erreurs de l’API CAPTCHA pour la gestion des échecs.

Seule une tâche ready contient une solution utilisable. La valeur à envoyer à la cible prévue est solution.token, et non l’identifiant de tâche. Utilisez l’identité du navigateur renvoyée dans solution.userAgent et solution.secChUa, avec le proxy d’origine configuré dans SOLVETHREE_PROXY.

Ces vues n’envoient rien à la cible. Votre code d’envoi doit conserver ce proxy et appliquer l’identité renvoyée ; renvoyer le jeton à une session de navigateur sans lien ne le fait pas automatiquement. Conservez les identifiants du proxy côté serveur et n’associez pas la solution à une autre URL cible ou à une autre identité de navigateur.