評価の作成

エンドユーザーが HTML アクションをトリガーすると、reCAPTCHA Enterprise が暗号化されたレスポンス(ユーザーのレスポンス トークンと呼ばれる)をエンドユーザーのブラウザに送信します。あらゆる種類のサイトキーの統合(チェックボックスまたはスコア)については、生成されたトークンを評価エンドポイントに送信することで評価を作成する必要があります。reCAPTCHA Enterprise は、送信されたトークンを処理し、トークンの有効性とスコアを報告します。

このページでは、トークンを取得して評価を作成する方法について説明します。

始める前に

ご使用の環境内で reCAPTCHA Enterprise をセットアップするための最適な方法を選択し、セットアップを完了します。

ユーザーによるレスポンス トークンの取得

次のいずれかの方法で、ユーザーのレスポンス トークンをウェブページから取得します。

  • grecaptcha.enterprise.execute() の呼び出しによって返された Promise の解決された値。
  • ユーザーがサイトでフォームを送信するときの g-recaptcha-response POST パラメータ。
  • data-callbackg-recaptcha HTML タグ属性または grecaptcha.enterprise.render メソッドのコールバック パラメータで指定されている場合、コールバック関数の文字列引数として。

モバイルアプリからユーザーのレスポンス トークンを取得するには、reCAPTCHA Enterprise と iOS アプリの統合または reCAPTCHA Enterprise と Android アプリの統合をご覧ください。

各ユーザーの reCAPTCHA レスポンス トークンには 1 回のみアクセスできます。ユーザーがサイトに対して行う後続の操作を評価する必要がある場合、または評価を作成する前にトークンが期限切れになった場合は、execute() を再度呼び出して新しいトークンを生成する必要があります。

評価の作成

reCAPTCHA Enterprise API にリクエストを送信するか、reCAPTCHA Enterprise クライアント ライブラリを使用して評価を作成します。reCAPTCHA Enterprise の設定場所に基づいて評価の作成方法を選択することをおすすめします。

評価の作成方法を選択する

評価の作成に使用できる方法は、環境によって異なります。

環境 評価の作成方法
Google Cloud App Engine または GKE reCAPTCHA Enterprise クライアント ライブラリ
Google Cloud Compute Engine

次のいずれかになります。

  • 認証に gcloud ツールを使用する reCAPTCHA Enterprise REST API
  • reCAPTCHA Enterprise クライアント ライブラリ
サービス アカウントをサポートするサードパーティのクラウドまたはオンプレミス

次のいずれかになります。

  • 認証に gcloud ツールを使用する reCAPTCHA Enterprise REST API
  • reCAPTCHA Enterprise クライアント ライブラリ
サービス アカウントをサポートしていないサードパーティのクラウドまたはオンプレミス 認証に API キーを使用する reCAPTCHA Enterprise REST API
多要素認証(MFA)などの reCAPTCHA Enterprise 機能を使用する移行環境

