評価にアノテーションを付ける

このページでは、reCAPTCHA で作成された評価の精度に関するフィードバックを提供する方法について説明します。この情報を使用して、reCAPTCHA はサイト固有のモデルを調整し、時間の経過とともにサイトのパフォーマンスを向上させることができます。

評価にアノテーションを付けるタイミング

reCAPTCHA では、ユーザー操作がもたらすリスクレベルを理解するのに有効な評価を作成する際に、スコアが提供されます。後で、サイトがユーザー操作に関する詳細情報を得て、その操作が正当か不正かを判断できるようになった場合は、reCAPTCHA の評価を確認または修正できます。そのためには、reCAPTCHA 評価 ID に LEGITIMATE または FRAUDULENT というラベルを付けて Google に返します。reCAPTCHA の評価を確認または修正することで、サイトに対する reCAPTCHA のパフォーマンスが向上します。

reCAPTCHA のパフォーマンスを向上させるために、評価エラーの可能性を示すアノテーションに加え、真陽性と真陰性のアノテーションを確認できます。たとえば、2 要素認証プロセスを使用して認証に成功し、reCAPTCHA スコアが高いユーザーの場合は、評価に LEGITIMATE のアノテーションを付けることができます。または、reCAPTCHA スコアが低く、サイトでインタラクションが不正または不適切であると判断された場合は、評価に FRAUDULENT のアノテーションを付けることができます。

次のリストは、正当または不正なユーザーインタラクションの例による追加情報です。

クレジットカードのチャージバック、または不正行為に関する具体的な証拠があると、以前の金融取引が不正行為だったことがわかります。
他のユーザーから迷惑メールと報告されたメッセージを発信する新しいアカウントは、そのアカウント作成が不正である可能性が高いことを示しています。
ユーザーがアカウントにログインできないとの問題に関するサポート記録は、ログインの試行が正当である可能性が高いことを示しています。
reCAPTCHA を使用してスクレイピングを阻止するサイトでの購入または予約は、そのユーザーが正当である可能性が高いことを示しています。

始める前に

reCAPTCHA Enterprise エージェント（roles/recaptchaenterprise.agent）の Identity and Access Management ロールがあることを確認します。
reCAPTCHA を設定している場所に応じて、適切な手順を行います。

評価 ID を取得する

評価にアノテーションを付けるには、次の方法で一意の評価 ID を取得します。

ウェブとモバイルの統合では、評価レスポンスから一意の評価 ID を取得できます。

評価を作成すると、次の例に示すように JSON レスポンスが返されます。

JSON レスポンスの name フィールドから一意の評価 ID を取得します。

{
'tokenProperties': {
  'valid': True,
  'hostname': 'www.google.com',
  'action': 'homepage',
  'createTime': u'2019-03-28T12:24:17.894Z'
},
'riskAnalysis': {
  'score': 0.1,
  'reasons': ['AUTOMATION']
},
'event': {
  'token': 'RESPONSE_TOKEN',
  'siteKey': 'KEY_ID'
},
'name': 'ASSESSMENT_ID'
}

WAF 統合の場合、reCAPTCHA トークンから一意の評価 ID を取得できます。一意の評価 ID は、reCAPTCHA トークンの末尾の :U= の後に表示される 16 文字の一意の英数字文字列です。たとえば、reCAPTCHA トークンが .................U=6ZZZZe73fZZZZZZ0 の場合、評価 ID は 6ZZZZe73fZZZZZZ0 です。

評価へのアノテーション付け

ユースケースに応じて、リクエストの JSON 本文に追加する情報とラベルを決定します。

次の表では、イベントにアノテーションを付けるために使用できるラベルと値を示します。

ラベル説明リクエストの例

