Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Auf dieser Seite erfahren Sie, wie Sie Feedback zur Genauigkeit der von reCAPTCHA erstellten Bewertungen geben können. Anhand dieser Informationen kann reCAPTCHA Ihr websitespezifisches Modell optimieren und die Leistung Ihrer Website im Laufe der Zeit verbessern.
Wann Bewertungen annotiert werden sollten
reCAPTCHA gibt beim Erstellen einer Bewertung eine Bewertung ab, anhand derer Sie das Risiko von Nutzerinteraktionen besser einschätzen können.
Wenn Ihre Website später mehr Informationen zu Nutzerinteraktionen enthält, um zu bestimmen, ob die Interaktion legitim oder betrügerisch war, können Sie die reCAPTCHA-Bewertung bestätigen oder korrigieren. Dazu senden Sie die reCAPTCHA-Bewertungs-IDs als LEGITIMATE oder FRAUDULENT an Google zurück.
Wenn Sie die reCAPTCHA-Bewertung bestätigen oder korrigieren, wird die Leistung von reCAPTCHA für Ihre Website verbessert.
Um die Leistung von reCAPTCHA zu verbessern, können Sie die Annotationen für richtig positive und richtig negative Bewertungen zusätzlich zu den Annotationen für potenzielle Bewertungsfehler bestätigen.
Beispiel: Sie können die Bewertung für einen Nutzer, der sich erfolgreich mit einer 2-Faktor-Authentifizierung authentifiziert und eine hohe reCAPTCHA-Punktzahl erhalten hat, als LEGITIMATE annotieren. Wenn die reCAPTCHA-Punktzahl niedrig war und Ihre Website feststellte, dass die Interaktion betrügerisch oder missbräuchlich war, können Sie die Bewertung als FRAUDULENT annotieren.
Folgende Liste enthält zusätzliche Informationen zu einigen beispielhaften Nutzerinteraktionen, bei denen angeben wird, ob eine Nutzerinteraktion legitim oder betrügerisch war:
Kreditkartenrückbuchungen oder andere konkrete Beweise für Betrug weisen darauf hin, dass eine frühere Finanztransaktion betrügerisch war.
Ein neues Konto, von dem Nachrichten gesendet werden, die von anderen Nutzern als Spam gekennzeichnet werden, kann ein Hinweis darauf sein, dass die Kontoerstellung betrügerisch war.
Ein Support-Fall, der eingereicht wird, wenn ein Nutzer Schwierigkeiten beim Einloggen in sein Konto hat, könnte darauf hinweisen, dass der Login-Versuch legitim ist.
Ein Kauf oder eine Buchung auf einer Website, die reCAPTCHA zum Schutz vor Scraping verwendet, kann darauf hindeuten, dass der Nutzer legitim ist.
Hinweis
Sie benötigen die folgende Identity and Access Management-Rolle: reCAPTCHA Enterprise Agent (roles/recaptchaenterprise.agent).
Führen Sie je nachdem, wo Sie reCAPTCHA eingerichtet haben, den entsprechenden Schritt aus:
Bei WAF-Integrationen können Sie die eindeutige Bewertungs-ID aus dem reCAPTCHA-Token abrufen. Die eindeutige Bewertungs-ID ist der eindeutige alphanumerische String mit 16 Zeichen, der nach :U= am Ende des reCAPTCHA-Tokens angezeigt wird. Wenn das reCAPTCHA-Token beispielsweise .................U=6ZZZZe73fZZZZZZ0 lautet, ist die Bewertungs-ID 6ZZZZe73fZZZZZZ0.
Bewertungen anmerken
Legen Sie die Informationen und Labels fest, die Sie je nach Anwendungsfall in den JSON-Text der Anfrage einfügen möchten.
In der folgenden Tabelle sind die Labels und Werte aufgeführt, mit denen Sie Ereignisse annotieren können:
Label
Beschreibung
Beispielanfrage
reasons
Optional. Ein Label, das Ihre Bewertungen unterstützt.
Geben Sie Echtzeitdetails zum Ereignis innerhalb weniger Sekunden oder Minuten nach dem Ereignis im reasons-Label an, da sie die Echtzeiterkennung beeinflussen.
Beispiel: Wenn Sie Kontoübernahmen erkennen möchten, können Sie angeben, ob das eingegebene Passwort korrekt war, indem Sie die Werte CORRECT_PASSWORD oder INCORRECT_PASSWORD verwenden. Wenn Sie Ihre eigene MFA bereitgestellt haben, können Sie die folgenden Werte hinzufügen: INITIATED_TWO_FACTOR, PASSED_TWO_FACTOR oder FAILED_TWO_FACTOR.
{
"reasons": ["INCORRECT_PASSWORD"]
}
annotation
Optional. Ein Label, das die Legitimität von Bewertungen angibt.
Geben Sie Fakten zu Anmelde- und Registrierungsereignissen an, um Ihre Risikobewertungen im Label annotation zu bestätigen oder zu korrigieren.
Mögliche Werte: LEGITIMATE oder FRAUDULENT.
Sie können diese Informationen jederzeit oder als Teil eines Batchjobs senden.
Wir empfehlen jedoch, diese Informationen einige Sekunden oder Minuten nach dem Ereignis zu senden, da sie die Echtzeiterkennung beeinflussen.
{
"annotation": "LEGITIMATE"
}
Merken Sie eine Bewertung mit der Methode projects.assessments.annotate mit der gcloud CLI oder einem API-Schlüssel an.
gcloud-CLI
Ersetzen Sie diese Werte in den folgenden Anfragedaten:
ASSESSMENT_ID: Wert des name-Felds, der vom projects.assessments.create-Aufruf zurückgegeben wurde.
ANNOTATION_LABEL: Das Label gibt an, ob die Bewertung legitim oder betrügerisch ist.
Mögliche Werte sind LEGITIMATE und FRAUDULENT.
ANNOTATION_REASON: Beschreibt den Kontext für die Anmerkung, die für diese Bewertung ausgewählt wurde.
Informationen zu möglichen Werten finden Sie unter Gründe für Anmerkungen zu einer Bewertung.
HTTP-Methode und URL:
POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate
Sie sollten einen erfolgreichen Statuscode (2xx) und eine leere Antwort als Ausgabe erhalten.
API-Schlüssel
Ersetzen Sie diese Werte in den folgenden Anfragedaten:
ASSESSMENT_ID: Wert des name-Felds, der vom projects.assessments.create-Aufruf zurückgegeben wurde
ANNOTATION_LABEL: Das Label gibt an, ob die Bewertung legitim oder betrügerisch ist.
Mögliche Werte sind LEGITIMATE und FRAUDULENT.
ANNOTATION_REASON: Beschreibt den Kontext für die Anmerkung, die für diese Bewertung ausgewählt wurde.
Informationen zu möglichen Werten finden Sie unter Gründe für Anmerkungen zu einer Bewertung.
HTTP-Methode und URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 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)."]]
