reCAPTCHAをgetTokenで解決: 1リクエスト、ポーリングなし

TL;DR

• CapSolverのgetTokenエンドポイントは、1回のリクエストでサポートされているreCAPTCHAの結果を返すことができます。
• clientKeyとサポートされているタスクオブジェクトをhttps://api.capsolver.com/getTokenに送信してください。
• ご使用のreCAPTCHAバリアントに応じたタスクタイプを選択し、対応するページ、公開サイトキー、および必要なコンテキストを提供してください。
• APIの結果を確認した後、solution.gRecaptchaResponseを読み取ってください。HTTPの成功だけでは十分ではありません。
• 返されたトークンは、所有するアプリケーションの通常の検証が必要です。1回のリクエストが即座の完了や保証された受け入れを意味するわけではありません。
• 下記のcURLリクエストはローカルのHTTP Fixtureでテストされています。ライブでの解決は行われていません。

従来のCAPTCHAソルバーの統合では、タスクを作成してからその結果を要求します。サポートされているreCAPTCHAタスクを統合し、直接的な応答を希望する場合、CapSolverのgetTokenエンドポイントは、別のドキュメント化されたリクエストパターンを提供します。

実際の違いはクライアント側にあり、タスクを送信し、その結果をそのHTTP応答で待つことになります。このフローではgetTaskResultのポーリングループを記述する必要はありません。このガイドでは、タスクのフィールド、JSONファイルおよびcURLコマンド、返されるトークン、および所有するアプリケーションが受け入れる前に必要なチェックについて説明します。

getToken APIとは何か？

getToken APIは、ドキュメントに記載されているreCAPTCHAタスクタイプの直接的な結果エンドポイントです。APIエンドポイントは、特定のAPI操作のアドレスであり、正しいパスを使用することでこのリクエストパターンを選択します。

公式のgetTokenドキュメントには、reCAPTCHA v2およびv3のタスクバリアント（および対応するエンタープライズおよびプロキシオプション）がリストされています。エンドポイントの一般的な名前からAWS WAF、Turnstile、または画像認識のサポートを推測しないでください。

このメソッドは結果の取得方法を変更するだけで、チャレンジパラメータの意味は変わりません。間違った公開サイトキーまたはタスクタイプの不一致は、直接エンドポイントを介して送信しても依然として間違ったままです。まずCAPTCHAのファミリを確認し、その後ドキュメント化されたタスクバリアントを選択してください。

一部のcreateTaskタスクファミリはすでに結果を直接返します。比較の意味は、すべてのcreateTask呼び出しがポーリングを必要とするという意味ではありません。

ステップ1: reCAPTCHAタスクとキーを特定する

所有するページ上の実際のreCAPTCHA統合を特定してください。以下の例ではReCaptchaV3TaskProxyLessを使用しているため、そのフィールドはv3の統合を記述する必要があります。

3つの重要な役割を別々に保つ必要があります。CapSolverのAPIキーは解決リクエストを認証します。reCAPTCHAの公開サイトキーはページの統合を識別します。サイトオーナーの検証シークレットはアプリケーションのサーバーにあり、このリクエストのclientKeyやwebsiteKeyではありません。

v3の場合、期待されるアクションと公開キーを確認してください。reCAPTCHA v3タスクドキュメントは、pageActionを含むタスクフィールドについて説明しています。以下の例のアクションsubmitは、所有するフォームが実際に使用するアクションのプレースホルダーです。

GoogleのreCAPTCHA v3ドキュメントは、アクションベースの評価を説明しています。異なるアクションのトークンは、意図したフォームの成功テストとして扱ってはなりません。リクエストのアクションとバックエンドの期待されるアクションを一致させてください。

ページがv2またはエンタープライズを使用している場合、v3のアクションを別のタスクにコピーするのではなく、そのドキュメント化されたタスクタイプとフィールドを選択してください。その要件を確認せずに異なるタスクに変更しないでください。

ステップ2: ドキュメント化されたJSONリクエストを保存する

以下のJSONをrequest.jsonとして保存してください。そのラッパーはgetTokenドキュメントに従い、タスクフィールドはv3ガイドに従います。これらはサンプル値であり、ライブチェックのために独自の設定に置き換えてください。

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "ReCaptchaV3TaskProxyLess",
    "websiteURL": "https://your-owned-test.example/form",
    "websiteKey": "YOUR_PUBLIC_SITE_KEY",
    "pageAction": "submit"
  }
}

ライブエンドポイントに接続する前に、すべてのプレースホルダーを置き換えてください。例のドメインは所有するテストページを明確に識別しており、動作するCAPTCHAターゲットではありません。公開キーとアクションは、そのページの構成済み統合から取得する必要があります。

