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.
Nesta página, explicamos como recuperar o token e criar uma avaliação.
Antes de começar
Escolha o melhor método para configurar o reCAPTCHA Enterprise no ambiente e conclua a configuração.
Como 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.
Como 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.
Como escolher o método de criação da avaliação
O método de criação da avaliação depende do seu ambiente:
| Ambiente | Métodos para criar uma avaliação |
|---|---|
| Google Cloud App Engine ou GKE | Bibliotecas de cliente do reCAPTCHA Enterprise |
| Google Cloud Compute Engine | Um dos seguintes:
|
| Nuvem de terceiros ou local com suporte a contas de serviço | Um dos 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) | Um dos seguintes:
|
Como 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.
Use a ferramenta gcloud ou a chave de API para autenticação.
Autenticar com a ferramenta 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 os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_ID: é o ID do projeto do Google Cloud.
- TOKEN: token retornado da chamada
grecaptcha.enterprise.execute() - KEY: chave reCAPTCHA associada ao site/app
- 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 comando a seguir:
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 comando a seguir:
$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"
}
Autenticar com uma chave de API
Crie uma avaliação usando
o método
projects.assessments.create. Envie a solicitação para o endpoint da API v1beta1.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- 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/app
- 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/v1beta1/projects/PROJECT_ID/assessments?key=API_KEY
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 comando a seguir:
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
Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:
$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 ContentVocê receberá uma resposta JSON semelhante a esta:
{
"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
A seguir
- Interprete uma avaliação e tome as medidas necessárias para seu site com base na pontuação.