创建评估

当最终用户触发 HTML 操作时,reCAPTCHA Enterprise 会将加密响应(称为用户响应令牌,简称令牌)发送到最终用户的浏览器。对于任何类型的网站密钥集成(复选框或得分),您必须通过将生成的令牌提交到评估端点来创建评估。reCAPTCHA Enterprise 会处理提交的令牌,并报告令牌的有效性和得分。

本页面介绍了如何检索令牌并创建评估。

准备工作

选择在您的环境中设置 reCAPTCHA Enterprise 的最佳方法,并完成设置。

检索用户的响应令牌

通过下列任一方式从网页中检索用户的响应令牌:

  • 调用 grecaptcha.enterprise.execute() 返回的 promise 的解析值。
  • 用户在您的网站上提交表单时的 g-recaptcha-response POST 参数。
  • 作为回调函数的字符串参数(如果在 g-recaptcha HTML 标记属性中或在 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(使用 gcloud 工具进行身份验证)
  • reCAPTCHA Enterprise 客户端库
支持服务帐号的第三方云或本地环境

以下任意一个:

  • reCAPTCHA Enterprise REST API(使用 gcloud 工具进行身份验证)
  • reCAPTCHA Enterprise 客户端库
不支持服务帐号的第三方云或本地环境 reCAPTCHA Enterprise REST API(使用 API 密钥进行身份验证)
使用额外的 reCAPTCHA Enterprise 功能(例如多重身份验证 (MFA))的迁移环境

以下任意一个:

  • reCAPTCHA Enterprise REST API(使用 gcloud 工具进行身份验证)
  • reCAPTCHA Enterprise REST API(使用 API 密钥进行身份验证)

使用 REST API 或客户端库创建评估

选择创建评估的适当方法后,请执行以下步骤以创建评估。 对于基于分数的网站密钥和复选框网站密钥,创建评估的方法是相同的。

REST API

向 reCAPTCHA Enterprise API 发送请求以创建评估。您可以使用 gcloud 工具或 API 密钥进行身份验证。

使用 gcloud 工具进行身份验证

使用 projects.assessments.create 方法创建评估。将此请求发送至 v1 API 端点。

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

  • PROJECT_ID:您的 Google Cloud 项目 ID
  • TOKEN:从 grecaptcha.enterprise.execute() 调用返回的令牌
  • KEY:与网站/应用关联的 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",
    "expectedAction": "USER_ACTION"
  }
}

如需发送请求,请选择以下方式之一:

curl

将请求正文保存在名为 request.json 的文件中,然后执行以下命令:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default 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 application-default 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",
    "expectedAction": "USER_ACTION"
  },
  "name": "projects/PROJECT_ID/assessments/b6ac310000000000"
}

使用 API 密钥进行身份验证

使用 projects.assessments.create 方法创建评估。将此请求发送至 v1beta1 API 端点。

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

  • API_KEY:与当前项目关联的 API 密钥
  • PROJECT_ID:您的 Google Cloud 项目 ID
  • TOKEN:从 grecaptcha.enterprise.execute() 调用返回的令牌
  • KEY:与网站/应用关联的 reCAPTCHA 密钥
  • USER_ACTION(仅适用于基于得分的网站密钥集成):您在 grecaptcha.enterprise.execute() 调用中为 action 指定的用户发起的操作,例如 login。如需了解详情,请参阅操作

HTTP 方法和网址:

POST https://recaptchaenterprise.googleapis.com/v1beta1/projects/PROJECT_ID/assessments?key=API_KEY

请求 JSON 正文:

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY",
    "expectedAction": "USER_ACTION"
  }
}

如需发送请求,请选择以下方式之一:

curl

将请求正文保存在名为 request.json 的文件中,然后执行以下命令:

