クライアント側統合を完了した後、CAPTCHA チャレンジごとに検証を行うため、ご利用のサーバーから VerifyIntelligentCaptcha API を呼び出します。クライアント側でのみ検証を行うと、アプリケーションは保護されません。攻撃者がトークンを偽造することが可能であるため、リクエストを許可する前に、必ずバックエンドでトークンを検証してください。
前提条件
開始する前に、以下の条件を満たしていることを確認してください。
クライアント側統合を完了済みであること
アクセス認証情報を作成済みであること — Captcha 2.0 では AccessKey 認証および Security Token Service (STS) トークン認証がサポートされています。詳細については、「認証情報クライアントの初期化」をご参照ください。
API を呼び出す Resource Access Management (RAM) ユーザーに AliyunYundunAFSFullAccess 権限が付与済みであること
Alibaba Cloud のルートアカウントの AccessKey を使用しないでください。万が一漏洩した場合、すべてのクラウドリソースが危険にさらされます。代わりに RAM ユーザーの AccessKey を使用してください。
仕組み
サーバー側検証の処理フローは以下のとおりです。
クライアントがトークンを生成します。 ユーザーが CAPTCHA チャレンジを完了すると、Captcha SDK が
CaptchaVerifyParamCaptcha 2.0 コンソール トークンを生成し、ご利用のサーバーに渡します。ご利用のサーバーが `VerifyIntelligentCaptcha` を呼び出します。 トークンを変更せずに Captcha 2.0 サービスに送信します。
CaptchaVerifyParamを一切変更しないでください。変更すると検証エラーが発生します。Captcha 2.0 が応答します。 API は
VerifyResult（trueまたはfalse）および、検証結果の詳細を示すVerifyCodeを返します。ご利用のサーバーが検証結果に基づいて処理を行います。
VerifyResultがtrueの場合はリクエストを許可し、それ以外の場合は拒否します。
トークンの制約事項：
各トークンは 1 回のみ検証可能です。再利用するとエラーコード F008 が返されます。
初期化レコードは 20 分後に有効期限切れとなります。初期化から検証までの間隔が 20 分を超えると、トークンは無効になります（F014）。
V3 アーキテクチャでは、動作検証リクエストとビジネス署名検証リクエストの間隔が 90 秒を超えてはなりません（F019）。
SDK のインストール
OpenAPI 開発者ポータルから、ご利用のプログラミング言語に対応したサーバー側 SDK をダウンロードしてください。パッケージを展開し、プロジェクトに読み込みます。
言語 | SDK ダウンロード URL | GitHub ソース URL |
Java | ||
Python | ||
TypeScript | ||
Go | ||
PHP | ||
Swift | ||
C++ | ||
.NET |
VerifyIntelligentCaptcha API の呼び出し
エンドポイントの選択
クライアント側の region 値（AliyunCaptchaConfig 内）を、正しいサーバー側エンドポイントにマップします。リージョンが一致しないと、リクエストエラーが発生します。
クライアント側の region 値 | デプロイメント | サーバー側エンドポイント |
|---|---|---|
cn | 中国本土（上海）— IPv4 専用 | captcha.cn-shanghai.aliyuncs.com |
cn | 中国本土（上海）— デュアルスタック（IPv4 および IPv6） | captcha-dualstack.cn-shanghai.aliyuncs.com |
sgp | 中国本土以外（シンガポール）— IPv4 専用 | captcha.ap-southeast-1.aliyuncs.com |
sgp | 中国本土以外（シンガポール）— デュアルスタック（IPv4 および IPv6） | captcha-dualstack.ap-southeast-1.aliyuncs.com |
API は HTTPS を使用し、POST メソッドで呼び出します。
リクエストパラメーター
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
CaptchaVerifyParam | String | はい | Captcha スクリプトのコールバックで返されたトークンです。受信したままの状態で API に渡してください — 変更しないでください。 |
SceneId | String | いいえ | 現在の検証におけるシナリオ ID です。マルチシナリオ構成では、クライアントが別のシナリオを代わりに使用することを防ぐため、サーバー側でこの値を指定してください。 |
アーキテクチャ別 CaptchaVerifyParam のフォーマット：
V2：
{"sceneId":"xxxxxx","certifyId":"xxxxxx","deviceToken":"xxxxxxx==","data":"xxxxxx==","..."}V3：
eyJjZXxxxxxxxxxxxxxxnVlfQ==（Base64 エンコード）
レスポンスパラメーター
| パラメーター | 型 | 説明 |
|---|---|---|
RequestId | String | リクエスト ID です。 |
Success | Boolean | true、失敗した場合は false です。 |
Code | String | HTTP レベルのリターンコードです。 |
Message | String | リターンコードに関する詳細情報です。 |
VerifyResult | Boolean | true、失敗した場合は false です。 |
VerifyCode | String | 検証結果の具体的なコードです。下記の表をご参照ください。 |
CertifyID | String | 検証エポック識別子です。初期化時にカスタムの UserCertifyId を指定した場合、その値がここに返されます。それ以外の場合は、サーバーがデフォルトの CertifyID を生成します。 |
VerifyCode リファレンス
まず VerifyResult を確認し、その後、診断およびログ記録のために VerifyCode を使用してください。
| コード | 意味 | 操作 |
|---|---|---|
| T001 | 検証に合格しました。 | リクエストを許可します。 |
| T005 | テストモードが有効になっており、すべての検証を合格させるように設定されています。 | 本番環境では、Captcha 2.0 コンソール でポリシーのステータスを確認してください。詳細については、「Captcha 2.0 コンソール統合ガイド」をご参照ください。 |
| F001 | 攻撃の疑いあり — リスクコントロールポリシーによりブロックされました。 | リクエストを拒否します。 |
| F002 | CaptchaVerifyParam が空です。 | 統合内容を確認してください：フロントエンドは、このパラメーターを変更せずにサーバーに渡す必要があります。 |
| F003 | CaptchaVerifyParam のフォーマットが無効です。 | 統合コードを確認してください — このパラメーターは API に到達するまでに一切変更してはいけません。 |
| F004 | テストモードが有効になっており、すべての検証をブロックするように設定されています。 | Captcha 2.0 コンソール にログインし、このシナリオのポリシーのステータスを調整してください。詳細については、「Captcha 2.0 コンソールシナリオの管理」をご参照ください。 |
| F005 | sceneId が CaptchaVerifyParam 内で無効です。 | CaptchaVerifyParam を変更しないでください。統合コードを確認してください。 |
| F006 | sceneId が CaptchaVerifyParam 内でご利用のアカウントに属していません。 | Captcha 2.0 コンソール にログインし、シナリオの構成を確認してください。 |
| F008 | トークンの再利用 — トークンは 1 回のみ送信可能です。 | ユーザーに CAPTCHA を再度完了させ、新しいトークンを取得するよう促してください。 |
| F009 | 仮想デバイス環境が検出されました（VMware、VirtualBox、Hyper-V、Parallels、AVD、BlueStacks、またはモバイル端末を模倣したデスクトップブラウザ）。 | リクエストを拒否するか、Captcha 2.0 コンソール でカスタムポリシーを設定してこのチェックを無効化してください。詳細については、「Captcha 2.0 コンソールCaptcha 2.0 コンソールCaptcha 2.0 コンソールCaptcha 2.0 コンソールカスタムポリシーの設定」をご参照ください。 |
| F010 | 同一 IP アドレスからのアクセス頻度が上限を超えました。 | リクエストを拒否します。必要に応じて、Captcha 2.0 コンソール でしきい値を調整してください。詳細については、「カスタムポリシーの設定」をご参照ください。 |
| F011 | 同一デバイスからのアクセス頻度が上限を超えました。 | リクエストを拒否します。必要に応じて、Captcha 2.0 コンソール でしきい値を調整してください。詳細については、「カスタムポリシーの設定」をご参照ください。 |
| F012 | サーバー側リクエスト内の SceneId が、フロントエンドで構成された sceneId と一致しません。 | サーバー側の SceneId を、Captcha コンソールで構成されたシナリオと一致させる必要があります。 |
| F013 | CaptchaVerifyParam に必須フィールドが不足しています。 | CaptchaVerifyParam を変更しないでください。統合コードを確認してください。 |
| F014 | 初期化レコードが見つかりません。 | 初期化と検証の間隔が 20 分を超えている（クライアント側で再初期化が必要）、または初期化リクエストが送信されていない（クライアント側統合を確認）可能性があります。 |
| F015 | 検証インタラクションに失敗しました（例：パズルピースを正しい位置に移動しなかった）。 | ユーザーに CAPTCHA をリフレッシュして再試行するよう促してください。 |
| F016 | コンソールで構成された URL 検証ポリシーによりリクエストがブロックされました。 | Captcha 2.0 コンソール で URL 検証ポリシーを調整してください。詳細については、「カスタムポリシーの設定」をご参照ください。 |
| F017 | 攻撃の疑いあり — 異常なプロトコルまたはパラメーターによりブロックされました。 | リクエストを拒否します。 |
| F018 | （V3 のみ）ビジネス署名検証リクエストの CaptchaVerifyParam が再利用されています。 | 各ビジネス署名検証リクエストには、新しいトークンを使用する必要があります。 |
| F019 | （V3 のみ）ビジネス署名検証リクエストが、動作検証リクエストの 90 秒以上経過後に送信されたか、動作検証リクエストなしで送信されました。 | ビジネス署名検証リクエストは、動作検証リクエストの 90 秒以内に送信する必要があります。 |
| F020 | （V3 のみ）ビジネス署名検証リクエストの CaptchaVerifyParam が、シナリオ ID またはユーザーと一致しません。 | ビジネス署名検証に使用するトークンが、正しいシナリオおよびユーザーに対応しているか確認してください。 |
HTTP ステータスコード
| HTTP ステータス | コード | メッセージ |
|---|---|---|
| 200 | Success | リクエストが成功しました。 |
| 400 | MissingParameter | 必須パラメーターが不足しています。 |
| 401 | InvalidParameter | パラメーターが無効です。 |
| 403 | Forbidden.AccountAccessDenied | 権限がありません。サービスが有効化されていないか、アカウントの支払いが遅延している可能性があります。 |
| 403 | Forbidden.RAMUserAccessDenied | RAM ユーザーに権限が付与されていません。 AliyunYundunAFSFullAccess 権限を付与してください。詳細については、「RAM ロールへの権限付与」をご参照ください。 |
| 500 | InternalError | 内部エラーが発生しました。リクエストを再試行してください。 |
コード例
すべての対応言語における、完全かつ実行可能なサーバー側検証のサンプルコードについては、サーバー側インテリジェント検証のサンプルコード（OpenAPI 開発者ポータル）をご参照ください。
次のステップ
シナリオの管理 — 異なる検証コンテキスト向けにシナリオを作成および構成します
カスタムポリシーの設定 — アクセス頻度の上限、仮想デバイス検出、URL 検証ルールを調整します