Djangoビューでsolvethreeを使用する

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を許可します。Djangoの通常のCSRF保護を維持し、POST時にはCSRFトークンを含めてください。csrf_exemptは追加しないでください。

1. 1.

   既存のURLconfを更新する

   django.urlsからpathを、アプリのviewsモジュールからcreate_captchaとget_captchaをインポートしてください。例の末尾に示す2つのルートエントリを既存のurlpatternsに追加します。アプリのURLconfを使用する場合は、プロジェクトのURLconfに含まれていることを確認してください。

2. 2.

   開発サーバーを起動する

   プロセスが環境変数を利用できる状態で、manage.pyを含むディレクトリからpython manage.py runserverを実行してください。エンドポイントを呼び出す前に、プロジェクトの既存のログインフローでログインしてください。

3. 3.

   登録したパスを使用する

   上位のURLプレフィックスがなければ、作成はPOST /captcha/tasks、取得はGET /captcha/tasks/<task_id>です。付属のルートに末尾のスラッシュはありません。プロジェクトのURLconfで追加したプレフィックスがあれば含めてください。

1. 1.

   POSTを送信する前にIDを保存する

   論理タスクごとに新しいX-Request-IDを選び、作成結果が確定するまで保持してください。1–64文字のASCII英字、数字、アンダースコア、ハイフンを使用します。ビューはこのヘッダーをタスクのrequestIdとして転送します。

2. 2.

   タスクのステータスより先にHTTPの成功を確認する

   このサンプルでは、入力検証エラーを捕捉するとHTTP 400、SDKエラーを捕捉すると502を返します。成功応答にはタスクのペイロードが含まれるため、そのidとstatusを読み取ってください。HTTPの成功はリクエストが成功したことを意味し、トークンの準備完了を意味するものではありません。

3. 3.

   タスクが完了するまで取得を続ける

   返されたタスクIDを使ってGETエンドポイントを呼び出してください。pendingまたはsolvingの間は取得を続けます。readyになったら解決結果を使用します。failedになったらポーリングを停止し、errorCodeとerrorを確認してください。解決に失敗した場合は返金されます。不正な入力はそのまま再試行せず、修正してください。

4. 4.

   作成結果が不明なタスクを復旧する

   POSTがタイムアウトするかSDKエラーを返しても、すぐに新しいIDで別のタスクを作成しないでください。既存のタスクIDがわかる場合は、そのタスクを取得します。わからない場合は、元のX-Request-IDと変更していないタスク入力でPOSTを再送し、復旧してください。設定済みのホスト名、アクション、プロキシの変更も含め、異なる入力でそのIDを再利用すると競合します。

SDKエラー応答には、診断用に例外のrequestIdとtaskIdが含まれます。その応答を受信できなくても復旧できるよう、呼び出し元の元のX-Request-IDを別途保持してください。失敗時の処理については、CAPTCHA APIエラーを参照してください。

使用可能な解決結果が含まれるのは、readyのタスクだけです。対象の送信先に送る値はタスクIDではなくsolution.tokenです。返されたsolution.userAgentとsolution.secChUaのブラウザー識別情報を、SOLVETHREE_PROXYに設定した元のプロキシとともに使用してください。

これらのビューは対象への送信を行いません。送信コードでそのプロキシを保持し、返された識別情報を適用する必要があります。無関係なブラウザーセッションにトークンを返しても、これが自動で行われるわけではありません。プロキシの認証情報はサーバー側で保持し、解決結果を別の対象URLやブラウザー識別情報と組み合わせないでください。