평가 작성

이 페이지에서는 애플리케이션 백엔드에서 전송된 사용자의 reCAPTCHA 응답 토큰에 액세스하는 방법을 설명합니다.

모든 유형의 사이트 키 통합(체크박스 또는 점수)에 대해 생성된 토큰을 평가 엔드포인트에 제출해야 합니다. reCAPTCHA Enterprise가 제출된 토큰을 처리하고 토큰의 유효성과 점수를 보고합니다.

시작하기 전에

환경에서 reCAPTCHA Enterprise를 설정하는 가장 좋은 방법을 선택하고 설정을 완료합니다.

사용자의 응답 토큰 검색

다음 방법 중 하나로 웹페이지에서 사용자의 응답 토큰을 검색합니다.

  • grecaptcha.enterprise.execute()에 대한 호출로 리턴된 프라미스의 확인된 값
  • 사용자가 사이트에서 양식을 제출할 때 g-recaptcha-response POST 매개변수
  • data-callbackg-recaptcha HTML 태그 속성이나 grecaptcha.enterprise.render 메서드의 콜백 매개변수에 지정된 경우 콜백 함수에 대한 문자열 인수로 사용

모바일 애플리케이션에서 사용자의 응답 토큰을 검색하려면 iOS 앱에 reCAPTCHA Enterprise 통합 또는 Android 앱에 reCAPTCHA Enterprise 통합을 참조하세요.

각 사용자의 reCAPTCHA 응답 토큰에 한 번만 액세스할 수 있습니다. 사용자가 사이트에서 취하는 후속 조치를 평가해야 하는 경우, 또는 평가가 생성되기 전에 토큰이 만료되면 execute()를 다시 호출하여 새 토큰을 생성해야 합니다.

평가 작성

reCAPTCHA Enterprise API에 요청을 보내거나 reCAPTCHA Enterprise 클라이언트 라이브러리를 사용하여 평가를 만듭니다. reCAPTCHA Enterprise를 설정한 위치를 기반으로 평가를 만드는 방법을 선택하는 것이 좋습니다.

평가 생성 방법 선택

평가를 만드는 데 사용할 수 있는 방법은 환경에 따라 다릅니다.

환경 평가를 만드는 방법
Google Cloud App Engine 또는 GKE reCAPTCHA Enterprise 클라이언트 라이브러리
Google Cloud Compute Engine

다음 중 하나입니다.

  • reCAPTCHA Enterprise REST API, 인증에 gcloud 도구 사용
  • reCAPTCHA Enterprise 클라이언트 라이브러리
서비스 계정을 지원하는 타사 클라우드 또는 온프레미스

다음 중 하나입니다.

  • reCAPTCHA Enterprise REST API, 인증에 gcloud 도구 사용
  • reCAPTCHA Enterprise 클라이언트 라이브러리
서비스 계정을 지원하지 않는 타사 클라우드 또는 온프레미스 reCAPTCHA Enterprise REST API, 인증에 API 키 사용
다단계 인증(MFA) 등의 추가 reCAPTCHA Enterprise 기능을 사용하는 마이그레이션된 환경

다음 중 하나입니다.

  • reCAPTCHA Enterprise REST API, 인증에 gcloud 도구 사용
  • reCAPTCHA Enterprise REST API, 인증에 API 키 사용

REST API 또는 클라이언트 라이브러리를 사용하여 평가 만들기

평가를 만들 적절한 방법을 선택한 후 다음 단계를 수행하여 평가를 만듭니다.

REST API

reCAPTCHA Enterprise API에 요청을 전송하여 평가를 만듭니다. 인증에 gcloud 도구 또는 API 키를 사용할 수 있습니다.

gcloud 도구로 인증

projects.assessments.create 메서드를 사용하여 평가를 작성하십시오. 이 요청을 v1 API 엔드포인트로 보냅니다.

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

  • PROJECT_ID: Google Cloud 프로젝트 ID
  • TOKEN: grecaptcha.enterprise.execute() 호출에서 반환 토큰
  • KEY: 사이트/앱과 연결된 reCAPTCHA 키
  • USER_ACTION(점수 기반 사이트 키 통합에만 해당): grecaptcha.enterprise.execute() 호출에서 action에 지정한 사용자 시작 작업입니다(예: login). 자세한 내용은 작업을 참조하세요.

