本文档介绍了如何创建评估，让您的后端能够验证 reCAPTCHA Enterprise 发送的令牌的真实性。reCAPTCHA Enterprise 会在最终用户触发 HTML 操作时发送名为“令牌”的加密响应。
对于任何类型的 reCAPTCHA 密钥集成（复选框或得分），您必须创建评估以评估后端中 execute() 的结果。您可以通过将生成的令牌提交到评估端点来创建评估。reCAPTCHA Enterprise 会处理提交的令牌，并报告令牌的有效性和得分。
每月前 100 万次 reCAPTCHA Enterprise 评估免费。如需在达到每月免费的用量限额（每月 100 万个评估）后继续创建评估，您必须为 Google Cloud 项目启用结算功能。如需详细了解 reCAPTCHA Enterprise 的结算信息，请参阅结算信息。
须知事项
选择在您的环境中设置 reCAPTCHA Enterprise 的最佳方法，并完成设置。
检索用户的响应令牌
通过下列任一方式从网页中检索用户的响应令牌：
- 调用
grecaptcha.enterprise.execute()返回的 promise 的解析值。 - 用户在您的网站上提交表单时的
g-recaptcha-responsePOST 参数。 - 作为回调函数的字符串参数（如果在
g-recaptchaHTML 标记属性中或在grecaptcha.enterprise.render方法中的回调参数中指定了data-callback）。
要从移动应用检索用户的响应令牌，请参阅将 reCAPTCHA Enterprise 与 iOS 应用集成或将 reCAPTCHA Enterprise 与 Android 应用集成。
您只能访问每个用户的 reCAPTCHA 响应令牌一次。如果您需要评估用户在您的网站上执行的后续操作，或者在创建评估之前令牌已过期，则必须再次调用 execute() 以生成新的令牌。
创建评估
请通过向 reCAPTCHA Enterprise API 发送请求或使用 reCAPTCHA Enterprise 客户端库来创建评估。我们建议您根据已设置 reCAPTCHA Enterprise 的位置来选择创建评估的方式。
选择如何创建评估
可用于创建评估的方法取决于您的环境。下表列出了受支持的环境及其相应的评估方法：
| 环境 | 创建评估的方式 |
|---|---|
| Google Cloud App Engine 或 GKE | reCAPTCHA Enterprise 客户端库 |
| Google Cloud Compute Engine | 以下任意一个：
|
| 支持服务账号的第三方云或本地环境 | 以下任意一个：
|
| 不支持服务账号的第三方云或本地环境 | reCAPTCHA Enterprise REST API（使用 API 密钥进行身份验证） |
| 使用额外的 reCAPTCHA Enterprise 功能（例如多重身份验证 (MFA)）的迁移环境 | 以下任意一个：
|
使用 REST API 或客户端库创建评估
选择创建评估的适当方法后，请执行以下步骤以创建评估。 对于基于得分的键和复选框键，创建评估的方式相同。
REST API
向 reCAPTCHA Enterprise API 发送请求以创建评估。您可以使用 gcloud CLI 或 API 密钥进行身份验证。
使用 gcloud CLI 进行身份验证
使用 projects.assessments.create 方法创建评估。将此请求发送至 v1 API 端点。
在使用任何请求数据之前，请先进行以下替换：
- PROJECT_ID：您的 Google Cloud 项目 ID
- TOKEN：从
grecaptcha.enterprise.execute()调用返回的令牌 - KEY_ID：与网站或应用关联的 reCAPTCHA 密钥。如需了解详情，请参阅 reCAPTCHA 密钥。
- USER_ACTION：您在
grecaptcha.enterprise.execute()调用中为action指定的用户发起的操作，例如login。
HTTP 方法和网址：
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments
请求 JSON 正文：
{
"event": {
"token": "TOKEN",
"siteKey": "KEY_ID",
"expectedAction": "USER_ACTION"
}
}
如需发送请求，请选择以下方式之一：
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/projects/PROJECT_ID/assessments"
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/projects/PROJECT_ID/assessments" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应：
{
"tokenProperties": {
"valid": true,
"hostname": "www.google.com",
"action": "homepage",
"createTime": "2019-03-28T12:24:17.894Z"
},
"riskAnalysis": {
"score": 0.1,
"reasons": ["AUTOMATION"]
},
"event": {
"token": "TOKEN",
"siteKey": "KEY_ID",
"expectedAction": "USER_ACTION"
},
"name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000"
}
我们建议以非严格解析模式使用任何 JSON 解析器，以免在 JSON 响应中引入任何其他字段时发生服务中断。
使用 API 密钥进行身份验证
使用 projects.assessments.create 方法创建评估。
本文档介绍了如何将 API 密钥作为查询参数传入 REST API 调用。您还可以使用 x-goog-api-key 标头通过 gRPC 请求传递 API 密钥。如需详细了解如何使用 x-goog-api-key header，请参阅使用 API 密钥。
在使用任何请求数据之前，请先进行以下替换：
- API_KEY：与当前项目关联的 API 密钥
- PROJECT_ID：您的 Google Cloud 项目 ID
- TOKEN：从
grecaptcha.enterprise.execute()调用返回的令牌 - KEY_ID：与网站或应用关联的 reCAPTCHA 密钥。如需了解详情，请参阅 reCAPTCHA 密钥。
- USER_ACTION：您在
grecaptcha.enterprise.execute()调用中为action指定的用户发起的操作，例如login。
HTTP 方法和网址：
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY
请求 JSON 正文：
{
"event": {
"token": "TOKEN",
"siteKey": "KEY_ID",
"expectedAction": "USER_ACTION"
}
}
如需发送请求，请选择以下方式之一：
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?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?key=API_KEY" | Select-Object -Expand Content您应该收到类似以下内容的 JSON 响应：
{
"tokenProperties": {
"valid": true,
"hostname": "www.google.com",
"action": "homepage",
"createTime": "2019-03-28T12:24:17.894Z"
},
"riskAnalysis": {
"score": 0.1,
"reasons": ["AUTOMATION"]
},
"event": {
"token": "TOKEN",
"siteKey": "KEY_ID",
"expectedAction": "USER_ACTION"
},
"name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000"
}
我们建议以非严格解析模式使用任何 JSON 解析器，以防止在 JSON 响应中引入任何其他字段时发生服务中断。
C#
using System;
using Google.Api.Gax.ResourceNames;
using Google.Cloud.RecaptchaEnterprise.V1;
public class CreateAssessmentSample
{
// Create an assessment to analyze the risk of an UI action.
// projectID: GCloud Project ID.
// recaptchaSiteKey: reCAPTCHA key obtained by registering a domain/app to use recaptcha.
// token: The token obtained from the client on passing the recaptchaSiteKey.
// recaptchaAction: Action name corresponding to the token.
public void createAssessment(string projectID = "project-id", string recaptchaSiteKey = "recaptcha-site-key",
string token = "action-token", string recaptchaAction = "action-name")
{
// Create the client.
// TODO: To avoid memory issues, move this client generation outside
// of this example, and cache it (recommended) or call client.close()
// before exiting this method.
RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.Create();
ProjectName projectName = new ProjectName(projectID);
// Build the assessment request.
CreateAssessmentRequest createAssessmentRequest = new CreateAssessmentRequest()
{
Assessment = new Assessment()
{
// Set the properties of the event to be tracked.
Event = new Event()
{
SiteKey = recaptchaSiteKey,
Token = token,
ExpectedAction = recaptchaAction
},
},
ParentAsProjectName = projectName
};
Assessment response = client.CreateAssessment(createAssessmentRequest);
// Check if the token is valid.
if (response.TokenProperties.Valid == false)
{
System.Console.WriteLine("The CreateAssessment call failed because the token was: " +
response.TokenProperties.InvalidReason.ToString());
return;
}
// Check if the expected action was executed.
if (response.TokenProperties.Action != recaptchaAction)
{
System.Console.WriteLine("The action attribute in reCAPTCHA tag is: " +
response.TokenProperties.Action.ToString());
System.Console.WriteLine("The action attribute in the reCAPTCHA tag does not " +
"match the action you are expecting to score");
return;
}
// Get the risk score and the reason(s).
// For more information on interpreting the assessment,
// see: https://cloud.google.com/recaptcha/docs/interpret-assessment
System.Console.WriteLine("The reCAPTCHA score is: " + ((decimal)response.RiskAnalysis.Score));
foreach (RiskAnalysis.Types.ClassificationReason reason in response.RiskAnalysis.Reasons)
{
System.Console.WriteLine(reason.ToString());
}
}
public static void Main(string[] args)
{
new CreateAssessmentSample().createAssessment();
}
}
Go
import (
"context"
"fmt"
recaptcha "cloud.google.com/go/recaptchaenterprise/apiv1"
recaptchapb "google.golang.org/genproto/googleapis/cloud/recaptchaenterprise/v1"
)
func main() {
// TODO(developer): Replace these variables before running the sample.
projectID := "project-id"
recaptchaSiteKey := "recaptcha-site-key"
token := "action-token"
recaptchaAction := "action-name"
createAssessment(projectID, recaptchaSiteKey, token, recaptchaAction)
}
/**
* Create an assessment to analyze the risk of an UI action.
*
* @param projectID: GCloud Project ID
* @param recaptchaSiteKey: reCAPTCHA key obtained by registering a domain/app to use recaptcha services.
* @param token: The token obtained from the client on passing the recaptchaSiteKey.
* @param recaptchaAction: Action name corresponding to the token.
*/
func createAssessment(projectID string, recaptchaSiteKey string, token string, recaptchaAction string) {
// Create the recaptcha client.
// TODO: To avoid memory issues, move this client generation outside
// of this example, and cache it (recommended) or call client.close()
// before exiting this method.
ctx := context.Background()
client, err := recaptcha.NewClient(ctx)
if err != nil {
fmt.Printf("Error creating reCAPTCHA client\n")
}
defer client.Close()
// Set the properties of the event to be tracked.
event := &recaptchapb.Event{
Token: token,
SiteKey: recaptchaSiteKey,
}
assessment := &recaptchapb.Assessment{
Event: event,
}
// Build the assessment request.
request := &recaptchapb.CreateAssessmentRequest{
Assessment: assessment,
Parent: fmt.Sprintf("projects/%s", projectID),
}
response, err := client.CreateAssessment(
ctx,
request)
if err != nil {
fmt.Printf("%v", err.Error())
}
// Check if the token is valid.
if response.TokenProperties.Valid == false {
fmt.Printf("The CreateAssessment() call failed because the token"+
" was invalid for the following reasons: %v",
response.TokenProperties.InvalidReason)
return
}
// Check if the expected action was executed.
if response.TokenProperties.Action == recaptchaAction {
// Get the risk score and the reason(s).
// For more information on interpreting the assessment,
// see: https://cloud.google.com/recaptcha/docs/interpret-assessment
fmt.Printf("The reCAPTCHA score for this token is: %v",
response.RiskAnalysis.Score)
for _,reason := range response.RiskAnalysis.Reasons {
fmt.Printf(reason.String()+"\n")
}
return
}
fmt.Printf("The action attribute in your reCAPTCHA tag does " +
"not match the action you are expecting to score")
}
Java
Node.js
const {RecaptchaEnterpriseServiceClient} =
require('@google-cloud/recaptcha-enterprise');
/**
* Create an assessment to analyze the risk of an UI action. Note that
* this example does set error boundaries and returns `null` for
* exceptions.
*
* projectID: GCloud Project ID
* recaptchaSiteKey: reCAPTCHA key obtained by registering a domain/app to use recaptcha services.
* token: The token obtained from the client on passing the recaptchaSiteKey.
* recaptchaAction: Action name corresponding to the token.
*/
async function createAssessment({
projectID = "your-project-id",
recaptchaSiteKey = "your-recaptcha-site-key",
token = "action-token",
recaptchaAction = "action-name",
}) {
// Create the reCAPTCHA client & set the project path. There are multiple
// ways to authenticate your client. For more information see:
// https://cloud.google.com/docs/authentication
// TODO: To avoid memory issues, move this client generation outside
// of this example, and cache it (recommended) or call client.close()
// before exiting this method.
const client = new RecaptchaEnterpriseServiceClient();
const projectPath = client.projectPath(projectID);
// Build the assessment request.
const request = ({
assessment: {
event: {
token: token,
siteKey: recaptchaSiteKey,
},
},
parent: projectPath,
});
// client.createAssessment() can return a Promise or take a Callback
const [ response ] = await client.createAssessment(request);
// Check if the token is valid.
if (!response.tokenProperties.valid) {
console.log("The CreateAssessment call failed because the token was: " +
response.tokenProperties.invalidReason);
return null;
}
// Check if the expected action was executed.
// The `action` property is set by user client in the
// grecaptcha.enterprise.execute() method.
if (response.tokenProperties.action === recaptchaAction) {
// Get the risk score and the reason(s).
// For more information on interpreting the assessment,
// see: https://cloud.google.com/recaptcha/docs/interpret-assessment
console.log("The reCAPTCHA score is: " +
response.riskAnalysis.score);
response.riskAnalysis.reasons.forEach((reason) => {
console.log(reason);
});
return response.riskAnalysis.score;
} else {
console.log("The action attribute in your reCAPTCHA tag " +
"does not match the action you are expecting to score");
return null;
}
}
PHP
<?php
// Include Google Cloud dependencies using Composer
require 'vendor/autoload.php';
use Google\Cloud\RecaptchaEnterprise\V1\RecaptchaEnterpriseServiceClient;
use Google\Cloud\RecaptchaEnterprise\V1\Event;
use Google\Cloud\RecaptchaEnterprise\V1\Assessment;
use Google\Cloud\RecaptchaEnterprise\V1\TokenProperties\InvalidReason;
/**
* Create an assessment to analyze the risk of a UI action.
* @param string $siteKey The key ID for the reCAPTCHA key (See https://cloud.google.com/recaptcha/docs/create-key)
* @param string $token The user's response token for which you want to receive a reCAPTCHA score. (See https://cloud.google.com/recaptcha/docs/create-assessment#retrieve_token)
* @param string $project Your Google Cloud project ID
*/
function create_assessment(
string $siteKey,
string $token,
string $project
): void {
// TODO: To avoid memory issues, move this client generation outside
// of this example, and cache it (recommended) or call client.close()
// before exiting this method.
$client = new RecaptchaEnterpriseServiceClient();
$projectName = $client->projectName($project);
$event = (new Event())
->setSiteKey($siteKey)
->setToken($token);
$assessment = (new Assessment())
->setEvent($event);
try {
$response = $client->createAssessment(
$projectName,
$assessment
);
// You can use the score only if the assessment is valid,
// In case of failures like re-submitting the same token, getValid() will return false
if ($response->getTokenProperties()->getValid() == false) {
printf('The CreateAssessment() call failed because the token was invalid for the following reason: ');
printf(InvalidReason::name($response->getTokenProperties()->getInvalidReason()));
} else {
printf('The score for the protection action is:');
printf($response->getRiskAnalysis()->getScore());
// Optional: You can use the following methods to get more data about the token
// Action name provided at token generation.
// printf($response->getTokenProperties()->getAction() . PHP_EOL);
// The timestamp corresponding to the generation of the token.
// printf($response->getTokenProperties()->getCreateTime()->getSeconds() . PHP_EOL);
// The hostname of the page on which the token was generated.
// printf($response->getTokenProperties()->getHostname() . PHP_EOL);
}
} catch (exception $e) {
printf('CreateAssessment() call failed with the following error: ');
printf($e);
}
}
// TODO(Developer): Replace the following before running the sample
create_assessment(
'YOUR_RECAPTCHA_SITE_KEY',
'YOUR_USER_RESPONSE_TOKEN',
'YOUR_GOOGLE_CLOUD_PROJECT_ID'
);
?>
Python
Ruby
后续步骤
- 解读评估，并根据得分对您的网站采取适当的措施。