为评估添加注解

本页面介绍了如何就 reCAPTCHA Enterprise 创建的评估的准确性提供反馈。利用此信息，reCAPTCHA Enterprise 可以微调网站专属模型，并随着时间的推移提升网站的性能。

何时为评估添加注解

reCAPTCHA Enterprise 会在创建评估时提供得分，该评估有助于您了解用户互动所产生的风险的等级。稍后，当您的网站提供有关用户互动的详细信息，以确定互动是否合法或具有欺骗性时，您可以确认或更正 reCAPTCHA Enterprise 的评估。为此，您需要将 reCAPTCHA 评估 ID 发回给 Google，标签为 LEGITIMATE 或 FRAUDULENT。确认或更正 reCAPTCHA Enterprise 的评估可以提升您网站的 reCAPTCHA Enterprise 的性能。

要提升 reCAPTCHA Enterprise 的性能，除了潜在的评估错误的注释外，您还可以确认真正例和真负例的注释。例如，对于使用双重身份验证方法成功进行身份验证并且 reCAPTCHA 得分较高的用户，您可以给评估添加注释 LEGITIMATE。或者，如果 reCAPTCHA 得分较低，并且您的网站确定互动属于欺诈或滥用行为，您可以给评估添加注释 FRAUDULENT。

以下列表显示了有关某些用户互动示例的补充信息，此类信息可指示用户互动是属于合法行为还是欺诈行为：

• 信用卡退款或其他欺诈的具体证据表明，较早的金融交易具有欺诈性。
• 如果新账号发送其他用户标记为垃圾邮件的电子邮件，则可能表示该账号是欺诈性账号。
• 如果用户无法登录其账号，则系统可能会提交支持案例，这可能表示登录尝试是合法的。
• 如果某网站在使用 reCAPTCHA Enterprise 来防范数据抓取，那么在该网站上进行购买或预订可能表示用户是合法的。

准备工作

• 确保您拥有以下 Identity and Access Management 角色：reCAPTCHA Enterprise Agent (roles/recaptchaenterprise.agent)。

• 根据您设置 reCAPTCHA Enterprise 的位置，完成相应的步骤：

• 为网站创建评估。

• 为您的移动应用创建评估。

• 设置 WAF 集成。

检索评估 ID

如需为评估添加注释，请按照以下步骤检索唯一评估 ID：

• 对于 Web 集成和移动应用集成，您可以从评估响应中检索唯一的评估 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 个字符的唯一字母数字字符串，显示在 reCAPTCHA 令牌末尾的 :U= 之后。例如，如果 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. 使用 projects.assessments.annotate 方法以及 gcloud CLI 或 API 密钥为评估添加注解。

   注意 ：如果您使用的是 v1beta1 版本的 API，我们建议您使用 v1 版本，因为 reCAPTCHA Enterprise 账号卫士等新功能仅适用于 v1 版本。如需从 v1beta1 迁移到 v1，请参阅从 v1beta API 迁移到 v1 API 。

   gcloud CLI

   在使用任何请求数据之前，请先进行以下替换：

   • ASSESSMENT_ID：从 projects.assessments.create 调用返回的 name 字段的值
   • ANNOTATION_LABEL：用于指示评估是合法还是欺诈性的标签。可能的值为 LEGITIMATE 或 FRAUDULENT。
   • ANNOTATION_REASON：描述为此评估选择的注解的上下文。如需了解可能的值，请参阅为评估添加注释的原因。

   HTTP 方法和网址：

   POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/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/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate"

   PowerShell

   注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 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/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate" | Select-Object -Expand Content

   您应该会收到一个成功的状态代码 (2xx) 和一个空响应。

   API 密钥

   在使用任何请求数据之前，请先进行以下替换：

   • ASSESSMENT_ID：从 projects.assessments.create 调用返回的 name 字段的值
   • ANNOTATION_LABEL：用于指示评估是合法还是欺诈性的标签。可能的值为 LEGITIMATE 或 FRAUDULENT。
   • ANNOTATION_REASON：描述为此评估选择的注解的上下文。如需了解可能的值，请参阅为评估添加注释的原因。

   HTTP 方法和网址：

   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 Enterprise 的用户账号保护功能。