次のいずれかになります。

  • 認証に gcloud ツールを使用する reCAPTCHA Enterprise REST API
  • 認証に API キーを使用する reCAPTCHA Enterprise REST 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.Api.Gax.ResourceNames;
   using Google.Cloud.RecaptchaEnterprise.V1;

   public class CreateAssessmentSample
   {
       // Create an assessment to analyze the risk of an UI action.
       // projectID: GCloud Project ID.
       // recaptchaSiteKey: Site key obtained by registering a domain/app to use recaptcha.
       // token: The token obtained from the client on passing the recaptchaSiteKey.
       // recaptchaAction: Action name corresponding to the token.
       public void createAssessment(string projectID = "project-id", string recaptchaSiteKey = "recaptcha-site-key",
           string token = "action-token", string recaptchaAction = "action-name")
       {

           // Create the client.
           RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.Create();

           ProjectName projectName = new ProjectName(projectID);

           // Build the assessment request.
           CreateAssessmentRequest createAssessmentRequest = new CreateAssessmentRequest()
           {
               Assessment = new Assessment()
               {
                   // Set the properties of the event to be tracked.
                   Event = new Event()
                   {
                       SiteKey = recaptchaSiteKey,
                       Token = token,
                       ExpectedAction = recaptchaAction
                   },
               },
               ParentAsProjectName = projectName
           };

           Assessment response = client.CreateAssessment(createAssessmentRequest);

           // Check if the token is valid.
           if (response.TokenProperties.Valid == false)
           { 
               System.Console.WriteLine("The CreateAssessment call failed because the token was: " +
                   response.TokenProperties.InvalidReason.ToString());
               return;
           }

           // Check if the expected action was executed.
           if (response.TokenProperties.Action != recaptchaAction)
           {
               System.Console.WriteLine("The action attribute in reCAPTCHA tag is: " +
                   response.TokenProperties.Action.ToString());
               System.Console.WriteLine("The action attribute in the reCAPTCHA tag does not " +
                   "match the action you are expecting to score");
               return;
           }

           // Get the risk score and the reason(s).
           // For more information on interpreting the assessment,
           // see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
           System.Console.WriteLine("The reCAPTCHA score is: " + ((decimal)response.RiskAnalysis.Score));

           foreach (RiskAnalysis.Types.ClassificationReason reason in response.RiskAnalysis.Reasons)
           {
               System.Console.WriteLine(reason.ToString());
           }
       }

       public static void Main(string[] args)
       {
           new CreateAssessmentSample().createAssessment();
       }
   }

