Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
Cette page explique comment envoyer des commentaires sur la précision des évaluations créées par reCAPTCHA. Grâce à ces informations, reCAPTCHA peut ajuster le modèle spécifique à votre site et l'améliorer au fil du temps.
Quand annoter les évaluations
reCAPTCHA fournit un score lors de la création d'une évaluation qui vous aide à comprendre le niveau de risque des interactions utilisateur.
Plus tard, lorsque votre site aura plus d'informations sur les interactions des utilisateurs pour déterminer si l'interaction était légitime ou frauduleuse, vous pourrez confirmer ou corriger l'évaluation de reCAPTCHA. Pour ce faire, renvoyez à Google les ID d'évaluation reCAPTCHA identifiés comme LEGITIMATE ou FRAUDULENT.
Le fait de confirmer ou de corriger l'évaluation de reCAPTCHA améliore les performances de reCAPTCHA pour votre site.
Pour améliorer les performances de reCAPTCHA, vous pouvez confirmer les annotations de vrais positifs et de vrais négatifs en plus des annotations d'erreurs d'évaluation potentielles.
Par exemple, dans le cas d'un utilisateur qui s'est authentifié à l'aide d'une méthode d'authentification à deux facteurs et qui a reçu un score reCAPTCHA élevé, vous pouvez annoter l'évaluation comme LEGITIMATE. Si le score reCAPTCHA est faible et que votre site détermine que l'interaction est frauduleuse ou abusive, vous pouvez annoter l'évaluation comme FRAUDULENT.
La liste suivante contient des informations supplémentaires sur des exemples d'interactions utilisateur qui indiquent si une interaction est légitime ou frauduleuse :
Les rejets de débit de carte de crédit ou d'autres preuves concrètes de fraude indiquent qu'une transaction financière antérieure était frauduleuse.
Un nouveau compte qui envoie des messages signalés comme spam par d'autres utilisateurs peut indiquer que la création du compte est frauduleuse.
Une demande d'assistance envoyée si un utilisateur rencontre des difficultés pour se connecter à son compte peut indiquer que la tentative de connexion est légitime.
Un achat ou une réservation sur un site qui utilise reCAPTCHA pour se protéger contre le scraping peut indiquer que l'utilisateur est légitime.
Avant de commencer
Assurez-vous de disposer du rôle IAM (Identity and Access Management) suivant : Agent reCAPTCHA Enterprise (roles/recaptchaenterprise.agent).
En fonction de l'emplacement où vous avez configuré reCAPTCHA, suivez la procédure appropriée:
Pour les intégrations WAF, vous pouvez récupérer l'ID d'évaluation unique à partir du jeton reCAPTCHA. L'ID d'évaluation unique est la chaîne alphanumérique unique de 16 caractères qui apparaît à la fin du jeton reCAPTCHA après :U=. Par exemple, si le jeton reCAPTCHA est .................U=6ZZZZe73fZZZZZZ0, l'ID d'évaluation est 6ZZZZe73fZZZZZZ0.
Annoter une évaluation
Déterminez les informations et les libellés à ajouter dans le corps de la requête JSON en fonction de votre cas d'utilisation.
Le tableau suivant liste les libellés et les valeurs que vous pouvez utiliser pour annoter les événements:
Libellé
Description
Exemple de requête
reasons
Facultatif. Un libellé pour étayer vos évaluations.
Fournissez des informations sur l'événement en temps réel dans l'étiquette reasons quelques secondes ou minutes après l'événement, car elles influencent la détection en temps réel.
Pour obtenir la liste des valeurs possibles, consultez la section Valeurs de reasons.
Exemple: Pour détecter les piratages de compte, indiquez si le mot de passe saisi était correct à l'aide des valeurs CORRECT_PASSWORD ou INCORRECT_PASSWORD. Si vous avez déployé votre propre MFA, vous pouvez ajouter les valeurs suivantes: INITIATED_TWO_FACTOR, PASSED_TWO_FACTOR ou FAILED_TWO_FACTOR.
{
"reasons": ["INCORRECT_PASSWORD"]
}
annotation
Facultatif. Libellé indiquant la légitimité des évaluations.
Fournissez des informations sur les événements de connexion et d'enregistrement pour valider ou corriger vos évaluations des risques dans le libellé annotation.
Valeurs possibles: LEGITIMATE ou FRAUDULENT.
Vous pouvez envoyer ces informations à tout moment ou dans le cadre d'une tâche par lot.
Toutefois, nous vous recommandons d'envoyer ces informations quelques secondes ou minutes après l'événement, car elles ont une incidence sur la détection en temps réel.
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
ASSESSMENT_ID: valeur du champ name renvoyée par l'appel projects.assessments.create.
ANNOTATION_LABEL: libellé indiquant si l'évaluation est légitime ou frauduleuse.
Les valeurs possibles sont LEGITIMATE ou FRAUDULENT.
ANNOTATION_REASON: décrit le contexte de l'annotation choisie pour cette évaluation.
Pour en savoir plus sur les valeurs possibles, consultez la section Pourquoi annoter une évaluation.
Méthode HTTP et URL :
POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate
Vous devriez recevoir un code d'état indiquant le succès de l'opération (2xx), ainsi qu'une réponse vide.
Clé API
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
ASSESSMENT_ID : valeur du champ name renvoyée par l'appel projects.assessments.create
ANNOTATION_LABEL: libellé indiquant si l'évaluation est légitime ou frauduleuse.
Les valeurs possibles sont LEGITIMATE ou FRAUDULENT.
ANNOTATION_REASON: décrit le contexte de l'annotation choisie pour cette évaluation.
Pour en savoir plus sur les valeurs possibles, consultez la section Pourquoi annoter une évaluation.
Méthode HTTP et URL :
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/09/04 (UTC).
[[["Facile à comprendre","easyToUnderstand","thumb-up"],["J'ai pu résoudre mon problème","solvedMyProblem","thumb-up"],["Autre","otherUp","thumb-up"]],[["Difficile à comprendre","hardToUnderstand","thumb-down"],["Informations ou exemple de code incorrects","incorrectInformationOrSampleCode","thumb-down"],["Il n'y a pas l'information/les exemples dont j'ai besoin","missingTheInformationSamplesINeed","thumb-down"],["Problème de traduction","translationIssue","thumb-down"],["Autre","otherDown","thumb-down"]],["Dernière mise à jour le 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)."]]
