Quando o usuário final aciona uma ação HTML, o reCAPTCHA Enterprise envia uma resposta criptografada, chamada de token de resposta (token) do usuário, para o navegador do usuário final. Para qualquer tipo de integração de chave de site (caixa de seleção ou pontuação), é necessário criar uma avaliação enviando o token gerado para o endpoint da avaliação. O reCAPTCHA Enterprise processa o token enviado e informa a validade e a pontuação dele.
Neste documento, explicamos como recuperar o token e criar uma avaliação. O primeiro milhão de avaliações mensais do reCAPTCHA Enterprise é gratuito. É possível criar um milhão de avaliações por mês sem ativar o faturamento do seu projeto do Google Cloud.
Antes de começar
Escolha o melhor método para configurar o reCAPTCHA Enterprise no ambiente e conclua a configuração.
Recuperar o token de resposta do usuário
O token de resposta do usuário das páginas da Web pode ser recuperado de uma das seguintes maneiras:
- O valor resolvido da promessa retornada pela chamada para
grecaptcha.enterprise.execute(). - Parâmetro POST
g-recaptcha-responsequando um usuário envia o formulário no seu site. - Como um argumento de sequência de caracteres para sua função de callback, se
data-callbackfor especificado no atributo de tag HTMLg-recaptchaou no parâmetro de callback no métodogrecaptcha.enterprise.render.
Para recuperar o token de resposta do usuário de aplicativos para dispositivos móveis, consulte Como integrar o reCAPTCHA Enterprise com apps iOS ou Como integrar o reCAPTCHA Enterprise com apps Android.
É possível acessar o token de resposta reCAPTCHA de cada usuário apenas uma vez.
Se você precisar avaliar uma ação subsequente realizada por um usuário no seu site
ou se um token expirar antes de criar uma avaliação, será necessário chamar execute()
novamente para gerar um novo token.
Criar uma avaliação
Para criar uma avaliação, envie uma solicitação para a API reCAPTCHA Enterprise ou use as bibliotecas de cliente do reCAPTCHA Enterprise. Recomendamos que você escolha o método para criar uma avaliação com base no local em que configurou o reCAPTCHA Enterprise.
Escolher como criar uma avaliação
Os métodos que você pode usar para criar uma avaliação dependem do ambiente. A tabela a seguir lista os ambientes compatíveis e os métodos de avaliação correspondentes:
| Ambiente | Métodos para criar uma avaliação |
|---|---|
| Google Cloud App Engine ou GKE | Bibliotecas de cliente do reCAPTCHA Enterprise |
| Google Cloud Compute Engine | Uma das seguintes:
|
| Nuvem de terceiros ou local com suporte a contas de serviço | Uma das seguintes:
|
| Nuvem de terceiros ou local incompatível com contas de serviço | API REST reCAPTCHA Enterprise que usa chaves de API para autenticação |
| Ambiente migrado usando recursos extras do reCAPTCHA Enterprise, como autenticação multifator (MFA, na sigla em inglês) | Uma das seguintes:
|
Criar uma avaliação usando a API REST ou as bibliotecas de cliente
Depois de selecionar o método apropriado para criar uma avaliação, execute as etapas a seguir para criar uma avaliação. O método de criar uma avaliação é igual para chaves de site baseadas em pontuação e com caixa de seleção.
API REST
Para criar uma avaliação, envie uma solicitação para a API reCAPTCHA Enterprise. É possível usar a CLI da gcloud ou a chave de API para autenticação.
Autenticar com a CLI gcloud
Crie uma avaliação usando
o método
projects.assessments.create. Envie a solicitação para o endpoint da API v1.
Antes de usar qualquer um dos dados da solicitação, faça as seguintes substituições:
- PROJECT_ID: é o ID do projeto do Google Cloud.
- TOKEN: token retornado da chamada
grecaptcha.enterprise.execute() - KEY: chave reCAPTCHA associada ao site ou app. Para mais informações, consulte Chaves reCAPTCHA.
- USER_ACTION (somente para integrações de chave de site baseadas em pontuação): a ação iniciada pelo usuário que você especificou para
actionna chamadagrecaptcha.enterprise.execute(), comologin. Para mais informações, consulte Ações.
Método HTTP e URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments
Corpo JSON da solicitação:
{
"event": {
"token": "TOKEN",
"siteKey": "KEY",
"expectedAction": "USER_ACTION"
}
}
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo chamado request.json
e execute o seguinte comando:
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
Salve o corpo da solicitação em um arquivo chamado request.json
e execute o seguinte comando:
$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
Você receberá uma resposta JSON semelhante a esta:
{
"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"
}
Recomendamos o uso de qualquer analisador JSON no modo de análise não rigorosa para evitar interrupções se outros campos forem introduzidos na resposta JSON.
Autenticar com uma chave de API
Crie uma avaliação usando
o método
projects.assessments.create.
Antes de usar qualquer um dos dados da solicitação, faça as seguintes substituições:
- API_KEY: chave de API associada ao projeto atual
- PROJECT_ID: é o ID do projeto do Google Cloud.
- TOKEN: token retornado da chamada
grecaptcha.enterprise.execute() - KEY: chave reCAPTCHA associada ao site ou app. Para mais informações, consulte Chaves reCAPTCHA.
- USER_ACTION (somente para integrações de chave de site baseadas em pontuação): a ação iniciada pelo usuário que você especificou para
actionna chamadagrecaptcha.enterprise.execute(), comologin. Para mais informações, consulte Ações.
Método HTTP e URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY
Corpo JSON da solicitação:
{
"event": {
"token": "TOKEN",
"siteKey": "KEY",
"expectedAction": "USER_ACTION"
}
}For more information, see reCAPTCHA keys.
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo chamado 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
Salve o corpo da solicitação em um arquivo chamado 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 ContentVocê receberá uma resposta JSON semelhante a esta:
{
"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"
}
Recomendamos o uso de qualquer analisador JSON no modo de análise não rigorosa para evitar interrupções no caso de outros campos serem introduzidos 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 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.
// 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-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.
// 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-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
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
// 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-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 {
// 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
A seguir
- Interprete uma avaliação e tome as medidas necessárias para seu site com base na pontuação.