为评估添加注解

本页将介绍如何就 创建的评估。有了这些信息 reCAPTCHA 可以对您的网站专用模型进行调优, 随着时间的推移,您网站的性能得以提升。

何时给评估添加注释

reCAPTCHA 会在创建评估时提供得分,该评估有助于您了解用户互动所产生的风险的等级。之后,当您的网站包含有关用户互动的更多信息时 要确定互动是合法的还是欺诈性的,您可以确认或 正确。为此,您需要向 reCAPTCHA 评估 ID 发回 Google,并标记为 LEGITIMATEFRAUDULENT。 确认或更正 reCAPTCHA 的评估可以提升您网站的 reCAPTCHA 的性能。

要提升 reCAPTCHA 的性能,除了潜在的评估错误的注释外,您还可以确认真正例真负例的注释。例如,对于使用双重身份验证方法成功进行身份验证并且 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 是 由 16 个字符组成的具有唯一性的字母数字字符串,显示在 将于 :U=后使用 reCAPTCHA 令牌。例如,如果 reCAPTCHA 令牌是 .................U=6ZZZZe73fZZZZZZ0,则评估 ID 为 6ZZZZe73fZZZZZZ0

为评估添加注释

  1. 根据您的使用场景确定要在请求 JSON 正文中添加的信息和标签。

    下表列出了可用于为事件添加注解的标签和值:

    标签 说明 请求示例
    reasons 可选。一个标签,用于支持您的 评估。

    请在事件发生后的几秒或几分钟内在 reasons 标签中提供实时事件详情,因为这些详情会影响实时检测。

    有关 可能的值, 请参阅原因值

    示例:要检测账号盗用,请在输入的 CORRECT_PASSWORD 的密码正确,或者 INCORRECT_PASSWORD 值。如果您部署了自己的 MFA, 您可以添加以下值:INITIATED_TWO_FACTORPASSED_TWO_FACTORFAILED_TWO_FACTOR

          {
          "reasons": ["INCORRECT_PASSWORD"]
          }
        
    annotation 可选。用于指示评估结果是否合法的标签。

    提供有关登录和 注册事件,以便在 annotation 标签。

    可能的值:LEGITIMATEFRAUDULENT

    您可以随时发送此类信息,也可以在批处理作业中发送。 不过,我们建议您在几秒钟或几分钟内发送此信息 因为它们会影响实时检测。

          {
           "annotation": "LEGITIMATE"
          }
    
      

  2. 使用 projects.assessments.annotate 方法。

    gcloud CLI

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

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

    HTTP 方法和网址:

    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:用于指明评估是否合法的标签。 可能的值是 LEGITIMATEFRAUDULENT
    • 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

    将请求正文保存在名为 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) 和一个空响应。

后续步骤