Crie avaliações para Websites

Esta página explica como criar uma avaliação para permitir que o back-end valide a autenticidade do token que o reCAPTCHA envia. O reCAPTCHA envia uma resposta encriptada, o token de resposta do reCAPTCHA (também conhecido como token), quando o utilizador final aciona uma ação HTML.

Para qualquer tipo de integração de chave do reCAPTCHA (caixa de verificação ou pontuação), tem de criar uma avaliação para avaliar os resultados de execute() no seu back-end através do envio do token gerado para o ponto final de avaliação. O reCAPTCHA processa o token enviado e comunica a validade e a pontuação do token.

As primeiras 10 000 avaliações mensais do reCAPTCHA são gratuitas. Para continuar a criar avaliações depois de atingir o limite de utilização mensal gratuito (10 000 avaliações por mês), tem de ativar a faturação para o seu Google Cloud projeto. Para mais informações sobre a faturação do reCAPTCHA, consulte as informações de faturação.

Antes de começar

  1. Prepare o seu ambiente para o reCAPTCHA.
  2. Certifique-se de que tem a seguinte função de gestão de acessos e identidade: Agente do reCAPTCHA Enterprise (roles/recaptchaenterprise.agent).
  3. Instale chaves baseadas em pontuação, chaves de caixa de verificação ou chaves de desafio baseadas em políticas no seu Website.
  4. Configure a autenticação para o reCAPTCHA.

    O método de autenticação que escolher depende do ambiente onde o reCAPTCHA está configurado. A tabela seguinte ajuda a escolher o método de autenticação adequado e a interface suportada para configurar a autenticação:

    Ambiente Interface Método de autenticação
    Google Cloud
    • REST
    • Bibliotecas cliente
    		 Use contas de serviço anexadas.
    Nas instalações ou num fornecedor de nuvem diferente REST Use chaves da API ou a Workload Identity Federation.

    Se quiser usar chaves da API, recomendamos que as proteja aplicando restrições de chaves da API.
    Bibliotecas cliente

    Use o seguinte:

Obtenha um token

Obtenha um token de páginas Web de uma das seguintes formas:

  • O valor resolvido da promessa devolvida pela chamada a grecaptcha.enterprise.execute().
  • Use o parâmetro g-recaptcha-response POST quando um utilizador enviar um formulário no seu site.
  • Como um argumento de string para a sua função de chamada de retorno se data-callback for especificado no g-recaptcha atributo da etiqueta HTML ou no parâmetro de chamada de retorno no método grecaptcha.enterprise.render.

Só pode aceder ao token de cada utilizador uma vez. Se precisar de avaliar uma ação subsequente que um utilizador realiza no seu site ou se um token expirar antes de ser criada uma avaliação, tem de chamar execute() novamente para gerar um novo token.

Crie uma avaliação

Depois de configurar a autenticação, crie uma avaliação enviando um pedido para a API reCAPTCHA Enterprise ou usando as bibliotecas de cliente do reCAPTCHA.

Para melhorar a deteção, recomendamos que transmita os seguintes valores adicionais quando criar avaliações:

  • userAgent: o agente do utilizador está incluído no pedido HTTP no cabeçalho do pedido. Para mais informações, consulte o artigo Saiba mais sobre o cabeçalho do pedido User-Agent na documentação da Mozilla Developer Network.
  • userIpAddress: o endereço IP do utilizador que envia um pedido para o seu back-end está disponível no pedido HTTP. Se usar um servidor proxy, o endereço IP está disponível no cabeçalho do pedido X-Forwarded-For. Para mais informações sobre como obter o endereço IP, consulte X-Forwarded-For.
  • ja4: JA4 é um método de código aberto para recolher impressões digitais de clientes TLS. Para mais informações sobre como criar uma impressão digital JA4, consulte a documentação do JA4 no GitHub.
  • ja3: O JA3 é um método de código aberto para recolher impressões digitais de clientes TLS. Para mais informações sobre como criar uma impressão digital JA3, consulte a documentação do JA3 no GitHub.

Isto ajuda a proteger o seu Website e aplicações para dispositivos móveis contra padrões de ataque avançados e abusos liderados por humanos.