JSONファイルは、長いシェルコマンドなしでペイロードを確認しやすくします。実際の資格情報が含まれている場合、そのファイルへのアクセスを制限し、ソース管理から除外してください。アプリケーションにこのリクエストを移動する際には適切なシークレット管理方法を使用してください。

プロキシレスタスクの名前は、プロバイダーのタスクバリアントを説明しています。これは正しいページコンテキストの必要性や、すべてのチャレンジ構成が同じパラメータを使用することを意味するものではありません。タスクドキュメントをフィールドの参照として使用してください。

ステップ3: cURLで1つのリクエストを送信する

request.jsonが含まれるディレクトリからこのコマンドを実行してください。そのフラグとペイロードはローカルのHTTP Fixtureでテストされていますが、ライブエンドポイントには解決用の資格情報と所有するページのパラメータが必要です:

curl --silent --show-error --connect-timeout 10 --max-time 90 \
  --json @request.json \
  https://api.capsolver.com/getToken

このコマンドはcURLのJSONリクエストオプションを使用して、ファイルを本文として送信します。公式のcURL JSONドキュメントはオプションとそのリクエストヘッダーについて説明しています。--jsonをサポートするcURLバージョンを使用してください。

接続および総合タイムアウト値は、この例でのローカルの選択であり、プロバイダーのサービスレベルのコミットメントではありません。エンドポイントはタスクの解決中にリクエストを保持する可能性があるため、直接的な応答は即時応答を意味するものではありません。

HTTPの結果とJSONの内容の両方を確認してください。このコマンドは応答本文とトランスポートエラーを表示します。これは完全なアプリケーションエラー処理ではありません。cURLは、返されたJSONがプロバイダーのエラーを説明している場合でも、HTTP交換を完了する可能性があります。アプリケーションは返されたフィールドに基づいて分岐する必要があります。トークンに似た文字列をターミナル出力で検索するのではなく、それ以外の方法で行うべきです。

このコマンドにポーリングループを追加しないでください。選択されたフローは特に直接的な結果の返却を意図しています。アプリケーションが別個の結果取得を必要とする場合、最初からドキュメント化されたcreateTaskフローを選択し、実装してください。

CapSolverのボーナスコードを活用してください

自動化予算を即座に増やす！
CapSolverアカウントにチャージする際、ボーナスコードCAP26を使用すると、すべてのチャージで5%のボーナスを獲得できます。制限なし。
今すぐCapSolverダッシュボードで適用してください

ステップ4: 直接的なトークン応答を読み取る

結果が成功と準備ができていることを確認した後、solution.gRecaptchaResponseを読み取ってください。以下の応答形式は例示的なものであり、トークンの値はライブ解決によって返されたものではなく、プレースホルダーです。

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "ILLUSTRATIVE_TOKEN_VALUE"
  }
}

重要な値はエラーインジケータ、準備状態、および空でない結果フィールドです。応答オブジェクト、タスク識別子、またはHTTPの成功ステータスを、使用可能なトークンと交換しないでください。オプションのフィールドも表示される可能性があり、統合に必要なもののみを保持してください。

プロバイダーの失敗の場合、APIエラー参照に記載されているエラーコードと説明を確認してください。無効なパラメータ、アカウントの問題、またはトランスポートの障害を区別できる情報を保持してください。資格情報やトークンは通常のログから除外してください。

直接的なエンドポイントはクライアントの状態マシンを簡略化しますが、接続は操作の一部です。クライアントがタイムアウトまたは応答を失った場合、結果は不明確になる可能性があります。リクエストがローカルエラーが発生する前にプロバイダーに到達した可能性があるため、即時の2回目の送信を最初のタスクの再開と説明しないでください。APIがその動作を明示的にドキュメント化していない限りです。

ステップ5: 所有するアプリケーションでトークンを検証する

返されたトークンは、操作が成功したとみなされる前に、アプリケーションの通常の検証を通過する必要があります。ソルバーの結果とアプリケーションの受け入れは、別々のイベントです。

Googleのサーバーサイド検証ドキュメントは、応答トークンが2分後に期限切れになり、一度だけ検証可能であることを述べています。意図された操作に近いタイミングでトークンを取得し、検証エンドポイントで同じトークンを繰り返しテストしないでください。

標準的な検証フローでは、サイトオーナーのシークレットはバックエンドにあります。統合に関連する応答プロパティを確認してください。これには、期待されるホスト名と、v3の場合、アクションとスコアポリシーが含まれます。エンタープライズアプリケーションは、標準例がすべてのバリアントをカバーしていると仮定せず、対応する検証または評価統合を使用する必要があります。

