申請プロセス
Cloudflare Turnstile プロトコル認識 API を使用するには、まず Ace Data Cloud コンソール にアクセスして、API Token を取得し、保管してください。
まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。
1つの API Token でプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。 初回申請時には無料のクレジットが付与され、無料で体験できます。クレジットが不足した場合は、コンソール で一般残高をチャージできます。
📘 完全なドキュメント:Cloudflare Turnstile プロトコル認識 API →
基本使用
まず、基本的な使用方法を理解します。これは、処理する必要のある Turnstile CAPTCHA のウェブサイト URL を入力することで、処理された結果を得ることができます。最初にwebsite_url フィールドを簡単に渡す必要があります。私たちのサンプルサイトは https://react-turnstile.vercel.app です。website_url ページで website_key を取得する必要があります。まず、このウェブページを開き、F12 を押してコンソールに入り、Element ページで cf-turnstile を全体検索すると、Turnstile を含むコンテナ要素が見つかります。その中の data-sitekey に対応する文字列が website_key の値です。
設定するリクエストヘッダーには以下が含まれます:
accept:受け取りたいレスポンス結果の形式。ここではapplication/json、つまり JSON 形式を記入します。authorization:API を呼び出すためのキー。申請後、直接ドロップダウンから選択できます。
website_url:処理する CAPTCHA のウェブサイト URL。website_key:Cloudflare Turnstile におけるウェブサイトのキー識別子(sitekey)。action:オプションのパラメータ。ターゲットウェブサイトが Turnstile コンポーネントにカスタムactionを設定している場合のみ渡す必要があります。cdata:オプションのパラメータ。ターゲットウェブサイトが Turnstile コンポーネントにカスタムcDataを設定している場合のみ渡す必要があります。
token:今回の Cloudflare Turnstile CAPTCHA タスク処理後の検証結果。started_at、finished_at:今回のリクエストが処理を開始し、結果を出力した時間、Unix タイムスタンプ(秒、浮動小数点)。elapsed:今回の処理にかかった総時間(秒)。
cf-turnstile-response パラメータとしてターゲットウェブサイトに送信します。トークン検証に対応する Python コードは以下の通りです:
非同期モード(async)
デフォルトでは、API は同期ブロッキングです:1回のリクエストはトークン処理が完了するまで待機します。マルチソルバーのローテーションを行っている場合(multi-solver rotation)、タスクを提出した後にすぐに task_id を取得し、他のソルバーを調整し、後で結果を読み取ることを希望する場合は、リクエストボディにasync: true を渡すことができます。
async: true を渡すと、インターフェースはすぐに task_id を返し、待機することはありません:
task_id を使用して POST /captcha/tasks をクエリできます(3〜5秒ごとを推奨)。このインターフェースはタスク処理をトリガーしたり進めたりしません。クエリしなくても、ネットワークが切断されても、クライアントを終了しても、サーバーは処理を続けます:
status: processing が返され、処理が完了すると status: ready とトークンが返されます:
timeout で終了し、課金されません。/captcha/tasks はタスクを進める責任はありません。
注意:Cloudflare Turnstile は現在、持ち込みプロキシ(Bring Your Own Proxy)をサポートしていないため、このインターフェースはproxyパラメータを受け付けません;渡すと400 invalid_proxyが返されます。
エラーハンドリング
API を呼び出す際にエラーが発生した場合、API は対応するエラーコードと情報を返します。例えば:400 token_mismatched:不正なリクエスト、パラメータが不足しているか無効である可能性があります。400 invalid_proxy:不正なリクエスト、このキャプチャタイプではプロキシがサポートされていません。401 invalid_token:未承認、無効または不足している認証トークン。429 too_many_requests:リクエストが多すぎます、レート制限を超えました。500 api_error:内部サーバーエラー、サーバーで何かがうまくいきませんでした。

