Quando l'utente finale attiva un'azione HTML, reCAPTCHA Enterprise invia una risposta criptata, denominata token di risposta dell'utente (token) al browser dell'utente finale. Per qualsiasi tipo di integrazione della chiave del sito (casella di controllo o punteggio), devi creare una valutazione inviando il token generato all'endpoint di valutazione. reCAPTCHA Enterprise elabora il token inviato e segnala la validità e il punteggio del token.
Questo documento spiega come recuperare il token e creare una valutazione. Il primo milione di test mensili di reCAPTCHA Enterprise è gratuito. Puoi creare un milione di valutazioni al mese senza abilitare la fatturazione per il tuo progetto Google Cloud.
Prima di iniziare
Scegli il metodo migliore per la configurazione di reCAPTCHA Enterprise nel tuo ambiente e completa la configurazione.
Recuperare il token di risposta dell'utente
Recupera il token di risposta dell'utente dalle pagine web in uno dei seguenti modi:
- Il valore risolto della promessa restituita dalla chiamata a
grecaptcha.enterprise.execute(). g-recaptcha-responsequando l'utente invia il modulo sul tuo sito.- Come argomento della stringa per la funzione di callback, se
data-callbackè specificato nell'attributo del tag HTMLg-recaptchao nel parametro di callback nel metodogrecaptcha.enterprise.render.
Per recuperare il token di risposta dell'utente dalle applicazioni per dispositivi mobili, consulta Integrare reCAPTCHA Enterprise con app iOS o Integrare reCAPTCHA Enterprise con app Android.
Puoi accedere al token di risposta reCAPTCHA di ogni utente solo una volta.
Se devi valutare un'azione successiva intrapresa da un utente sul tuo sito o
se un token scade prima della creazione di una valutazione, devi richiamare nuovamente
execute() per generare un nuovo token.
Creare una valutazione
Crea una valutazione inviando una richiesta all'API reCAPTCHA Enterprise o utilizzando le librerie client reCAPTCHA Enterprise. Ti consigliamo di scegliere il metodo con cui creare una valutazione in base a dove hai configurato reCAPTCHA Enterprise.
Scegliere come creare una valutazione
I metodi che puoi utilizzare per creare una valutazione dipendono dal tuo ambiente. La tabella seguente elenca gli ambienti supportati e i corrispondenti metodi di valutazione:
| Ambiente | Metodi per creare una valutazione |
|---|---|
| Google Cloud App Engine o GKE | Librerie client di reCAPTCHA Enterprise |
| Google Cloud Compute Engine | Uno dei seguenti elementi:
|
| Cloud o on-premise di terze parti che supportano gli account di servizio | Uno dei seguenti elementi:
|
| Cloud o on-premise di terze parti che non supportano gli account di servizio | API reCAPTCHA Enterprise REST, utilizzando chiavi API per l'autenticazione |
| Ambiente di cui è stata eseguita la migrazione utilizzando funzionalità aggiuntive di reCAPTCHA Enterprise, come l'autenticazione a più fattori (MFA) | Uno dei seguenti elementi:
|
Creare una valutazione utilizzando l'API REST o le librerie client
Dopo aver selezionato il metodo appropriato per creare una valutazione, procedi nel seguente modo per crearne una. Il modo in cui crei una valutazione è uguale per le chiavi del sito basate su punteggi e con casella di controllo.
API REST
Crea una valutazione inviando una richiesta all'API reCAPTCHA Enterprise. Per l'autenticazione puoi utilizzare l'interfaccia a riga di comando gcloud o la chiave API.
Autenticare con l'interfaccia a riga di comando gcloud
Crea una valutazione utilizzando il metodo
projects.assessments.create. Invia questa richiesta all'endpoint dell'API v1.
Prima di utilizzare uno qualsiasi dei dati della richiesta, effettua le seguenti sostituzioni:
- PROJECT_ID: il tuo ID progetto Google Cloud
- TOKEN: token restituito dalla chiamata
grecaptcha.enterprise.execute() - KEY: chiave reCAPTCHA associata al sito o all'app. Per ulteriori informazioni, consulta Chiavi reCAPTCHA.
- USER_ACTION (solo per integrazioni con chiavi del sito basate sul punteggio): l'azione avviata dall'utente specificata per
actionnella chiamatagrecaptcha.enterprise.execute(), ad esempiologin. Per ulteriori informazioni, consulta la sezione Azioni.
Metodo HTTP e URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments
Corpo JSON richiesta:
{
"event": {
"token": "TOKEN",
"siteKey": "KEY",
"expectedAction": "USER_ACTION"
}
}
Per inviare la richiesta, scegli una delle seguenti opzioni:
Curling
Salva il corpo della richiesta in un file denominato request.json
ed esegui il seguente 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
Salva il corpo della richiesta in un file denominato request.json
ed esegui il seguente 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
Dovresti ricevere una risposta JSON simile alla seguente:
{
"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"
}
Consigliamo di utilizzare qualsiasi analizzatore sintattico JSON nella modalità di analisi non rigida per evitare interruzioni nel caso in cui vengano introdotti campi aggiuntivi nella risposta JSON.
Autenticarsi con una chiave API
Crea una valutazione utilizzando il metodo
projects.assessments.create.
Prima di utilizzare uno qualsiasi dei dati della richiesta, effettua le seguenti sostituzioni:
- API_KEY: chiave API associata al progetto corrente
- PROJECT_ID: il tuo ID progetto Google Cloud
- TOKEN: token restituito dalla chiamata
grecaptcha.enterprise.execute() - KEY: chiave reCAPTCHA associata al sito o all'app. Per ulteriori informazioni, consulta Chiavi reCAPTCHA.
- USER_ACTION (solo per integrazioni con chiavi del sito basate sul punteggio): l'azione avviata dall'utente specificata per
actionnella chiamatagrecaptcha.enterprise.execute(), ad esempiologin. Per ulteriori informazioni, consulta la sezione Azioni.
Metodo HTTP e URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY
Corpo JSON richiesta:
{
"event": {
"token": "TOKEN",
"siteKey": "KEY",
"expectedAction": "USER_ACTION"
}
}For more information, see reCAPTCHA keys.
Per inviare la richiesta, scegli una delle seguenti opzioni:
Curling
Salva il corpo della richiesta in un file denominato request.json
ed esegui il seguente 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
Salva il corpo della richiesta in un file denominato request.json
ed esegui il seguente 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 ContentDovresti ricevere una risposta JSON simile alla seguente:
{
"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"
}
Consigliamo di utilizzare qualsiasi analizzatore sintattico JSON nella modalità di analisi non rigida per evitare interruzioni nel caso in cui vengano introdotti campi aggiuntivi nella risposta 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
Passaggi successivi
- Interpreta una valutazione e intraprendi l'azione appropriata per il tuo sito in base al punteggio.