HTTP 메서드 및 URL:

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments

JSON 요청 본문:

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY",
    "expectedAction": "USER_ACTION"
  }
}

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

curl

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

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

PowerShell

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

$cred = gcloud auth application-default 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" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "tokenProperties": {
    "valid": true,
    "hostname": "www.google.com",
    "action": "homepage",
    "createTime": "2019-03-28T12:24:17.894Z"
   },
  "riskAnalysis": {
    "score": 0.1,
    "reasons": ["AUTOMATION"]
  },
 "event": {
    "token": "TOKEN",
    "siteKey": "KEY",
    "expectedAction": "USER_ACTION"
  },
  "name": "projects/PROJECT_ID/assessments/b6ac310000000000"
}

API 키로 인증

projects.assessments.create 메서드를 사용하여 평가를 작성하십시오. 이 요청을 v1beta1 API 엔드포인트로 보냅니다.

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

  • API_KEY: 현재 프로젝트와 연결된 API 키
  • PROJECT_ID: Google Cloud 프로젝트 ID
  • TOKEN: grecaptcha.enterprise.execute() 호출에서 반환 토큰
  • KEY: 사이트/앱과 연결된 reCAPTCHA 키
  • USER_ACTION(점수 기반 사이트 키 통합에만 해당): grecaptcha.enterprise.execute() 호출에서 action에 지정한 사용자 시작 작업입니다(예: login). 자세한 내용은 작업을 참조하세요.

HTTP 메서드 및 URL:

POST https://recaptchaenterprise.googleapis.com/v1beta1/projects/PROJECT_ID/assessments?key=API_KEY

JSON 요청 본문:

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY",
    "expectedAction": "USER_ACTION"
  }
}

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

curl

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

curl -X POST \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://recaptchaenterprise.googleapis.com/v1beta1/projects/PROJECT_ID/assessments?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/v1beta1/projects/PROJECT_ID/assessments?key=API_KEY" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "tokenProperties": {
    "valid": true,
    "hostname": "www.google.com",
    "action": "homepage",
    "createTime": "2019-03-28T12:24:17.894Z"
   },
  "score": 0.1,
  "reasons": ["AUTOMATION"],
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY",
    "expectedAction": "USER_ACTION"
  },
  "name": "projects/PROJECT_ID//assessments/b6ac310000000000"
}

C#

using System;
using Google.Cloud.RecaptchaEnterprise.V1;

namespace csharp_recaptcha_sample
{
    public class create_assessment_sample
    {
        static void Main(string[] args)
        {

            string SiteKey = "your_site_key";
            string Token = "user_response_token";
            string ParentProject = "projects/your_project_name";
            string RecaptchaAction = "name_of_action_to_protect";

            RecaptchaEnterpriseServiceClient client =
                RecaptchaEnterpriseServiceClient.Create();

            CreateAssessmentRequest createAssessmentRequest = new CreateAssessmentRequest()
            {
                Assessment = new Assessment()
                {
                    Event = new Event()
                    {
                        SiteKey = SiteKey,
                        Token = Token,
                        ExpectedAction = RecaptchaAction
                    },
                },
                Parent = ParentProject
            };

            Assessment response = client.CreateAssessment(createAssessmentRequest);

            if (response.TokenProperties.Valid == false)
            {
                System.Console.WriteLine("The CreateAssessment() call failed " +
                    "because the token was invalid for the following reason: " +
                    response.TokenProperties.InvalidReason.ToString());
            }
            else
            {
                if (response.Event.ExpectedAction == RecaptchaAction)
                {
                    System.Console.WriteLine("The reCAPTCHA score for this token is: " +
                        response.RiskAnalysis.Score.ToString());
                }
                else
                {
                    System.Console.WriteLine("The action attribute in your reCAPTCHA " +
                        "tag does not match the action you are expecting to score");

                }

            }

        }
    }
}

Go

package main

import (
  "context"
  "fmt"

  recaptcha "cloud.google.com/go/recaptchaenterprise/apiv1"
  recaptchapb "google.golang.org/genproto/googleapis/cloud/recaptchaenterprise/v1"
)

