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

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

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

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

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

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

  • クレジット カードのチャージバック、または不正行為に関する具体的な証拠があると、以前の金融取引が不正行為だったことがわかります。
  • 他のユーザーから迷惑メールと報告されたメッセージを発信する新しいアカウントは、そのアカウント作成が不正である可能性が高いことを示しています。
  • ユーザーがアカウントにログインできないとの問題に関するサポート記録は、ログインの試行が正当である可能性が高いことを示しています。
  • 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 文字の一意の英数字文字列です。たとえば、reCAPTFHA トークンが .................U=6ZZZZe73fZZZZZZ0 の場合、評価 ID は 6ZZZZe73fZZZZZZ0 になります。

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

  1. ユースケースに応じて、リクエストの 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"
      }

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

    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

    リクエスト本文を 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

    リクエスト本文を 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

    リクエスト本文を 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

    リクエスト本文を 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）と空のレスポンスが返されます。

次のステップ