所有するフォームにsubmitアクションがある場合、有用なテストはまず要求されたタスクがそのアクションを記述していることを確認し、その後、返されたトークンをフォームの通常のバックエンドパスに送信し、意図されたテスト操作が受け入れられたことをアサートします。ターミナルに印刷されたトークン文字列は、文字列が受信されたことを示すだけです。

スコアの解釈については、別のreCAPTCHA v3スコアガイドをご覧ください。取得エンドポイントの切り替えは、特定のスコアを確立したり、バックエンドの受け入れルールを解除したりするものではありません。

getTokenをポーリングではなく使用すべきタイミングは？

タスクバリアントがサポートされており、クライアントが結果を待つ間にリクエストを開いたままにできる場合、このエンドポイントを使用してください。これは、次のアプリケーションステップがすぐに返されたトークンを消費する小さな直接的な統合に適しています。

アプリケーションが明示的に別個のタスク作成と結果取得を必要とする場合、createTask APIとそのドキュメント化された結果フローを使用してください。たとえば、ステップ間でタスク識別子を永続化するワーカーは、このパターンに基づいて構成される可能性があります。

クライアントのライフサイクルに基づいて選択してください。1つのエンドポイントが常に高速であると仮定しないでください。直接的なリクエストはクライアントのポーリングコードを削除しますが、これだけで解決遅延が低いことを証明するものではありません。バックグラウンドワーカーは、単一の同期HTTPコールで提供されない制御が必要な場合があります。

単に好むエンドポイントに合わせてCAPTCHAファミリを切り替えないでください。ページがチャレンジタイプを決定します。もしファミリがgetTokenでリストされていない場合、そのファミリのドキュメント化されたAPIに従ってください。

例のテストで何が確認されているのか？

cURLコマンドは、エンドポイントのみを置き換えてローカルのHTTP Fixtureで実行されました。FixtureはPOSTパス、JSONコンテンツタイプ、および正確にパースされたペイロードをチェックし、供給された準備完了応答を返しました。これにより、ファイルベースのコマンドと直接応答処理が検証されました。

実際の解決キー、有料タスク、またはreCAPTCHA保護フォームは使用されていません。Fixtureのトークンはどのアプリケーションでも有効ではありません。ライブ統合には、実際のサイトキー、アクション、解決用資格情報、および所有するアプリケーションの検証結果が必要です。

単一のテストを超えて拡張する前に、所有するページで動作したタスクバリアントとフィールドを記録してください。テストが失敗した場合、タスク送信、結果取得、トークン検証、または最終的なアプリケーション操作のどの段階で失敗したかを特定してください。これらの区別は、不要なポーリングループを追加することなく、具体的な出発点を提供します。

CapSolverで試してみることで、ライブ検証ステップを完了できます。cURLからアプリケーションに移行する際に、同じリクエストフィールドと受け入れチェックを保持してください。

FAQ

Q: getTokenはgetTaskResultを必要としますか？

ここに記載されている直接的なフローでは、結果がgetTokenの応答に返されるため、クライアントはgetTaskResultをポーリングする必要はありません。別個の取得を必要とするタスクの追跡は、対応するcreateTask統合に属します。

Q: getTokenはすべてのCAPTCHAタイプを解決できますか？

ドキュメントに記載されているタスクタイプのみを使用してください。ドキュメント化されたreCAPTCHAバリアントは、AWS WAFや画像認識などの関連のないファミリのサポートを示すものではありません。

Q: getTokenはcreateTaskよりも高速ですか？

このガイドでは遅延の優位性を示していません。観測可能なデザインの違いは、クライアントが別個の取得ループを実装する代わりに直接的な結果を待つことであるだけです。

Q: websiteKeyはプライベート検証シークレットですか？

いいえ。これはページ統合の公開サイトキーです。サイトの検証シークレットはバックエンドにあり、clientKeyは解決サービスの資格情報です。

Q: なぜ返されたトークンが検証に失敗する可能性があるのですか？

有効期限、以前の使用、期待されるページコンテキスト、アクション、およびアプリケーションの検証応答を確認してください。ソルバーからトークンを受信したからといって、アプリケーションが受け入れる保証はありません。

Q: サンプルトークンはライブ解決によって生成されましたか？

いいえ。表示されている応答は例示的なものであり、コマンドはローカルのHTTP Fixtureでテストされました。解決用キーと所有するアプリケーションで別のライブテストを完了してください。