func main() {

  siteKey := "your_sitekey"
  token := "user_response_token"
  parentProject := "projects/your_project_name"
  recaptchaAction := "name_of_action_to_protect"

  ctx := context.Background()
  client, err := recaptcha.NewClient(ctx)
  if err != nil {
    fmt.Printf("Error creating reCAPTCHA client\n")
  }

  event := &recaptchapb.Event{
    ExpectedAction: recaptchaAction,
    Token:          token,
    SiteKey:        siteKey,
  }

  assessment := &recaptchapb.Assessment{
    Event: event,
  }

  request := &recaptchapb.CreateAssessmentRequest{
    Assessment: assessment,
    Parent:     parentProject,
  }

  response, err := client.CreateAssessment(
    ctx,
    request)

  if err != nil {
    fmt.Printf("%v", err.Error())
  }

  if response.TokenProperties.Valid == false {
    fmt.Printf("The CreateAssessment() call failed because the token"+
      " was invalid for the following reasons: %v",
      response.TokenProperties.InvalidReason)
  } else {
    if response.Event.ExpectedAction == recaptchaAction {
      fmt.Printf("The reCAPTCHA score for this token is:  %v",
        response.RiskAnalysis.Score)
    } else {
      fmt.Printf("The action attribute in your reCAPTCHA tag does" +
        "not match the action you are expecting to score")
    }
  }
}

자바

  import com.google.cloud.recaptchaenterprise.v1.*;
  import com.google.recaptchaenterprise.v1.Assessment;
  import com.google.recaptchaenterprise.v1.CreateAssessmentRequest;
  import com.google.recaptchaenterprise.v1.Event;
  import java.io.IOException;

  public class test1 {
      public static void main(String[] args) throws IOException {

          String siteKey = "your_site_key";
          String token = "user_response_token";
          String projectPath = "projects/your_project_name";
          String recaptchaAction = "name_of_action_to_protect";

          RecaptchaEnterpriseServiceClient client =
                  RecaptchaEnterpriseServiceClient.create();

          Event event =
                  Event.newBuilder()
                          .setToken(token)
                          .setSiteKey(siteKey)
                          .setExpectedAction(recaptchaAction)
                          .build();

          Assessment assessment =
                  Assessment.newBuilder()
                          .setEvent(event)
                          .build();

          CreateAssessmentRequest createAssessmentRequest =
                  CreateAssessmentRequest.newBuilder()
                          .setParent(projectPath)
                          .setAssessment(assessment)
                          .build();

          Assessment response =
                  client.createAssessment(createAssessmentRequest);

          if (!response.getTokenProperties().getValid()) {
              System.out.println("The CreateAssessment call failed because the token was: " +
                      response.getTokenProperties().getInvalidReason().name());
          } else {
              if (response.getEvent().getExpectedAction() == recaptchaAction) {
                  System.out.println("The reCAPTCHA score is: " +
                          response.getRiskAnalysis().getScore());
              } else {
                  System.out.println("The action attribute in your reCAPTCHA tag " +
                          "does not match the action you are expecting to score");
              }
          }
      }
  }

Node.js

    function main() {

    let siteKey = "your_site_key";
    let token = "user_response_token";
    let parentPath = "projects/your_project_name";
    let recaptchaAction = "name_of_action_to_protect";

    const {RecaptchaEnterpriseServiceClient} =
        require('@google-cloud/recaptcha-enterprise');
    const client = new RecaptchaEnterpriseServiceClient();

    const event = ({
        token: token,
        siteKey: siteKey,
        protectedAction: recaptchaAction
    });

    const assessment = ({
        event: event
    });

    const request = ({
        assessment: assessment,
        parent: parentPath
    });

    client.createAssessment(request, function(err, response) {

        if (response.tokenProperties.valid == false)
        {
            console.log("The CreateAssessment() call failed because the " +
                "token was invalid with the following reason: " +
                response.tokenProperties.invalidReason);
        }
        else
        {
            if (response.event.expectedAction == protectedAction){
                console.log("The reCAPTCHA score is: " +
                    response.riskAnalysis.score);
            }
            else
            {
                console.log("The action attribute in your reCAPTCHA tag does " +
                    "not match the action you are expecting to score");
            }
        }
    });
}