A forma como cria uma avaliação é a mesma para as chaves baseadas em pontuação, as chaves de caixa de verificação e as chaves de desafio baseadas em políticas (pré-visualização).

API REST

Crie uma avaliação enviando um pedido para a API reCAPTCHA. Pode usar a CLI gcloud ou a chave da API para autenticação.

Use a CLI gcloud

Crie uma avaliação com o método projects.assessments.create. Envie este pedido para o ponto final da API v1.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu Google Cloud projeto
  • TOKEN: token devolvido pela chamada grecaptcha.enterprise.execute()
  • KEY_ID: a chave reCAPTCHA associada ao site ou à app. Para mais informações, consulte o artigo Chaves reCAPTCHA.
  • USER_AGENT: o agente do utilizador no pedido do dispositivo do utilizador.
  • USER_IP_ADDRESS: o endereço IP no pedido do dispositivo do utilizador.
  • JA4: impressão digital JA4 para o cliente TLS. Recomendamos a utilização de FoxIO-LLC/ja4 para calcular a impressão digital do JA4.
  • JA3: Impressão digital JA3 para o cliente TLS. Recomendamos a utilização do salesforce/ja3 para calcular a impressão digital JA3.
  • USER_ACTION: a ação iniciada pelo utilizador que especificou para action na chamada grecaptcha.enterprise.execute(), como login.

    Para mais informações, consulte Nomes de ações.

Método HTTP e URL: 

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments

Corpo JSON do pedido: 

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userAgent": "USER_AGENT",
    "userIpAddress": "USER_IP_ADDRESS",
    "ja4": "JA4",
    "ja3": "JA3",
    "expectedAction": "USER_ACTION"
  }
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

$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

Deve receber uma resposta JSON semelhante à seguinte:

{
  "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",
    "userAgent": "USER_AGENT",
    "userIpAddress": "USER_IP_ADDRESS",
    "ja4": "JA4",
    "ja3": "JA3",
    "expectedAction": "USER_ACTION"
  },
  "name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000"
}

Recomendamos que use analisadores JSON no modo de análise não rigorosa para evitar interrupções se forem introduzidos campos adicionais na resposta JSON.

Use uma chave da API

Crie uma avaliação com o método projects.assessments.create. Envie este pedido para o ponto final da API v1.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • API_KEY: chave da API associada ao projeto atual
  • PROJECT_ID: o ID do seu Google Cloud projeto
  • TOKEN: token devolvido pela chamada grecaptcha.enterprise.execute()
  • KEY_ID: a chave reCAPTCHA associada ao site ou à app. Para mais informações, consulte o artigo Chaves reCAPTCHA.
  • USER_AGENT: o agente do utilizador no pedido do dispositivo do utilizador.
  • USER_IP_ADDRESS: o endereço IP no pedido do dispositivo do utilizador.
  • JA3: impressão digital JA3 para o cliente SSL. Recomendamos que use salesforce/ja3 para calcular o JA3.
  • USER_ACTION: a ação iniciada pelo utilizador que especificou para action na chamada grecaptcha.enterprise.execute(), como login.

    Para mais informações, consulte Nomes de ações.

Método HTTP e URL: 

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

Corpo JSON do pedido: 

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userAgent": "USER_AGENT",
    "userIpAddress": "USER_IP_ADDRESS",
    "ja3": "JA3",
    "expectedAction": "USER_ACTION"
  }
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

$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

Deve receber uma resposta JSON semelhante à seguinte:

{
  "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",
    "userAgent": "USER_AGENT",
    "userIpAddress": "USER_IP_ADDRESS",
    "ja3": "JA3",
    "expectedAction": "USER_ACTION"
  },
  "name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000"
}

