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

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

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

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

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

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

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

準備

評価 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 は、16 文字の一意の英数字文字列で、:U= の後に reCAPTCHA トークンの末尾に表示されます。たとえば、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）と空のレスポンスが返されます。

次のステップ