Go

   import (
     "context"
     "fmt"

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

   func main() {
     // TODO(developer): Replace these variables before running the sample.
     projectID := "project-id"
     recaptchaSiteKey := "recaptcha-site-key"
     token := "action-token"
     recaptchaAction := "action-name"

     createAssessment(projectID, recaptchaSiteKey, token, recaptchaAction)
   }

   /**
   * Create an assessment to analyze the risk of an UI action.
   *
   * @param projectID: GCloud Project ID
   * @param recaptchaSiteKey: Site key obtained by registering a domain/app to use recaptcha services.
   * @param token: The token obtained from the client on passing the recaptchaSiteKey.
   * @param recaptchaAction: Action name corresponding to the token.
   */
   func createAssessment(projectID string, recaptchaSiteKey string, token string, recaptchaAction string) {

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

     // Set the properties of the event to be tracked.
     event := &recaptchapb.Event{
       Token:          token,
       SiteKey:        recaptchaSiteKey,
     }

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

     // Build the assessment request.
     request := &recaptchapb.CreateAssessmentRequest{
       Assessment: assessment,
       Parent:     fmt.Sprintf("projects/%s", projectID),
     }

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

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

     // Check if the token is valid.
     if response.TokenProperties.Valid == false {
       fmt.Printf("The CreateAssessment() call failed because the token"+
          " was invalid for the following reasons: %v",
       response.TokenProperties.InvalidReason)
       return
     }

     // Check if the expected action was executed.
     if response.TokenProperties.Action == recaptchaAction {
       // Get the risk score and the reason(s).
       // For more information on interpreting the assessment,
       // see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
       fmt.Printf("The reCAPTCHA score for this token is:  %v",
         response.RiskAnalysis.Score)

       for _,reason := range response.RiskAnalysis.Reasons {
         fmt.Printf(reason.String()+"\n")
       }
       return
     }

     fmt.Printf("The action attribute in your reCAPTCHA tag does " +
         "not match the action you are expecting to score")
   }

Java

   import com.google.cloud.recaptchaenterprise.v1.RecaptchaEnterpriseServiceClient;
   import com.google.recaptchaenterprise.v1.Assessment;
   import com.google.recaptchaenterprise.v1.CreateAssessmentRequest;
   import com.google.recaptchaenterprise.v1.Event;
   import com.google.recaptchaenterprise.v1.ProjectName;
   import com.google.recaptchaenterprise.v1.RiskAnalysis.ClassificationReason;
   import java.io.IOException;

   public class CreateAssessment {

     public static void main(String[] args) throws IOException {
       // TODO(developer): Replace these variables before running the sample.
       String projectID = "project-id";
       String recaptchaSiteKey = "recaptcha-site-key";
       String token = "action-token";
       String recaptchaAction = "action-name";

       createAssessment(projectID, recaptchaSiteKey, token, recaptchaAction);
     }

     /**
      * Create an assessment to analyze the risk of an UI action.
      *
      * @param projectID: GCloud Project ID
      * @param recaptchaSiteKey: Site key obtained by registering a domain/app to use recaptcha services.
      * @param token: The token obtained from the client on passing the recaptchaSiteKey.
      * @param recaptchaAction: Action name corresponding to the token.
      */
     public static void createAssessment(String projectID, String recaptchaSiteKey, String token,
         String recaptchaAction)
         throws IOException {
       // Initialize a client that will be used to send requests. This client needs to be created only
       // once, and can be reused for multiple requests. After completing all of your requests, call
       // the `client.close()` method on the client to safely
       // clean up any remaining background resources.
       try (RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.create()) {

         // Set the properties of the event to be tracked.
         Event event = Event.newBuilder()
             .setSiteKey(recaptchaSiteKey)
             .setToken(token)
             .build();

         // Build the assessment request.
         CreateAssessmentRequest createAssessmentRequest = CreateAssessmentRequest.newBuilder()
             .setParent(ProjectName.of(projectID).toString())
             .setAssessment(Assessment.newBuilder().setEvent(event).build())
             .build();

         Assessment response = client.createAssessment(createAssessmentRequest);

         // Check if the token is valid.
         if (!response.getTokenProperties().getValid()) {
           System.out.println("The CreateAssessment call failed because the token was: " +
              response.getTokenProperties().getInvalidReason().name());
           return;
         }

         // Check if the expected action was executed.
         // (If the key is checkbox type and 'action' attribute wasn't set, skip this check.)
         if (!response.getTokenProperties().getAction().equals(recaptchaAction)) {
           System.out.println("The action attribute in your reCAPTCHA tag " +
               "does not match the action you are expecting to score");
           return;
         }

         // Get the risk score and the reason(s).
         // For more information on interpreting the assessment,
         // see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
         float recaptchaScore = response.getRiskAnalysis().getScore();
         System.out.println("The reCAPTCHA score is: " + recaptchaScore);

         for (ClassificationReason reason : response.getRiskAnalysis().getReasonsList()) {
           System.out.println(reason);
         }
       }
     }
   }

Node.js

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

   /**
   * Create an assessment to analyze the risk of an UI action. Note that
   * this example does set error boundaries and returns `null` for
   * exceptions.
   *
   * projectID: GCloud Project ID
   * recaptchaSiteKey: Site key obtained by registering a domain/app to use recaptcha services.
   * token: The token obtained from the client on passing the recaptchaSiteKey.
   * recaptchaAction: Action name corresponding to the token.
   */
   async function createAssessment({
     projectID = "your-project-id",
     recaptchaSiteKey = "your-recaptcha-site-key",
     token = "action-token",
     recaptchaAction = "action-name",
   }) {
     // Create the reCAPTCHA client & set the project path. There are multiple
     // ways to authenticate your client. For more information see:
     // https://cloud.google.com/docs/authentication
     const client = new RecaptchaEnterpriseServiceClient();
     const projectPath = client.projectPath(projectID);

     // Build the assessment request.
     const request = ({
       assessment: {
         event: {
           token: token,
           siteKey: recaptchaSiteKey,
         },
       },
       parent: projectPath,
     });

     // client.createAssessment() can return a Promise or take a Callback
     const [ response ] = await client.createAssessment(request);

     // Check if the token is valid.
     if (!response.tokenProperties.valid) {
      console.log("The CreateAssessment call failed because the token was: " +
        response.tokenProperties.invalidReason);

      return null;
     }

     // Check if the expected action was executed.
     // The `action` property is set by user client in the
     // grecaptcha.enterprise.execute() method.
     if (response.tokenProperties.action === recaptchaAction) {

      // Get the risk score and the reason(s).
      // For more information on interpreting the assessment,
      // see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
      console.log("The reCAPTCHA score is: " +
        response.riskAnalysis.score);

      response.riskAnalysis.reasons.forEach((reason) => {
        console.log(reason);
      });
      return response.riskAnalysis.score;
     } else {
      console.log("The action attribute in your reCAPTCHA tag " +
        "does not match the action you are expecting to score");
      return null;
     }
   }

PHP

 <?php

   // Include Google Cloud dependencies using Composer
   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;

   /**
   * Create an assessment to analyze the risk of a UI action.
   * @param string $siteKey The key ID for the reCAPTCHA key (See https://cloud.google.com/recaptcha-enterprise/docs/create-key)
   * @param string $token The user's response token for which you want to receive a reCAPTCHA score. (See https://cloud.google.com/recaptcha-enterprise/docs/create-assessment#retrieve_token)
   * @param string $project Your Google Cloud project ID
   */
   function create_assessment(
      string $siteKey,
      string $token,
      string $project
   ): void {
      $client = new RecaptchaEnterpriseServiceClient();
      $projectName = $client->projectName($project);

      $event = (new Event())
          ->setSiteKey($siteKey)
          ->setToken($token);

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

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

          // You can use the score only if the assessment is valid,
          // In case of failures like re-submitting the same token, getValid() will return false
          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 {
              printf('The score for the protection action is:');
              printf($response->getRiskAnalysis()->getScore());

              // Optional: You can use the following methods to get more data about the token
              // Action name provided at token generation.
              // printf($response->getTokenProperties()->getAction() . PHP_EOL);
              // The timestamp corresponding to the generation of the token.
              // printf($response->getTokenProperties()->getCreateTime()->getSeconds() . PHP_EOL);
              // The hostname of the page on which the token was generated.
              // printf($response->getTokenProperties()->getHostname() . PHP_EOL);
          }
      } catch (exception $e) {
          printf('CreateAssessment() call failed with the following error: ');
          printf($e);
      }
   }

   // TODO(Developer): Replace the following before running the sample
   create_assessment(
      'YOUR_RECAPTCHA_SITE_KEY',
      'YOUR_USER_RESPONSE_TOKEN',
      'YOUR_GOOGLE_CLOUD_PROJECT_ID'
   );