Recomendamos que use analisadores JSON no modo de análise não rigorosa para evitar interrupções se forem introduzidos campos adicionais na resposta 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 a UI action.
      // projectID: Google Cloud project ID.
      // recaptchaKey: reCAPTCHA key obtained by registering a domain or an app to use reCAPTCHA Enterprise.
      // token: The token obtained from the client on passing the recaptchaKey.
      // recaptchaAction: Action name corresponding to the token.
      public void createAssessment(string projectID = "project-id", string recaptchaKey = "recaptcha-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 = recaptchaKey,
                      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 reasons.
          // 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/v2/apiv1"
    recaptchapb "cloud.google.com/go/recaptchaenterprise/v2/apiv1/recaptchaenterprisepb"
  )

  func main() {
    // TODO(developer): Replace these variables before running the sample.
    projectID := "project-id"
    recaptchaKey := "recaptcha-key"
    token := "action-token"
    recaptchaAction := "action-name"

    createAssessment(projectID, recaptchaKey, token, recaptchaAction)
  }

  /**
  * Create an assessment to analyze the risk of a UI action.
  *
  * @param projectID: Google Cloud project ID
  * @param recaptchaKey: reCAPTCHA key obtained by registering a domain or an app to use the services of reCAPTCHA Enterprise.
  * @param token: The token obtained from the client on passing the recaptchaKey.
  * @param recaptchaAction: Action name corresponding to the token.
  */
  func createAssessment(projectID string, recaptchaKey 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:        recaptchaKey,
    }

    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


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";
    String userIpAddress = "user-ip-address";
    String userAgent = "user-agent";
    String ja3 = "ja3";
    String ja4 = "ja4";

    createAssessment(projectID, recaptchaSiteKey, token, recaptchaAction, userIpAddress, userAgent, ja3, ja4);
  }

  /**
   * Create an assessment to analyze the risk of an UI action. Assessment approach is the same for
   * both 'score' and 'checkbox' type recaptcha site keys.
   *
   * @param projectID : GCloud Project ID
   * @param recaptchaSiteKey : Site key obtained by registering a domain/app to use recaptcha
   *     services. (score/ checkbox type)
   * @param token : The token obtained from the client on passing the recaptchaSiteKey.
   * @param recaptchaAction : Action name corresponding to the token.
   * @param userIpAddress: IP address of the user sending a request.
   * @param userAgent: User agent is included in the HTTP request in the request header. 
   * @param ja3: JA3 associated with the request.
   * @param ja4: JA4 associated with the request.
   */
  public static void createAssessment(
      String projectID, String recaptchaSiteKey, String token, String recaptchaAction, String userIpAddress, String userAgent, String ja3, String ja4)
      throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // 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)
          .setUserIpAddress(userIpAddress)
          .setJa3(ja3)
          .setJa4(ja4)
          .setUserAgent(userAgent)
          .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 reCAPTCHA tag is: "
                + response.getTokenProperties().getAction());
        System.out.println(
            "The action attribute in the reCAPTCHA tag "
                + "does not match the action ("
                + recaptchaAction
                + ") you are expecting to score");
        return;
      }

      // Get the reason(s) and the risk score.
      // For more information on interpreting the assessment,
      // see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
      for (ClassificationReason reason : response.getRiskAnalysis().getReasonsList()) {
        System.out.println(reason);
      }

      float recaptchaScore = response.getRiskAnalysis().getScore();
      System.out.println("The reCAPTCHA score is: " + recaptchaScore);

      // Get the assessment name (id). Use this to annotate the assessment.
      String assessmentName = response.getName();
      System.out.println(
          "Assessment name: " + assessmentName.substring(assessmentName.lastIndexOf("/") + 1));
    }
  }
}

