評価の作成

このページでは、アプリケーションのバックエンドから送られたユーザーの reCAPTCHA レスポンス トークンを評価する方法を説明します。

サイトキーの統合の種類(チェックボックスまたはスコア)にかかわらず、生成されたトークンを評価エンドポイントに送信する必要があります。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.Cloud.RecaptchaEnterprise.V1;

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

            string SiteKey = "your_site_key";
            string Token = "your_token";
            string AssessmentName = "your_assessment_name";
            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
                    },
                    Name = AssessmentName,
                },
                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 := "your_token"
  assessmentName := "your_assessment_name"
  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,
    Name:  assessmentName,
  }

  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")
    }
  }
}

Java

  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 = "your_token";
          String assessmentName = "assessment_name";
          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)
                          .setName(assessmentName)
                          .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 = "your_token";
    let assessmentName = "your_assessment_name";
    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,
        name: assessmentName
    });

    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', 'your_token');
 define('ASSESSMENT_NAME', 'your_assessment_name');
 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)
     ->setName(ASSESSMENT_NAME);

 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 = "your_token"
  assessment_name = "your_assessment_name"
  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
  assessment.name = assessment_name

  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 = "your_token"
  assessment_name = "your_assessment_name"
  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
  assessment.name = assessment_name

  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

次のステップ

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