Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
In questa pagina viene spiegato come fornire un feedback sull'accuratezza delle valutazioni create da reCAPTCHA. Con queste informazioni, reCAPTCHA può ottimizzare il modello specifico per il tuo sito e migliorare il rendimento del tuo sito nel tempo.
Quando annotare le valutazioni
Quando crei una valutazione, reCAPTCHA fornisce un punteggio che ti aiuta a comprendere il livello di rischio delle interazioni degli utenti.
In un secondo momento, quando il tuo sito avrà più informazioni sulle interazioni degli utenti per determinare se l'interazione è stata legittima o fraudolenta, potrai confermare o correggere la valutazione di reCAPTCHA. A tal fine, invia gli ID di valutazione reCAPTCHA a Google etichettati come LEGITIMATE o FRAUDULENT.
La conferma o la correzione della valutazione di reCAPTCHA migliora il rendimento di reCAPTCHA per il tuo sito.
Per migliorare le prestazioni di reCAPTCHA, puoi confermare le annotazioni per i veri positivi e i veri negativi, oltre alle annotazioni per i potenziali errori di valutazione.
Ad esempio, per un utente che ha eseguito l'autenticazione utilizzando un metodo di autenticazione a due fattori e ha ricevuto un punteggio reCAPTCHA elevato, puoi annotare la valutazione come LEGITIMATE. In alternativa, se il punteggio reCAPTCHA è basso e il tuo sito ha stabilito che l'interazione è fraudolenta o illecita, puoi annotare la valutazione come FRAUDULENT.
Il seguente elenco mostra informazioni aggiuntive su alcune interazioni utente di esempio che indicano se un'interazione utente è legittima o fraudolenta:
I riaccreditamenti della carta di credito o altre prove concrete di attività fraudolenta indicano che una transazione finanziaria precedente è stata fraudolenta.
Un nuovo account che invia messaggi segnalati come spam da altri utenti potrebbe indicare che la creazione dell'account è stata fraudolenta.
Una richiesta di assistenza inviata da un utente che ha difficoltà ad accedere al proprio account potrebbe indicare che il tentativo di accesso è legittimo.
Un acquisto o una prenotazione su un sito che utilizza reCAPTCHA per difendersi dallo scraping potrebbe indicare che l'utente è legittimo.
Prima di iniziare
Assicurati di disporre del seguente ruolo di gestione dell'identità e dell'accesso: Agente reCAPTCHA Enterprise (roles/recaptchaenterprise.agent).
A seconda di dove hai configurato reCAPTCHA, completa il
passaggio appropriato:
Per le integrazioni WAF, puoi recuperare l'ID valutazione univoco dal
token reCAPTCHA. L'ID valutazione univoco è la
stringa alfanumerica univoca di 16 caratteri visualizzata alla fine del
token reCAPTCHA dopo :U=. Ad esempio, se il token reCAPTCHA è
.................U=6ZZZZe73fZZZZZZ0, l'ID valutazione è 6ZZZZe73fZZZZZZ0.
Annotare una valutazione
Determina le informazioni e le etichette da aggiungere nel corpo JSON della richiesta
a seconda del caso d'uso.
La tabella seguente elenca le etichette e i valori che puoi utilizzare per annotare
gli eventi:
Etichetta
Descrizione
Esempio di richiesta
reasons
Facoltativo. Un'etichetta a supporto delle tue
valutazioni.
Fornisci i dettagli degli eventi in tempo reale nell'etichetta reasons entro pochi secondi o minuti dall'evento, in quanto influiscono sul rilevamento in tempo reale.
Per l'elenco
dei valori possibili,
consulta valori reasons.
Esempio: per rilevare le acquisizioni di account, annota se la password inserita era corretta con i valori CORRECT_PASSWORD o INCORRECT_PASSWORD. Se hai implementato la tua autenticazione a due fattori,
puoi aggiungere i seguenti valori: INITIATED_TWO_FACTOR e
PASSED_TWO_FACTOR o FAILED_TWO_FACTOR.
{
"reasons": ["INCORRECT_PASSWORD"]
}
annotation
Facoltativo. Un'etichetta per indicare la
legalità delle valutazioni.
Fornisci informazioni sugli eventi di accesso e registrazione per convalidare o correggere le valutazioni del rischio nell'etichetta annotation.
Valori possibili: LEGITIMATE
o FRAUDULENT.
Puoi inviare queste informazioni in qualsiasi momento o nell'ambito di un job batch.
Tuttavia, ti consigliamo di inviare queste informazioni entro pochi secondi o minuti
dopo l'evento perché influiscono sul rilevamento in tempo reale.
{
"annotation": "LEGITIMATE"
}
Aggiungi annotazioni a una valutazione utilizzando il metodo
projects.assessments.annotate
con l'interfaccia a riga di comando gcloud o una chiave API.
Interfaccia a riga di comando gcloud
Prima di utilizzare i dati della richiesta,
apporta le seguenti sostituzioni:
ASSESSMENT_ID: valore del campo name restituito dalla chiamata projects.assessments.create.
ANNOTATION_LABEL: l'etichetta che indica se la valutazione è legittima o fraudolenta.
I valori possibili sono LEGITIMATE o FRAUDULENT.
ANNOTATION_REASON: descrive il contesto dell'annotazione scelta per questa valutazione.
Per conoscere i valori possibili, consulta i motivi per annotare una valutazione.
Metodo HTTP e URL:
POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate
Dovresti ricevere un codice di stato di operazione riuscita (2xx) e una risposta vuota.
Chiave API
Prima di utilizzare i dati della richiesta,
apporta le seguenti sostituzioni:
ASSESSMENT_ID: valore del campo name restituito dalla chiamata projects.assessments.create
ANNOTATION_LABEL: l'etichetta che indica se la valutazione è legittima o fraudolenta.
I valori possibili sono LEGITIMATE o FRAUDULENT.
ANNOTATION_REASON: descrive il contesto dell'annotazione scelta per questa valutazione.
Per conoscere i valori possibili, consulta i motivi per annotare una valutazione.
Metodo HTTP e URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Difficile da capire","hardToUnderstand","thumb-down"],["Informazioni o codice di esempio errati","incorrectInformationOrSampleCode","thumb-down"],["Mancano le informazioni o gli esempi di cui ho bisogno","missingTheInformationSamplesINeed","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 2025-09-04 UTC."],[],[],null,["# Annotate assessments\n\nThis page explains how you can provide feedback on the accuracy of the\nassessments created by reCAPTCHA. With this information,\nreCAPTCHA can tune your site-specific model and provide\nimproved performance for your site over time.\n\nWhen to annotate assessments\n----------------------------\n\nreCAPTCHA provides a score when creating an assessment that\nhelps you understand the level of risk user interactions pose.\nLater, when your site has more information about user interactions\nto determine if the interaction was legitimate or fraudulent, you can confirm or\ncorrect reCAPTCHA's assessment. To do this, you send the\nreCAPTCHA assessment IDs back to Google labeled as `LEGITIMATE`\nor `FRAUDULENT`.\nConfirming or correcting\nreCAPTCHA's assessment improves the performance of\nreCAPTCHA for your site.\n\nTo improve the performance of reCAPTCHA, you can confirm the\nannotations for **true positives** and **true negatives** in addition to the\nannotations for potential assessment errors.\nFor example, for a user who successfully authenticated using\na 2-factor-authentication method and received a high reCAPTCHA score, you can\nannotate the assessment as `LEGITIMATE`. Alternatively, if reCAPTCHA\nscore was low and your site determined that the interaction was fraudulent or\nabusive, you can annotate the assessment as `FRAUDULENT`.\n\nThe following list shows additional information about some sample user\ninteractions that indicate whether a user interaction is legitimate or\nfraudulent:\n\n- Credit card chargebacks or other concrete evidence of fraud indicate that an earlier financial transaction was fraudulent.\n- A new account that sends messages that are flagged as spam by other users might indicate that the account creation was fraudulent.\n- A support case filed if a user has difficulty logging in to their account might indicate that the login attempt is legitimate.\n- A purchase or booking on a site that uses reCAPTCHA to defend against scraping might indicate that the user is legitimate.\n\nBefore you begin\n----------------\n\n- Ensure that you have the following Identity and Access Management role:\n reCAPTCHA Enterprise Agent (`roles/recaptchaenterprise.agent`).\n\n- Depending on where you have set up reCAPTCHA, complete the\n appropriate step:\n\n - [Create an assessment for your website](/recaptcha/docs/create-assessment-website).\n - [Create an assessment for your mobile application](/recaptcha/docs/create-assessment-mobile).\n - [Set up your WAF integration](/recaptcha/docs/setup-overview-waf).\n\nRetrieve the assessment ID\n--------------------------\n\nTo annotate an assessment, retrieve the unique assessment ID in the\nfollowing ways:\n\n- For web and mobile integrations, you can retrieve the unique assessment ID\n from the assessment response.\n\n After you create an assessment, you receive a JSON response as shown in the\n following example.\n\n Retrieve the unique assessment ID from the `name` field in the JSON response. \n\n ```bash\n {\n 'tokenProperties': {\n 'valid': True,\n 'hostname': 'www.google.com',\n 'action': 'homepage',\n 'createTime': u'2019-03-28T12:24:17.894Z'\n },\n 'riskAnalysis': {\n 'score': 0.1,\n 'reasons': ['AUTOMATION']\n },\n 'event': {\n 'token': 'RESPONSE_TOKEN',\n 'siteKey': 'KEY_ID'\n },\n 'name': 'ASSESSMENT_ID'\n }\n ```\n- For WAF integrations, you can retrieve the unique assessment ID from the\n reCAPTCHA token. The unique assessment ID is the\n unique alphanumeric string of 16 characters that appears at the end of the\n reCAPTCHA token after `:U=`. For example, if the reCAPTCHA token is\n `.................U=6ZZZZe73fZZZZZZ0`, then the assessment ID is `6ZZZZe73fZZZZZZ0`.\n\nAnnotate an assessment\n----------------------\n\n1.\n\n Determine the information and labels to add in the request JSON body\n depending on your use case.\n\n The following table lists the labels and values that you can use to annotate\n events:\n\n \u003cbr /\u003e\n\n2. Annotate an assessment using the\n [`projects.assessments.annotate`](/recaptcha/docs/reference/rest/v1/projects.assessments/annotate)\n method with the gcloud CLI or an API key.\n\n **Note:** If you are using the `v1beta1` version of the API, we recommend using the `v1` version because the new features, such as reCAPTCHA account defender are available only on `v1` version. For migrating from `v1beta1` to `v1`, see [Migrate from v1beta API to v1 API](/recaptcha/docs/migration-v1). \n\n ### gcloud CLI\n\n\n Before using any of the request data,\n make the following replacements:\n - \u003cvar translate=\"no\"\u003eASSESSMENT_ID\u003c/var\u003e: Value of the `name` field returned from the `projects.assessments.create` call.\n - \u003cvar translate=\"no\"\u003eANNOTATION_LABEL\u003c/var\u003e: The label to indicate whether the assessment is legitimate or fraudulent. Possible values are `LEGITIMATE` or `FRAUDULENT`.\n - \u003cvar translate=\"no\"\u003eANNOTATION_REASON\u003c/var\u003e: Describes the context for the annotation that was chosen for this assessment. To learn about possible values, see [reasons for annotating an assessment](https://cloud.google.com/recaptcha/docs/reference/rest/v1/projects.assessments/annotate#reason).\n\n\n HTTP method and URL:\n\n ```\n POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate\n ```\n\n\n Request JSON body:\n\n ```\n {\n \"annotation\": \"ANNOTATION_LABEL\"\n \"reasons\": \"ANNOTATION_REASON\"\n }\n ```\n\n To send your request, choose one of these options: \n\n #### curl\n\n | **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](/sdk/gcloud/reference/init) or [`gcloud auth login`](/sdk/gcloud/reference/auth/login) , or by using [Cloud Shell](/shell/docs), which automatically logs you into the `gcloud` CLI . You can check the currently active account by running [`gcloud auth list`](/sdk/gcloud/reference/auth/list).\n\n\n Save the request body in a file named `request.json`,\n and execute the following command:\n\n ```\n curl -X POST \\\n -H \"Authorization: Bearer $(gcloud auth print-access-token)\" \\\n -H \"Content-Type: application/json; charset=utf-8\" \\\n -d @request.json \\\n \"https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate\"\n ```\n\n #### PowerShell\n\n | **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](/sdk/gcloud/reference/init) or [`gcloud auth login`](/sdk/gcloud/reference/auth/login) . You can check the currently active account by running [`gcloud auth list`](/sdk/gcloud/reference/auth/list).\n\n\n Save the request body in a file named `request.json`,\n and execute the following command:\n\n ```\n $cred = gcloud auth print-access-token\n $headers = @{ \"Authorization\" = \"Bearer $cred\" }\n\n Invoke-WebRequest `\n -Method POST `\n -Headers $headers `\n -ContentType: \"application/json; charset=utf-8\" `\n -InFile request.json `\n -Uri \"https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate\" | Select-Object -Expand Content\n ```\n\n You should receive a successful status code (2xx) and an empty response.\n\n \u003cbr /\u003e\n\n ### API key\n\n\n Before using any of the request data,\n make the following replacements:\n - \u003cvar translate=\"no\"\u003eASSESSMENT_ID\u003c/var\u003e: Value of the `name` field returned from the `projects.assessments.create` call\n - \u003cvar translate=\"no\"\u003eANNOTATION_LABEL\u003c/var\u003e: The label to indicate whether the assessment is legitimate or fraudulent. Possible values are `LEGITIMATE` or `FRAUDULENT`.\n - \u003cvar translate=\"no\"\u003eANNOTATION_REASON\u003c/var\u003e: Describes the context for the annotation that was chosen for this assessment. To learn about possible values, see [reasons for annotating an assessment](https://cloud.google.com/recaptcha/docs/reference/rest/v1/projects.assessments/annotate#reason).\n\n\n HTTP method and URL:\n\n ```\n POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY\n ```\n\n\n Request JSON body:\n\n ```\n {\n \"annotation\": \"ANNOTATION_LABEL\"\n \"reasons\": \"ANNOTATION_REASON\"\n }\n ```\n\n To send your request, choose one of these options: \n\n #### curl\n\n | **Note:** Create an [API key](https://cloud.google.com/docs/authentication/api-keys#creating_an_api_key) to authenticate with the API.\n\n\n Save the request body in a file named `request.json`,\n and execute the following command:\n\n ```\n curl -X POST \\\n -H \"Content-Type: application/json; charset=utf-8\" \\\n -d @request.json \\\n \"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY\"\n ```\n\n #### PowerShell\n\n | **Note:** Create an [API key](https://cloud.google.com/docs/authentication/api-keys#creating_an_api_key) to authenticate with the API.\n\n\n Save the request body in a file named `request.json`,\n and execute the following command:\n\n ```\n $headers = @{ }\n\n Invoke-WebRequest `\n -Method POST `\n -Headers $headers `\n -ContentType: \"application/json; charset=utf-8\" `\n -InFile request.json `\n -Uri \"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY\" | Select-Object -Expand Content\n ```\n\n You should receive a successful status code (2xx) and an empty response.\n\n \u003cbr /\u003e\n\nWhat's next\n-----------\n\n- Learn about the [user accounts protection features of reCAPTCHA](/recaptcha/docs/protect-accounts-overview)."]]
