本页介绍了如何针对 reCAPTCHA 创建的评估的准确性提供反馈。利用这些信息,reCAPTCHA 可以调整您的网站专用模型,并随着时间的推移而提升您网站的性能。
何时为评估添加注释
reCAPTCHA 会在创建评估时提供分数,以帮助您了解用户互动造成的风险程度。之后,当您的网站获得更多有关用户互动的信息来确定互动是合法还是欺诈性时,您可以确认或纠正 reCAPTCHA 的评估。为此,您需要将 reCAPTCHA 评估 ID 发回给 Google,标签为 LEGITIMATE
或 FRAUDULENT
。确认或更正 reCAPTCHA 的评估可提高网站 reCAPTCHA 的性能。
为了提高 reCAPTCHA 的性能,除了潜在评估错误的注释之外,您还可以确认真正例和真负例的注释。例如,对于使用双重身份验证方法成功进行身份验证并且 reCAPTCHA 得分较高的用户,您可以给评估添加注释 LEGITIMATE
。或者,如果 reCAPTCHA 得分较低,并且您的网站确定互动属于欺诈或滥用行为,您可以给评估添加注释 FRAUDULENT
。
以下列表显示了有关某些用户互动示例的补充信息,此类信息可指示用户互动是属于合法行为还是欺诈行为:
- 信用卡退款或其他欺诈的具体证据表明,较早的金融交易具有欺诈性。
- 如果新账号发送其他用户标记为垃圾邮件的电子邮件,则可能表示该账号是欺诈性账号。
- 如果用户无法登录其账号,则系统可能会提交支持案例,这可能表示登录尝试是合法的。
- 在使用 reCAPTCHA 来防范网络爬取的网站上进行购买交易或预订,可能表明用户是合法用户。
准备工作
确保您拥有以下 Identity and Access Management 角色:reCAPTCHA Enterprise Agent (
roles/recaptchaenterprise.agent
)。根据您设置 reCAPTCHA 的位置,完成相应的步骤:
检索评估 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
。
为评估添加注解
根据您的用例确定要在请求 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" }
使用
projects.assessments.annotate
方法和 gcloud CLI 或 API 密钥为评估添加注解。gcloud CLI
在使用任何请求数据之前,请先进行以下替换:
- ASSESSMENT_ID:从
projects.assessments.create
调用返回的name
字段的值。 - ANNOTATION_LABEL:用于指示评估是合法还是欺诈性的标签。可能的值是
LEGITIMATE
或FRAUDULENT
。 - 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:用于指示评估是合法还是欺诈性的标签。可能的值是
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
将请求正文保存在名为
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) 和一个空响应。
- ASSESSMENT_ID:从