CAPTCHAタスクのポーリングとタイムアウトに対処する

waitMsは、APIリクエストが応答する前に結果を待つ時間を制御します。これはURLクエリパラメーターであり、タスクJSONのフィールドではありません。作成時のデフォルト値は製品ごとに異なり、GETによるポーリングには別の上限があります。

HTTPクライアントには、要求したサーバー待機時間にネットワークのオーバーヘッドを加えた十分な時間を設定してください。クライアントのタイムアウトがサーバーの待機時間より短いと、タスクの現在の状態を受信する前にレスポンスが中断される可能性があります。

公式SDKのsolveメソッドは1回だけ作成を行い、準備完了の結果またはエラーが得られるまでポーリングします。Pythonではtimeoutとpoll_intervalを秒単位で、Node.jsではtimeoutMsとpollIntervalMsをミリ秒単位で指定できます。ドキュメントの設定では、解決処理の期限を3分、ポーリング間隔を1秒にしています。

直接制御する場合、Pythonにはcreate_taskとget_task、Node.jsにはcreateTaskとgetTaskがあります。次の手順を使用してください。

1. 1.

   期限を設定し、タスクを1つ作成する

   作成前に全体の期限を決めてください。作成が中断された場合に復旧できるよう、requestIdを正確なタスク入力とともに保持してください。作成時の待機を避けるには、待機時間を明示的にゼロに設定してください。

2. 2.

   返されたタスクIDを保存し、ステータスを確認する

   作成時にすでに終端状態の結果が返される場合があります。readyの場合は解決結果を返してください。failedの場合はerrorCodeとerrorを確認し、処理を停止してください。失敗した解決処理の料金は返金されます。追加のポーリングが必要なのはpendingとsolvingだけです。

3. 3.

   時間が残っている間は同じタスクを取得する

   GET /v1/tasks/:idを使用し、必要に応じて最大15000 msのロングポーリング待機時間を指定してください。成功ペイロードを読み取る前に、成功以外のHTTPレスポンスを処理してください。レスポンスがまだpendingまたはsolvingの場合は、別のタスクを作成するのではなく、同じIDに対して繰り返してください。

4. 4.

   期限になったら停止する

   ネットワークのオーバーヘッドを考慮し、各リクエストの時間を残り時間内に制限してください。期限が切れたらローカルのループを停止し、復旧用にタスクIDを保持してください。クライアントが待機を停止しただけで、タスクを失敗扱いにしないでください。

このリクエストは既存のタスクを取得し、サーバーの待機時間を15秒、クライアントのタイムアウトを30秒に設定します。TASK_IDに保存したIDを設定し、SOLVETHREE_API_KEYはサーバー上に保持してください。どちらのタイムアウトも、繰り返し実行するポーリングループ全体の期限ではありません。

curl --fail-with-body --max-time 30 \
  "https://api.solvethree.com/v1/tasks/$TASK_ID?waitMs=15000" \
  -H "Authorization: Bearer $SOLVETHREE_API_KEY"

HTTPの成功レスポンスに、まだポーリングが必要なタスクが含まれる場合があります。pendingとsolvingは終端状態ではありません。使用可能な解決結果を含むのはreadyだけです。failedは終端状態で、errorCodeとerrorを含みます。

{
  "nonterminal": [
    {
      "id": "example-task",
      "status": "pending"
    },
    {
      "id": "example-task",
      "status": "solving"
    }
  ],
  "ready": {
    "id": "example-task",
    "status": "ready",
    "solution": {
      "token": "EXAMPLE_TOKEN",
      "userAgent": "EXAMPLE_USER_AGENT",
      "secChUa": "EXAMPLE_CLIENT_HINTS"
    }
  },
  "failed": {
    "id": "example-task",
    "status": "failed",
    "errorCode": "site-unreachable",
    "error": "target page did not respond"
  }
}

ここに示すreadyレスポンスには、reCAPTCHAトークンが含まれています。Kasadaは代わりにヘッダーを、TMPTは未加工のCookie値を返します。準備完了の結果は解決結果が生成されたことを意味し、後続の対象サイトがそれを受け入れたことを意味しません。準備完了のreCAPTCHAトークンが拒否された場合は、ポーリングの診断から送信したトークンの確認に切り替えてください。

接続のタイムアウトは、クライアントが完全なレスポンスを受信できなかったことを示します。作成が失敗した証拠ではありません。別の解決処理に料金を支払う前に、すでに作成されている可能性のあるタスクを復旧してください。

1. 1.

   タスクIDがある場合はGETによるポーリングを再開する

   新たに有限のローカル期限を設定して、そのIDのタスクを取得してください。GETのタイムアウトは、別の作成リクエストを送信する理由にはなりません。

2. 2.

   作成が中断された場合は、そのrequestIdを再利用する

   同じrequestIdで同一のタスクリクエストを再送し、既存のタスクを復旧してください。そのIDを再利用しながらタスク入力を変更すると、競合が発生します。仕様の詳細はリクエストIDによる復旧を参照してください。

どちらのSDKも、省略された場合はrequestIdを生成し、作成を自動で再試行することはありません。SolvethreeErrorから復旧用IDを取得できます。Pythonではrequest_idとtask_id、JavaScriptではrequestIdとtaskIdです。新しい論理タスクを作成すると判断する前に、これらのフィールドを確認してください。

ポーリングリクエストがHTTPエラーを返す

HTTPステータスはタスクのステータスと分けて確認してください。SDKのApiErrorから、そのステータスと再試行までの待機時間を取得できます。

試してみましょう： 一時的なポーリングの失敗では、解決処理全体の期限内でRetry-Afterに従ってください。SDKのフィールドは、Pythonでは秒単位のretry_after、JavaScriptではミリ秒単位のretryAfterMsです。

タスクがfailedを返す

errorCodeとerrorを確認してください。SDKでは、これはTaskFailedErrorとして表されます。

試してみましょう： そのタスクのポーリングを停止してください。別のタスクを作成する前に、報告された原因を診断してください。無効な入力を変更せずにむやみに再試行したり、クレジットが原因だと決めつけたりしないでください。

取得時にHTTP 410が返される

保存された結果の有効期限が切れています。

試してみましょう： 一時的なポーリングエラーと同じように取得を再試行し続けないでください。完了した結果の保持期間には限りがあり、解決結果の永続的なキャッシュではありません。

準備完了のレスポンスを保存しても、対象サイトのトークンやCookieの有効期間は延長されません。