2CaptchaのreCAPTCHA連携をsolvethreeに移行する

この移行では、2Captcha API v2 を通じた reCAPTCHA v3 Enterprise を扱います。従来の in.php/res.php API は対象ではありません。また、2Captcha の API バージョンは CAPTCHA のバージョンではありません。solvethree は reCAPTCHA v2 に対応していません。

移行前のリクエストは、2Captcha createTask に記載されているエンベロープを使用し、プロバイダー固有のタスクオブジェクトの外に認証情報を配置しています。

{
  "clientKey": "TWO_CAPTCHA_API_KEY",
  "task": {
    "type": "RecaptchaV3TaskProxyless",
    "websiteURL": "https://accounts.example.com/login",
    "websiteKey": "PUBLIC_SITE_KEY",
    "minScore": 0.7,
    "pageAction": "login",
    "isEnterprise": true
  }
}

このオブジェクトを変更せずに新しい API に引き継がないでください。特に、プロキシ不要のタスクタイプと minScore は、以下の solvethree リクエストでは使用しません。

まず、solvethreeコンソールで対象サイトを設定します。そのホスト名のリクエストを解決するには、ワークスペースに有効なサイトプロファイルが必要です。ホスト名とアクションを送信するだけでは、プロファイルは作成されません。

https://api.solvethree.com の POST /v1/tasks で新しいタスクを作成します。Authorization: Bearer にワークスペースのAPIキーを指定してください。キーはサーバー側で保管します。タスク作成の仕様では、ネストされたtaskオブジェクトではなく、フラットなJSON本文を使用します。

{
  "site": "accounts.example.com",
  "action": "login",
  "proxy": "http://user:[email protected]:8080",
  "requestId": "example_login_001"
}

例のホスト名、アクション、プロキシを、対象サイトに合った値に置き換えてください。リクエスト送信前にrequestIdを決め、タイムアウト時の復旧に備えて保持します。新しい論理タスクごとに新しい値を使用してください。

この例ではプロキシを1つ使用しています。代わりにproxyCandidatesを使うと、パス、クエリ、フラグメントを含まない、重複のないHTTPまたはHTTPSプロキシURLを最大12個指定できます。どちらか一方のフィールドだけを送信し、両方は送信しないでください。候補を指定すると、サービスは別の送信元経路を試せますが、動作するプロキシが得られる保証はありません。

処理中の2Captchaタスクには、引き続き2Captchaの認証情報、タスクID、文書化されたポーリングポリシーを使用し、getTaskResultのフローで対応してください。他サービスのタスクIDは、solvethreeのタスクハンドルではありません。

1. 1.

   作成レスポンスの処理

   成功時のペイロードを読み取る前に、HTTPレスポンスが成功以外になっていないか確認します。reCAPTCHAの作成はデフォルトで最大15秒待機しますが、終端状態ではないタスクを返すこともあります。すでにreadyの場合は、ポーリングループを開始せずに解答を使用してください。

2. 2.

   未完了のタスクのみをポーリング

   GET /v1/tasks/:idでsolvethreeのタスクを取得します。従来のprocessingチェックをpendingとsolvingに置き換えてください。どちらもタスクが未完了であることを示します。使用可能な解答が含まれるのはreadyだけです。

3. 3.

   URLで待機時間を設定

   GETによるポーリングは、デフォルトでは待機しません。ロングポーリングでは、JSONフィールドではなく、URLクエリパラメーターのwaitMsに最大15000を指定します。HTTPクライアントのタイムアウトには、指定した待機時間に加えてネットワークのオーバーヘッドも見込んでください。

4. 4.

   failedで停止

   errorCodeとerrorを読み取り、そのタスクのポーリングを停止します。解決に失敗した場合は返金されます。site-unreachableなどのエラーは調査が必要です。すべての失敗をクレジットの問題と決めつけたり、無効な入力を変更せずに繰り返し送信したりしないでください。

接続タイムアウトが発生しても、作成に失敗したとは限りません。タスクIDを受信していれば、そのタスクを取得してください。受信していなければ、同じrequestIdで同じリクエストを再送し、新たな解決処理を作成するのではなく、既存のタスクを復旧します。同じrequestIdを再利用しながらタスクの入力を変更すると、競合が発生します。

アダプターでは、HTTPエラーとタスクの終端状態としての失敗を分けて扱います。ポーリングの仕様と失敗時の処理で、この2つの経路を説明しています。2Captchaのエラーペイロードパーサーは再利用しないでください。

既存のアダプターでのトークン参照を、ready状態のsolvethreeタスクのsolution.tokenに置き換えます。対象サイトがreCAPTCHAの値を受け取る箇所に、そのトークンを送信してください。タスクIDやsolutionオブジェクト全体を送信してはいけません。

トークンを送信するときは、返されたuserAgentとsecChUaによるブラウザー識別情報を、成功したプロキシと併せて使用します。proxyCandidatesを指定した場合も、送信用に別の候補を選ばず、成功したプロキシを使用してください。

タスクがreadyであることは、解答が生成されたことを意味し、ウェブサイトがアプリケーションのリクエストを受け入れたことを意味するわけではありません。対象サイトに拒否された場合は、次の解決処理に料金を支払う前に、送信するトークン、アクション、対象URL、プロキシ、ブラウザー識別情報を確認してください。