main();

PHP

 <?php
 require 'vendor/autoload.php';

 use Google\Cloud\RecaptchaEnterprise\V1\RecaptchaEnterpriseServiceClient;
 use Google\Cloud\RecaptchaEnterprise\V1\Event;
 use Google\Cloud\RecaptchaEnterprise\V1\Assessment;
 use Google\Cloud\RecaptchaEnterprise\V1\TokenProperties\InvalidReason;

 $client = new RecaptchaEnterpriseServiceClient();

 define('SITE_KEY', 'your_site_key');
 define('TOKEN', 'user_response_token');
 define('PROTECTED_ACTION', 'name_of_action_to_protect');
 define('PARENT_PROJECT', 'projects/your_project_name');

 $event = (new Event())
     ->setSiteKey(SITE_KEY)
     ->setExpectedAction(PROTECTED_ACTION)
     ->setToken(TOKEN);

 $assessment = (new Assessment())
     ->setEvent($event);

 try {
     $response = $client->createAssessment(
         PARENT_PROJECT,
         $assessment
     );

     if ($response->getTokenProperties()->getValid() == false) {
         printf('The CreateAssessment() call failed because the token was invalid for the following reason: ');
         printf(InvalidReason::name($response->getTokenProperties()->getInvalidReason()));
     } else {
         if ($response->getEvent()->getExpectedAction() == PROTECTED_ACTION) {
             printf('The score for the protection action is:');
             printf($response->getRiskAnalysis()->getScore());
         }
         else
         {
             printf('The action attribute in your reCAPTCHA tag does not match the action you are expecting to score');
         }
     }
 } catch (exception $e) {
     printf('CreateAssessment() call failed with the following error: ');
     printf($e);
 }

Python

  from google.cloud import recaptchaenterprise_v1

  site_key = "your_site_key"
  token = "user_response_token"
  parent_project = "projects/your_project_name"
  recaptcha_action = "name_of_action_to_protect"

  client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()

  event = recaptchaenterprise_v1.Event()
  event.site_key = site_key
  event.token = token
  event.expected_action = recaptcha_action

  assessment = recaptchaenterprise_v1.Assessment()
  assessment.event = event

  request = recaptchaenterprise_v1.CreateAssessmentRequest()
  request.assessment = assessment
  request.parent = parent_project

  response = client.create_assessment(request)

  if not response.token_properties.valid:
    print("The CreateAssessment() call failed because the token was " +
          "invalid for the following reasons: "
          + str(response.token_properties.invalid_reason))
  else:
    if response.event.expected_action == recaptcha_action:
      print("The reCAPTCHA score for this token is: " +
            str(response.risk_analysis.score))
    else:
      print("The action attribute in your reCAPTCHA tag does" +
            "not match the action you are expecting to score")

Ruby

  require "google/cloud/recaptcha_enterprise/v1"

  siteKey = "your_site_key"
  token = "user_response_token"
  parent_project = "projects/your_project_name"
  recaptcha_action = "name_of_action_to_protect"

  client = ::Google::Cloud::RecaptchaEnterprise::V1::RecaptchaEnterpriseService::Client.new

  event = ::Google::Cloud::RecaptchaEnterprise::V1::Event.new
  event.site_key = siteKey
  event.token = token
  event.expected_action = recaptcha_action

  assessment = ::Google::Cloud::RecaptchaEnterprise::V1::Assessment.new
  assessment.event = event

  request = ::Google::Cloud::RecaptchaEnterprise::V1::CreateAssessmentRequest.new
  request.parent = parent_project
  request.assessment = assessment

  response = client.create_assessment(request)

  if response.token_properties.valid == false
    printf("The CreateAssessment() call failed because the token was invalid with the following reason: %s ", response.token_properties.invalid_reason)
  else
    if response.event.expected_action == recaptcha_action
      printf("The reCAPTCHA score for this token is: %s" + response.risk+analysis.score)
    else
      printf("The action attribute in your reCAPTCHA tag does not match the action you are expecting to score")
    end
  end

다음 단계

  • 평가를 해석하고 점수에 따라 사이트에 적절한 조치를 취합니다.