이 페이지에서는 reCAPTCHA에서 생성된 평가의 정확성에 대한 의견을 제공하는 방법을 설명합니다. 이 정보를 바탕으로 reCAPTCHA는 사이트별 모델을 조정하고 시간이 지남에 따라 사이트의 성능을 개선할 수 있습니다.
평가에 주석을 추가해야 하는 경우
reCAPTCHA는 사용자 상호작용의 위험도를 파악하는 데 도움이 되는 평가를 만들 때 점수를 제공합니다.
나중에 사이트에서 사용자 상호작용에 대한 자세한 정보를 통해 사용자 상호작용이 적법한지 또는 허위인지 판단할 때 reCAPTCHA의 평가를 확인하거나 수정할 수 있습니다. 이렇게 하려면 LEGITIMATE 또는 FRAUDULENT로 라벨이 지정된 reCAPTCHA 평가 ID를 Google로 다시 보냅니다.
reCAPTCHA의 평가를 확인하거나 수정하면 사이트의 reCAPTCHA 성능이 개선됩니다.
reCAPTCHA의 성능을 개선하기 위해 잠재적 평가 오류에 대한 주석 외에도 참양성 및 참음성에 대한 주석을 확인할 수 있습니다.
예를 들어, 2단계 인증 방식을 사용하여 성공적으로 인증받고 높은 reCAPTCHA 점수를 받은 사용자의 경우 평가에 LEGITIMATE로 주석을 달 수 있습니다. 또는 reCAPTCHA 점수가 낮아 사이트에서 상호 작용이 허위이거나 모욕적이라고 판단한 경우 평가에 FRAUDULENT로 주석을 달 수 있습니다.
다음 목록은 사용자 상호작용이 합법적인지 또는 사기인지를 나타내는 일부 샘플 사용자 상호작용에 대한 추가 정보를 보여줍니다.
신용카드 지불 거절 또는 기타 사기에 관련한 명백한 증거는 이전의 금융 거래가 사기였음을 나타냅니다.
다른 사용자가 스팸으로 표시한 메시지를 보내는 새 계정은 계정 생성이 허위였음을 나타냅니다.
사용자가 계정에 로그인하는 데 문제가 있는 경우 지원 기록이 있으면 타당한 로그인 시도임을 나타냅니다.
reCAPTCHA를 사용하여 스크랩을 방지하는 사이트의 구매 또는 예약은 사용자가 합법적임을 나타낼 수 있습니다.
시작하기 전에
Identity and Access Management 역할인 reCAPTCHA Enterprise 에이전트(roles/recaptchaenterprise.agent)가 있는지 확인합니다.
WAF 통합의 경우 reCAPTCHA 토큰에서 고유한 평가 ID를 검색할 수 있습니다. 고유한 평가 ID는 :U= 다음에 reCAPTCHA 토큰 끝에 표시되는 16자의 고유한 영숫자 문자열입니다. 예를 들어 reCAPTCHA 토큰이 .................U=6ZZZZe73fZZZZZZ0이면 평가 ID는 6ZZZZe73fZZZZZZ0입니다.
평가에 주석 추가
사용 사례에 따라 요청 JSON 본문에 추가할 정보 및 라벨을 결정합니다.
다음 표에는 이벤트에 주석을 추가하는 데 사용할 수 있는 라벨과 값이 나와 있습니다.
라벨
설명
요청 예시
reasons
선택사항. 평가를 지원하는 라벨입니다.
실시간 감지에 영향을 주기 때문에 이벤트 발생 후 몇 초 또는 몇 분 이내에 reasons 라벨에 실시간 이벤트 세부정보를 제공합니다.
예시: 계정 탈취를 감지하려면 입력한 비밀번호가 CORRECT_PASSWORD 또는 INCORRECT_PASSWORD 값에 올바른지 주석을 추가합니다. 자체 MFA를 배포한 경우 INITIATED_TWO_FACTOR, PASSED_TWO_FACTOR, FAILED_TWO_FACTOR 값을 추가할 수 있습니다.
{
"reasons": ["INCORRECT_PASSWORD"]
}
annotation
선택사항. 평가 적법성을 나타내는 라벨입니다.
annotation 라벨에서 위험 평가를 검증하거나 수정하기 위해 로그인 및 등록 이벤트에 대한 사실을 제공합니다.
가능한 값은 LEGITIMATE 또는 FRAUDULENT입니다.
이 정보는 언제든지 또는 일괄 작업을 통해 전송할 수 있습니다.
하지만 실시간 감지에 영향을 주기 때문에 이벤트 후 몇 초 또는 몇 분 이내에 이 정보를 전송하는 것이 좋습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 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)."]]