Node.js

  const {RecaptchaEnterpriseServiceClient} =
      require('@google-cloud/recaptcha-enterprise');

 /**
 * Create an assessment to analyze the risk of a UI action. Note that
 * this example does set error boundaries and returns `null` for
 * exceptions.
 *
 * projectID: Google Cloud project ID
 * recaptchaKey: reCAPTCHA key obtained by registering a domain or an app to use the services of reCAPTCHA Enterprise.
 * token: The token obtained from the client on passing the recaptchaKey.
 * recaptchaAction: Action name corresponding to the token.
 * userIpAddress: The IP address of the user sending a request to your backend is available in the HTTP request.
 * userAgent: The user agent is included in the HTTP request in the request header.
 * ja4: JA4 fingerprint associated with the request.
 * ja3: JA3 fingerprint associated with the request.
 */
 async function createAssessment({
   projectID = "your-project-id",
   recaptchaKey = "your-recaptcha-key",
   token = "action-token",
   recaptchaAction = "action-name",
   userIpAddress = "user-ip-address",
   userAgent = "user-agent",
   ja4 = "ja4"
   ja3 = "ja3"
 }) {
   // 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: recaptchaKey,
         userIpAddress: userIpAddress,
         userAgent: userAgent,
         ja4: ja4,
         ja3: ja3,
       },
     },
     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
  // composer require google/cloud-recaptcha-enterprise
  require 'vendor/autoload.php';

  use Google\Cloud\RecaptchaEnterprise\V1\Client\RecaptchaEnterpriseServiceClient;
  use Google\Cloud\RecaptchaEnterprise\V1\Event;
  use Google\Cloud\RecaptchaEnterprise\V1\Assessment;
  use Google\Cloud\RecaptchaEnterprise\V1\CreateAssessmentRequest;
  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);

     $request = (new CreateAssessmentRequest())
         ->setParent($projectName)
         ->setAssessment($assessment);

     try {
         $response = $client->createAssessment($request);

         // 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_KEY',
     'YOUR_USER_RESPONSE_TOKEN',
     'YOUR_GOOGLE_CLOUD_PROJECT_ID'
  );
?>

Python


from google.cloud import recaptchaenterprise_v1
from google.cloud.recaptchaenterprise_v1 import Assessment


def create_assessment(
    project_id: str,
    recaptcha_site_key: str,
    token: str,
    recaptcha_action: str,
    user_ip_address: str,
    user_agent: str,
    ja3: str,
) -> Assessment:
    """Create an assessment to analyze the risk of a UI action.
    Args:
        project_id: GCloud Project ID
        recaptcha_site_key: Site key obtained by registering a domain/app to use recaptcha services.
        token: The token obtained from the client on passing the recaptchaSiteKey.
        recaptcha_action: Action name corresponding to the token.
        user_ip_address: IP address of the user sending a request.
        user_agent: User agent is included in the HTTP request in the request header.
        ja3: JA3 associated with the request.
    """

    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
    event.user_ip_address = user_ip_address
    event.user_agent = user_agent
    event.ja3 = ja3

    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)
        )
        return

    # Check if the expected action was executed.
    if response.token_properties.action != recaptcha_action:
        print(
            "The action attribute in your reCAPTCHA tag does"
            + "not match the action you are expecting to score"
        )
        return
    else:
        # 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
        for reason in response.risk_analysis.reasons:
            print(reason)
        print(
            "The reCAPTCHA score for this token is: "
            + str(response.risk_analysis.score)
        )
        # Get the assessment name (id). Use this to annotate the assessment.
        assessment_name = client.parse_assessment_path(response.name).get("assessment")
        print(f"Assessment name: {assessment_name}")
    return response

Ruby

require "google/cloud/recaptcha_enterprise"

# Create an assessment to analyze the risk of a UI action.
#
# @param site_key [String] Site key obtained by registering a domain/app to use recaptcha services.
# @param token [String] The token obtained from the client on passing the recaptcha site_key.
# @param project_id [String] GCloud Project ID.
# @param recaptcha_action [String] Action name corresponding to the token.
# @return [void]
def create_assessment site_key:, token:, project_id:, recaptcha_action:
  # Create the reCAPTCHA client.
  client = ::Google::Cloud::RecaptchaEnterprise.recaptcha_enterprise_service

  request = { parent: "projects/#{project_id}",
              assessment: {
                event: {
                  site_key: site_key,
                  token: token
                }
              } }

  response = client.create_assessment request

  # Check if the token is valid.
  if !response.token_properties.valid
    puts "The create_assessment() call failed because the token was invalid with the following reason:" \
         "#{response.token_properties.invalid_reason}"
  # Check if the expected action was executed.
  elsif 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
    puts "The reCAPTCHA score for this token is: #{response.risk_analysis.score}"
    response.risk_analysis.reasons.each { |reason| puts reason }
  else
    puts "The action attribute in your reCAPTCHA tag does not match the action you are expecting to score"
  end
end

O que se segue?