평가에 주석 추가

이 페이지에서는 reCAPTCHA Enterprise에서 생성된 평가의 정확성에 대한 의견을 제공하는 방법을 설명합니다. 이 정보를 바탕으로 reCAPTCHA Enterprise는 사이트별 모델을 조정하고 시간이 지남에 따라 사이트의 성능을 개선할 수 있습니다.

평가에 주석을 추가해야 하는 경우

reCAPTCHA Enterprise는 사용자 상호작용의 위험도를 파악하는 데 도움이 되는 평가를 만들 때 점수를 제공합니다. 나중에 사이트에서 사용자 상호작용에 대한 자세한 정보를 통해 사용자 상호작용이 적법한지 또는 허위인지 판단할 때 reCAPTCHA Enterprise의 평가를 확인하거나 수정할 수 있습니다. 이렇게 하려면 LEGITIMATE 또는 FRAUDULENT로 라벨이 지정된 reCAPTCHA 평가 ID를 Google로 다시 보냅니다. reCAPTCHA Enterprise의 평가를 확인하거나 수정하면 사이트에 대해 reCAPTCHA Enterprise의 성능이 향상됩니다.

reCAPTCHA Enterprise의 성능을 개선하기 위해 잠재적 평가 오류에 대한 주석 외에도 참양성참음성에 대한 주석을 확인할 수 있습니다. 예를 들어, 2단계 인증 방식을 사용하여 성공적으로 인증받고 높은 reCAPTCHA 점수를 받은 사용자의 경우 평가에 LEGITIMATE로 주석을 달 수 있습니다. 또는 reCAPTCHA 점수가 낮아 사이트에서 상호 작용이 허위이거나 모욕적이라고 판단한 경우 평가에 FRAUDULENT로 주석을 달 수 있습니다.

다음 목록은 사용자 상호작용이 합법적인지 또는 사기인지를 나타내는 일부 샘플 사용자 상호작용에 대한 추가 정보를 보여줍니다.

  • 신용카드 지불 거절 또는 기타 사기에 관련한 명백한 증거는 이전의 금융 거래가 사기였음을 나타냅니다.
  • 다른 사용자가 스팸으로 표시한 메시지를 보내는 새 계정은 계정 생성이 허위였음을 나타냅니다.
  • 사용자가 계정에 로그인하는 데 문제가 있는 경우 지원 기록이 있으면 타당한 로그인 시도임을 나타냅니다.
  • reCAPTCHA Enterprise를 사용하여 스크랩을 방지하는 사이트의 구매 또는 예약은 사용자가 합법적임을 나타낼 수 있습니다.

시작하기 전에

평가 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자의 고유한 영숫자 문자열입니다. 예를 들어 reCAPTFHA 토큰이 .................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 메서드를 사용하여 평가에 주석을 추가합니다.

    gcloud CLI

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

    • 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

    JSON 요청 본문:

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

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

    curl

    요청 본문을 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/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate"

    PowerShell

    요청 본문을 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/projects/PROJECT_ID/assessments/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

    요청 본문을 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

    요청 본문을 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)와 빈 응답을 받게 됩니다.

다음 단계