Python

  from google.cloud import recaptchaenterprise_v1

  def create_assessment():
     """ Create an assessment to analyze the risk of a UI action.

     Args:
     projectID: GCloud Project ID
     recaptchaSiteKey: Site key obtained by registering a domain/app to use recaptcha services.
     token: The token obtained from the client on passing the recaptchaSiteKey.
     recaptchaAction: Action name corresponding to the token.
     """
     # TODO(developer): Replace these variables before running the sample.
     project_id = "your_project_id"
     recaptcha_site_key = "your_site_key"
     token = "action_token"
     recaptcha_action = "action_name"

     client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()

     # Set the properties of the event to be tracked.
     event = recaptchaenterprise_v1.Event()
     event.site_key = recaptcha_site_key
     event.token = token

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

     project_name = f'projects/{project_id}'

     # Build the assessment request.
     request = recaptchaenterprise_v1.CreateAssessmentRequest()
     request.assessment = assessment
     request.parent = project_name

     response = client.create_assessment(request)

     # Check if the token is valid.
     if not response.token_properties.valid:
         print("The CreateAssessment call failed because the token was " +
               "invalid for for the following reasons: "
               + str(response.token_properties.invalid_reason))
     else:
         # Check if the expected action was executed.
         if response.token_properties.action == recaptcha_action:
             # Get the risk score and the reason(s)
             # For more information on interpreting the assessment,
             # see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
             print("The reCAPTCHA score for this token is: " +
                   str(response.risk_analysis.score))
             for reason in response.risk_analysis.reasons:
                 print(reason)
         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

次のステップ

  • 評価を解釈し、スコアに基づいてサイトに対して適切な措置を講じる。