ラベル	説明	リクエストの例
`reasons`	省略可。評価をサポートするラベル。リアルタイムの検出に影響するため、イベント後数秒または数分で `reasons` ラベルにリアルタイムのイベントの詳細が提供されます。有効な値については、理由の値をご覧ください。例: アカウントの乗っ取りを検出するには、入力したパスワードが正しいかどうかを `CORRECT_PASSWORD` または `INCORRECT_PASSWORD` の値でアノテーションを設定します。独自の MFA をデプロイした場合は、`INITIATED_TWO_FACTOR`、`PASSED_TWO_FACTOR`、`FAILED_TWO_FACTOR` の値を追加できます。	{ "reasons": ["INCORRECT_PASSWORD"] }
`annotation`	省略可。評価の正当性を示すラベル。ログインイベントと登録イベントに関する事実を提供して、`annotation` ラベルでリスク評価を検証または修正します。有効な値は `LEGITIMATE` または `FRAUDULENT` です。この情報はいつでも送信でき、またバッチジョブの一部として送信できます。ただし、リアルタイムの検出に影響するため、この情報はイベント後数秒または数分で送信することをおすすめします。	{ "annotation": "LEGITIMATE" }

reasons

省略可。評価をサポートするラベル。

リアルタイムの検出に影響するため、イベント後数秒または数分で reasons ラベルにリアルタイムのイベントの詳細が提供されます。

有効な値については、理由の値をご覧ください。

例: アカウントの乗っ取りを検出するには、入力したパスワードが正しいかどうかを CORRECT_PASSWORD または INCORRECT_PASSWORD の値でアノテーションを設定します。独自の MFA をデプロイした場合は、INITIATED_TWO_FACTOR、PASSED_TWO_FACTOR、FAILED_TWO_FACTOR の値を追加できます。

      {
      "reasons": ["INCORRECT_PASSWORD"]
      }

annotation

省略可。評価の正当性を示すラベル。

ログインイベントと登録イベントに関する事実を提供して、annotation ラベルでリスク評価を検証または修正します。

有効な値は LEGITIMATE または FRAUDULENT です。

この情報はいつでも送信でき、またバッチジョブの一部として送信できます。ただし、リアルタイムの検出に影響するため、この情報はイベント後数秒または数分で送信することをおすすめします。

      {
       "annotation": "LEGITIMATE"
      }

gcloud CLI または API キーを使用して projects.assessments.annotate メソッドを使用して評価にアノテーションを付けます。

注: API の v1beta1 バージョンを使用している場合は、v1 バージョンを使用することをおすすめします。reCAPTCHA アカウント保護などの新機能は v1 バージョンでのみ使用できるためです。v1beta1 から v1 への移行については、v1beta API から v1 API への移行をご覧ください。
gcloud CLI

リクエストのデータを使用する前に、次のように置き換えます。
- ASSESSMENT_ID: projects.assessments.create 呼び出しから返された name フィールドの値。
- ANNOTATION_LABEL: 評価が正当か不正かを示すラベル。指定可能な値は LEGITIMATE、FRAUDULENT です。
- ANNOTATION_REASON: この評価用に選択されたアノテーションのコンテキストを記述します。有効な値については、評価にアノテーションを付ける理由をご覧ください。
HTTP メソッドと URL:
POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate
リクエストの本文（JSON）:
{ "annotation": "ANNOTATION_LABEL" "reasons": "ANNOTATION_REASON" }
リクエストを送信するには、次のいずれかのオプションを選択します。
curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate"
PowerShell

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate" | Select-Object -Expand Content
成功したことを示すステータスコード（2xx）と空のレスポンスが返されます。
API キー

リクエストのデータを使用する前に、次のように置き換えます。
- ASSESSMENT_ID: projects.assessments.create 呼び出しから返された name フィールドの値
- ANNOTATION_LABEL: 評価が正当か不正かを示すラベル。指定可能な値は LEGITIMATE、FRAUDULENT です。
- ANNOTATION_REASON: この評価用に選択されたアノテーションのコンテキストを記述します。有効な値については、評価にアノテーションを付ける理由をご覧ください。
HTTP メソッドと URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY
リクエストの本文（JSON）:
{ "annotation": "ANNOTATION_LABEL" "reasons": "ANNOTATION_REASON" }
リクエストを送信するには、次のいずれかのオプションを選択します。
curl

注: API で認証するための API キーを作成します。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY"
PowerShell

注: API で認証するための API キーを作成します。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$headers = @{ }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY" | Select-Object -Expand Content
成功したことを示すステータスコード（2xx）と空のレスポンスが返されます。

次のステップ

reCAPTCHA のユーザーアカウント保護機能について学習する。

評価にアノテーションを付ける