평가에 주석 추가

이 페이지에서는 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)가 있는지 확인합니다.

• reCAPTCHA를 설정한 위치에 따라 적절한 단계를 완료합니다.

  • 웹사이트용 평가를 만듭니다.
  • 모바일 애플리케이션용 평가를 만듭니다.
  • WAF 통합을 설정합니다.

평가 ID 검색

평가에 주석을 추가하려면 다음과 같은 방법으로 고유한 평가 ID를 검색합니다.

• 웹 및 모바일 통합의 경우 평가 응답에서 고유한 평가 ID를 검색할 수 있습니다.

  평가를 만들면 다음 예시와 같이 JSON 응답이 수신됩니다.

  JSON 응답의 name 필드에서 고유 평가 ID를 검색합니다.

  {
  'tokenProperties': {
    'valid': True,
    'hostname': 'www.google.com',
    'action': 'homepage',
    'createTime': u'2019-03-28T12:24:17.894Z'
  },
  'riskAnalysis': {
    'score': 0.1,
    'reasons': ['AUTOMATION']
  },
  'event': {
    'token': 'RESPONSE_TOKEN',
    'siteKey': 'KEY_ID'
  },
  'name': 'ASSESSMENT_ID'
  }

• WAF 통합의 경우 reCAPTCHA 토큰에서 고유한 평가 ID를 검색할 수 있습니다. 고유한 평가 ID는 :U= 다음에 reCAPTCHA 토큰 끝에 표시되는 16자의 고유한 영숫자 문자열입니다. 예를 들어 reCAPTCHA 토큰이 .................U=6ZZZZe73fZZZZZZ0이면 평가 ID는 6ZZZZe73fZZZZZZ0입니다.

평가에 주석 추가

1. 사용 사례에 따라 요청 JSON 본문에 추가할 정보 및 라벨을 결정합니다.

   다음 표에는 이벤트에 주석을 추가하는 데 사용할 수 있는 라벨과 값이 나와 있습니다.

   라벨	설명	요청 예시
   reasons	선택사항. 평가를 지원하는 라벨입니다. 실시간 감지에 영향을 주기 때문에 이벤트 발생 후 몇 초 또는 몇 분 이내에 reasons 라벨에 실시간 이벤트 세부정보를 제공합니다. 가능한 값 목록은 이유 값을 참조하세요. 예시: 계정 탈취를 감지하려면 입력한 비밀번호가 CORRECT_PASSWORD 또는 INCORRECT_PASSWORD 값에 올바른지 주석을 추가합니다. 자체 MFA를 배포한 경우 INITIATED_TWO_FACTOR, PASSED_TWO_FACTOR, FAILED_TWO_FACTOR 값을 추가할 수 있습니다.	{ "reasons": ["INCORRECT_PASSWORD"] }
   annotation	선택사항. 평가 적법성을 나타내는 라벨입니다. annotation 라벨에서 위험 평가를 검증하거나 수정하기 위해 로그인 및 등록 이벤트에 대한 사실을 제공합니다. 가능한 값은 LEGITIMATE 또는 FRAUDULENT입니다. 이 정보는 언제든지 또는 일괄 작업을 통해 전송할 수 있습니다. 하지만 실시간 감지에 영향을 주기 때문에 이벤트 후 몇 초 또는 몇 분 이내에 이 정보를 전송하는 것이 좋습니다.	{ "annotation": "LEGITIMATE" }

2. gcloud CLI 또는 API 키와 함께 projects.assessments.annotate 메서드를 사용하여 평가에 주석을 추가합니다.

   참고: API의 v1beta1 버전을 사용하는 경우 v1 버전에서만 reCAPTCHA 계정 방어 도구와 같은 새로운 기능을 사용할 수 있으므로 v1 버전을 사용하는 것이 좋습니다. v1beta1에서 v1로 마이그레이션은 v1beta API에서 v1 API로 마이그레이션 을 참조하세요.

   gcloud CLI

   요청 데이터를 사용하기 전에 다음을 바꿉니다.

   • ASSESSMENT_ID: projects.assessments.create 호출에서 반환된 name 필드 값입니다.
   • ANNOTATION_LABEL: 평가가 적법한지 또는 허위인지 여부를 나타내는 라벨입니다. 가능한 값은 LEGITIMATE 또는 FRAUDULENT입니다.
   • ANNOTATION_REASON: 이 평가에 선택된 주석의 컨텍스트를 설명합니다. 가능한 값에 대한 자세한 내용은 평가에 주석을 추가하는 이유를 참조하세요.

   HTTP 메서드 및 URL:

   POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate

   JSON 요청 본문:

   {
   "annotation": "ANNOTATION_LABEL"
   "reasons": "ANNOTATION_REASON"
   }
   

   요청을 보내려면 다음 옵션 중 하나를 선택합니다.

   curl

   참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

   요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate"

   PowerShell

   참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

   요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

   $cred = gcloud auth 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/ASSESSMENT_ID:annotate" | Select-Object -Expand Content

   성공 상태 코드(2xx)와 빈 응답을 받게 됩니다.

   API 키

   요청 데이터를 사용하기 전에 다음을 바꿉니다.

   • ASSESSMENT_ID: projects.assessments.create 호출에서 반환된 name 필드 값입니다.
   • ANNOTATION_LABEL: 평가가 적법한지 또는 허위인지 여부를 나타내는 라벨입니다. 가능한 값은 LEGITIMATE 또는 FRAUDULENT입니다.
   • ANNOTATION_REASON: 이 평가에 선택된 주석의 컨텍스트를 설명합니다. 가능한 값에 대한 자세한 내용은 평가에 주석을 추가하는 이유를 참조하세요.

   HTTP 메서드 및 URL:

   POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY

   JSON 요청 본문:

   {
   "annotation": "ANNOTATION_LABEL"
   "reasons": "ANNOTATION_REASON"
   }
   

   요청을 보내려면 다음 옵션 중 하나를 선택합니다.

   curl

   참고: API 키를 생성하여 API로 인증하세요.

   요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

   curl -X POST \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY"

   PowerShell

   참고: API 키를 생성하여 API로 인증하세요.

   요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

   $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/ASSESSMENT_ID:annotate?key=API_KEY" | Select-Object -Expand Content

   성공 상태 코드(2xx)와 빈 응답을 받게 됩니다.

다음 단계

• reCAPTCHA의 사용자 계정 보호 기능에 대해 알아보기