curl -X POST \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1beta1/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/v1beta1/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"
   },
  "score": 0.1,
  "reasons": ["AUTOMATION"],
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY",
    "expectedAction": "USER_ACTION"
  },
  "name": "projects/PROJECT_ID//assessments/b6ac310000000000"
}

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: Site 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.
           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-enterprise/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: Site 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.
     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-enterprise/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

   import com.google.cloud.recaptchaenterprise.v1.RecaptchaEnterpriseServiceClient;
   import com.google.recaptchaenterprise.v1.Assessment;
   import com.google.recaptchaenterprise.v1.CreateAssessmentRequest;
   import com.google.recaptchaenterprise.v1.Event;
   import com.google.recaptchaenterprise.v1.ProjectName;
   import com.google.recaptchaenterprise.v1.RiskAnalysis.ClassificationReason;
   import java.io.IOException;

   public class CreateAssessment {

     public static void main(String[] args) throws IOException {
       // TODO(developer): Replace these variables before running the sample.
       String projectID = "project-id";
       String recaptchaSiteKey = "recaptcha-site-key";
       String token = "action-token";
       String 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: Site 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.
      */
     public static void createAssessment(String projectID, String recaptchaSiteKey, String token,
         String recaptchaAction)
         throws IOException {
       // Initialize a client that will be used to send requests. This client needs to be created only
       // once, and can be reused for multiple requests. After completing all of your requests, call
       // the `client.close()` method on the client to safely
       // clean up any remaining background resources.
       try (RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.create()) {

         // Set the properties of the event to be tracked.
         Event event = Event.newBuilder()
             .setSiteKey(recaptchaSiteKey)
             .setToken(token)
             .build();

         // Build the assessment request.
         CreateAssessmentRequest createAssessmentRequest = CreateAssessmentRequest.newBuilder()
             .setParent(ProjectName.of(projectID).toString())
             .setAssessment(Assessment.newBuilder().setEvent(event).build())
             .build();

         Assessment response = client.createAssessment(createAssessmentRequest);

         // Check if the token is valid.
         if (!response.getTokenProperties().getValid()) {
           System.out.println("The CreateAssessment call failed because the token was: " +
              response.getTokenProperties().getInvalidReason().name());
           return;
         }

         // Check if the expected action was executed.
         // (If the key is checkbox type and 'action' attribute wasn't set, skip this check.)
         if (!response.getTokenProperties().getAction().equals(recaptchaAction)) {
           System.out.println("The action attribute in your 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-enterprise/docs/interpret-assessment
         float recaptchaScore = response.getRiskAnalysis().getScore();
         System.out.println("The reCAPTCHA score is: " + recaptchaScore);

         for (ClassificationReason reason : response.getRiskAnalysis().getReasonsList()) {
           System.out.println(reason);
         }
       }
     }
   }

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: Site 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
     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-enterprise/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-enterprise/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-enterprise/docs/create-assessment#retrieve_token)
   * @param string $project Your Google Cloud project ID
   */
   function create_assessment(
      string $siteKey,
      string $token,
      string $project
   ): void {
      $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

  from google.cloud import recaptchaenterprise_v1

  def create_assessment():
     """ Create an assessment to analyze the risk of a UI action.

     Args:
     projectID: GCloud Project ID
     recaptchaSiteKey: Site 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.
     """
     # TODO(developer): Replace these variables before running the sample.
     project_id = "your_project_id"
     recaptcha_site_key = "your_site_key"
     token = "action_token"
     recaptcha_action = "action_name"

     client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()

     # Set the properties of the event to be tracked.
     event = recaptchaenterprise_v1.Event()
     event.site_key = recaptcha_site_key
     event.token = token

     assessment = recaptchaenterprise_v1.Assessment()
     assessment.event = event

     project_name = f'projects/{project_id}'

     # Build the assessment request.
     request = recaptchaenterprise_v1.CreateAssessmentRequest()
     request.assessment = assessment
     request.parent = project_name

     response = client.create_assessment(request)

     # Check if the token is valid.
     if not response.token_properties.valid:
         print("The CreateAssessment call failed because the token was " +
               "invalid for for the following reasons: "
               + str(response.token_properties.invalid_reason))
     else:
         # Check if the expected action was executed.
         if response.token_properties.action == recaptcha_action:
             # Get the risk score and the reason(s)
             # For more information on interpreting the assessment,
             # see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
             print("The reCAPTCHA score for this token is: " +
                   str(response.risk_analysis.score))
             for reason in response.risk_analysis.reasons:
                 print(reason)
         else:
             print("The action attribute in your reCAPTCHA tag does " +
                   "not match the action you are expecting to score")

Ruby

  require "google/cloud/recaptcha_enterprise/v1"

  siteKey = "your_site_key"
  token = "user_response_token"
  parent_project = "projects/your_project_name"
  recaptcha_action = "name_of_action_to_protect"

  client = ::Google::Cloud::RecaptchaEnterprise::V1::RecaptchaEnterpriseService::Client.new

  event = ::Google::Cloud::RecaptchaEnterprise::V1::Event.new
  event.site_key = siteKey
  event.token = token
  event.expected_action = recaptcha_action

  assessment = ::Google::Cloud::RecaptchaEnterprise::V1::Assessment.new
  assessment.event = event

  request = ::Google::Cloud::RecaptchaEnterprise::V1::CreateAssessmentRequest.new
  request.parent = parent_project
  request.assessment = assessment

  response = client.create_assessment(request)

  if response.token_properties.valid == false
    printf("The CreateAssessment() call failed because the token was invalid with the following reason: %s ", response.token_properties.invalid_reason)
  else
    if response.event.expected_action == recaptcha_action
      printf("The reCAPTCHA score for this token is: %s" + response.risk+analysis.score)
    else
      printf("The action attribute in your reCAPTCHA tag does not match the action you are expecting to score")
    end
  end

后续步骤

  • 解读评估,并根据得分对您的网站采取适当的措施。