このページは Cloud Translation API によって翻訳されました。

ウェブサイトの評価を作成する

このページでは、reCAPTCHA から送信されるトークンの信頼性をバックエンドで検証するための評価を作成する方法について説明します。 reCAPTCHA は、エンドユーザーが HTML アクションをトリガーすると、暗号化されたレスポンスである reCAPTCHA レスポンストークン（トークン）を送信します。

あらゆるタイプの reCAPTCHA キー統合（(チェックボックスまたはスコア）では、生成されたトークンを評価エンドポイントに送信して、バックエンドで execute() の結果を評価するための評価を作成する必要があります。reCAPTCHA は送信されたトークンを処理し、トークンの有効性とスコアを報告します。

reCAPTCHA の月間評価数のうち、最初の 10,000 回は無料です。毎月の無料使用量上限（1 か月あたり 10,000 回の評価）に達した後も評価の作成を続けるには、Google Cloud プロジェクトに対する課金を有効にする必要があります。reCAPTCHA のお支払い情報については、お支払い情報をご覧ください。

始める前に

reCAPTCHA 用に環境を準備します。
reCAPTCHA Enterprise エージェント（roles/recaptchaenterprise.agent）の Identity and Access Management ロールがあることを確認します。
スコアベースキーまたはチェックボックスキーをウェブサイトにインストールします。

reCAPTCHA に対する認証を設定します。

選択する認証方式は、reCAPTCHA が設定されている環境によって異なります。次の表は、認証を設定するために、適切な認証方法とサポートされているインターフェースを選択する際に有用です。

環境	インターフェース	認証方法
Google Cloud	REST クライアントライブラリ	関連付けられているサービスアカウントを使用します。
オンプレミスまたは別のクラウドプロバイダ	REST	API キーまたは　Workload Identity 連携を使用します。 API キーを使用する場合は、API キーの制限を適用して API キーを保護することをおすすめします。
クライアントライブラリ	以下を使用します。 Python または Java の場合は、API キーまたは Workload Identity 連携を使用します。 API キーを使用する場合は、API キーの制限を適用して API キーを保護することをおすすめします。他の言語の場合は、Workload Identity 連携を使用します。

環境

インターフェース

認証方法

Google Cloud

REST
クライアントライブラリ

関連付けられているサービスアカウントを使用します。

オンプレミスまたは別のクラウドプロバイダ

REST

API キーまたは　Workload Identity 連携を使用します。

API キーを使用する場合は、API キーの制限を適用して API キーを保護することをおすすめします。

クライアントライブラリ

以下を使用します。

Python または Java の場合は、API キーまたは Workload Identity 連携を使用します。
API キーを使用する場合は、API キーの制限を適用して API キーを保護することをおすすめします。
他の言語の場合は、Workload Identity 連携を使用します。

トークンを取得する

ウェブページからトークンを取得するには、次のいずれかの方法を使用します。

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

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

評価の作成

認証を設定したら、reCAPTCHA Enterprise API にリクエストを送信するか、reCAPTCHA クライアントライブラリを使用して評価を作成します。

検出を向上させるには、評価の作成時に次の追加の値を渡すことをおすすめします。

userAgent: ユーザーエージェントは、リクエストヘッダーの HTTP リクエストに含まれます。詳細については、Mozilla Developer Network のドキュメントで User-Agent リクエストヘッダーについてをご覧ください。
userIpAddress: バックエンドにリクエストを送信したユーザーの IP アドレスは HTTP リクエストで使用できます。プロキシサーバーを使用している場合、IP アドレスは X-Forwarded-For リクエストヘッダーで使用できます。IP アドレスの取得の詳細については、X-Forwarded-For をご覧ください。
ja3: JA3 は、TLS クライアントのフィンガープリントを取得するオープンソースの方法です。JA3 を使用した TLS フィンガープリントの作成について詳しくは、JA3 のドキュメントをご覧ください。

高度な攻撃パターンや人手による不正行為からウェブサイトやモバイルアプリを保護するうえで有用です。

評価の作成方法は、スコアベースのサイトキーとチェックボックスキーで同じです。

REST API

reCAPTCHA API にリクエストを送信して評価を作成します。認証には、gcloud CLI または API キーを使用できます。

gcloud CLI を使用する

projects.assessments.create メソッドを使用して評価を作成します。このリクエストは v1 API エンドポイントに送信します。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: 実際の Google Cloud プロジェクト ID
TOKEN: grecaptcha.enterprise.execute() 呼び出しから返されたトークン
KEY_ID: サイトまたはアプリに関連付けられた reCAPTCHA キー。詳細については、reCAPTCHA キーをご覧ください。
USER_AGENT: ユーザーのデバイスからのリクエストに含まれるユーザーエージェント。
USER_IP_ADDRESS: ユーザーのデバイスからのリクエストに含まれる IP アドレス。
JA3: SSL クライアントの JA3 フィンガープリント。JA3 の計算には、salesforce/ja3 を使用することをおすすめします。
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_ID",
    "userAgent": "USER_AGENT",
    "userIpAddress": "USER_IP_ADDRESS",
    "ja3": "JA3",
    "expectedAction": "USER_ACTION"
  }
}

リクエストを送信するには、次のいずれかのオプションを選択します。

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/projects/PROJECT_ID/assessments"

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/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_ID",
    "userAgent": "USER_AGENT",
    "userIpAddress": "USER_IP_ADDRESS",
    "ja3": "JA3",
    "expectedAction": "USER_ACTION"
  },
  "name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000"
}

注: アクションとの統合では、projects.assessments.create メソッドを呼び出したときに、action の戻り値が expectedAction と一致することを確認します。不一致が存在する場合は、攻撃者が操作を偽装しようとしていることを示しています。ユーザーインタラクションに対して、追加の検証を行う、またはインタラクションをブロックするなどのアクションを講じて、不正なアクティビティを防止できます。

非厳格な解析モードで JSON パーサーを使用することをおすすめします。これにより、フィールドが JSON レスポンスに追加された場合の停止を防ぐことができます。

API キーを使用する

projects.assessments.create メソッドを使用して評価を作成します。このリクエストは v1 API エンドポイントに送信します。

注: API の v1beta1 バージョンを使用している場合は、v1 バージョンを使用することをおすすめします。reCAPTCHA アカウント保護などの新機能は v1 バージョンでのみ使用できるためです。v1beta1 から v1 への移行については、v1beta API から v1 API への移行をご覧ください。

リクエストのデータを使用する前に、次のように置き換えます。

API_KEY: 現在のプロジェクトに関連付けられた API キー
PROJECT_ID: 実際の Google Cloud プロジェクト ID
TOKEN: grecaptcha.enterprise.execute() 呼び出しから返されたトークン
KEY_ID: サイトまたはアプリに関連付けられた reCAPTCHA キー。詳細については、reCAPTCHA キーをご覧ください。
USER_AGENT: ユーザーのデバイスからのリクエストに含まれるユーザーエージェント。
USER_IP_ADDRESS: ユーザーのデバイスからのリクエストに含まれる IP アドレス。
JA3: SSL クライアントの JA3 フィンガープリント。JA3 の計算には、salesforce/ja3 を使用することをおすすめします。
USER_ACTION: grecaptcha.enterprise.execute() 呼び出しで action にユーザーが設定したアクション（login など）。
詳細については、アクション名をご覧ください。
注: ウィジェットを明示的にレンダリングするチェックボックスキーの統合では、アクションはサポートされていません。

HTTP メソッドと URL:

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

リクエストの本文（JSON）:

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userAgent": "USER_AGENT",
    "userIpAddress": "USER_IP_ADDRESS",
    "ja3": "JA3",
    "expectedAction": "USER_ACTION"
  }
}

リクエストを送信するには、次のいずれかのオプションを選択します。

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?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?key=API_KEY" | 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_ID",
    "userAgent": "USER_AGENT",
    "userIpAddress": "USER_IP_ADDRESS",
    "ja3": "JA3",
    "expectedAction": "USER_ACTION"
  },
  "name": "projects/PROJECT_NUMBER/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 a UI action.
      // projectID: Google Cloud project ID.
      // recaptchaKey: reCAPTCHA key obtained by registering a domain or an app to use reCAPTCHA Enterprise.
      // token: The token obtained from the client on passing the recaptchaKey.
      // recaptchaAction: Action name corresponding to the token.
      public void createAssessment(string projectID = "project-id", string recaptchaKey = "recaptcha-key",
          string token = "action-token", string recaptchaAction = "action-name")
      {

          // Create the client.
          // TODO: To avoid memory issues, move this client generation outside
          // of this example, and cache it (recommended) or call client.close()
          // before exiting this method.
          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 = recaptchaKey,
                      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 reasons.
          // For more information on interpreting the assessment,
          // see: https://cloud.google.com/recaptcha/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/v2/apiv1"
    recaptchapb "cloud.google.com/go/recaptchaenterprise/v2/apiv1/recaptchaenterprisepb"
  )

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

    createAssessment(projectID, recaptchaKey, token, recaptchaAction)
  }

  /**
  * Create an assessment to analyze the risk of a UI action.
  *
  * @param projectID: Google Cloud project ID
  * @param recaptchaKey: reCAPTCHA key obtained by registering a domain or an app to use the services of reCAPTCHA Enterprise.
  * @param token: The token obtained from the client on passing the recaptchaKey.
  * @param recaptchaAction: Action name corresponding to the token.
  */
  func createAssessment(projectID string, recaptchaKey string, token string, recaptchaAction string) {

    // Create the recaptcha client.
    // TODO: To avoid memory issues, move this client generation outside
    // of this example, and cache it (recommended) or call client.close()
    // before exiting this method.
    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:        recaptchaKey,
    }

    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/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";
    String userIpAddress = "user-ip-address";
    String userAgent = "user-agent";
    String ja3 = "ja3"

    createAssessment(projectID, recaptchaSiteKey, token, recaptchaAction, userIpAddress, userAgent, ja3);
  }

  /**
   * Create an assessment to analyze the risk of an UI action. Assessment approach is the same for
   * both 'score' and 'checkbox' type recaptcha site keys.
   *
   * @param projectID : GCloud Project ID
   * @param recaptchaSiteKey : Site key obtained by registering a domain/app to use recaptcha
   *     services. (score/ checkbox type)
   * @param token : The token obtained from the client on passing the recaptchaSiteKey.
   * @param recaptchaAction : Action name corresponding to the token.
   * @param userIpAddress: IP address of the user sending a request.
   * @param userAgent: User agent is included in the HTTP request in the request header. 
   * @param ja3: JA3 associated with the request.
   */
  public static void createAssessment(
      String projectID, String recaptchaSiteKey, String token, String recaptchaAction, String userIpAddress, String userAgent, String ja3)
      throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // 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)
          .setUserIpAddress(userIpAddress)
          .setJa3(ja3)
          .setUserAgent(userAgent)
          .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 reCAPTCHA tag is: "
                + response.getTokenProperties().getAction());
        System.out.println(
            "The action attribute in the reCAPTCHA tag "
                + "does not match the action ("
                + recaptchaAction
                + ") you are expecting to score");
        return;
      }

      // Get the reason(s) and the risk score.
      // For more information on interpreting the assessment,
      // see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
      for (ClassificationReason reason : response.getRiskAnalysis().getReasonsList()) {
        System.out.println(reason);
      }

      float recaptchaScore = response.getRiskAnalysis().getScore();
      System.out.println("The reCAPTCHA score is: " + recaptchaScore);

      // Get the assessment name (id). Use this to annotate the assessment.
      String assessmentName = response.getName();
      System.out.println(
          "Assessment name: " + assessmentName.substring(assessmentName.lastIndexOf("/") + 1));
    }
  }
}

Node.js

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

 /**
 * Create an assessment to analyze the risk of a UI action. Note that
 * this example does set error boundaries and returns `null` for
 * exceptions.
 *
 * projectID: Google Cloud project ID
 * recaptchaKey: reCAPTCHA key obtained by registering a domain or an app to use the services of reCAPTCHA Enterprise.
 * token: The token obtained from the client on passing the recaptchaKey.
 * recaptchaAction: Action name corresponding to the token.
 * userIpAddress: The IP address of the user sending a request to your backend is available in the HTTP request.
 * userAgent: The user agent is included in the HTTP request in the request header.
 * ja3: JA3 associated with the request.
 */
 async function createAssessment({
   projectID = "your-project-id",
   recaptchaKey = "your-recaptcha-key",
   token = "action-token",
   recaptchaAction = "action-name",
   userIpAddress = "user-ip-address",
   userAgent = "user-agent",
   ja3 = "ja3"
 }) {
   // 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
   // TODO: To avoid memory issues, move this client generation outside
   // of this example, and cache it (recommended) or call client.close()
   // before exiting this method.
   const client = new RecaptchaEnterpriseServiceClient();
   const projectPath = client.projectPath(projectID);

   // Build the assessment request.
   const request = ({
     assessment: {
       event: {
         token: token,
         siteKey: recaptchaKey,
         userIpAddress: userIpAddress,
         userAgent: userAgent,
         ja3: ja3,
       },
     },
     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/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
  // composer require google/cloud-recaptcha-enterprise
  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/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/docs/create-assessment#retrieve_token)
  * @param string $project Your Google Cloud project ID
  */
  function create_assessment(
     string $siteKey,
     string $token,
     string $project
  ): void {
  // TODO: To avoid memory issues, move this client generation outside
  // of this example, and cache it (recommended) or call client.close()
  // before exiting this method.
  $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_KEY',
     'YOUR_USER_RESPONSE_TOKEN',
     'YOUR_GOOGLE_CLOUD_PROJECT_ID'
  );
?>

Python


from google.cloud import recaptchaenterprise_v1
from google.cloud.recaptchaenterprise_v1 import Assessment


def create_assessment(
    project_id: str,
    recaptcha_site_key: str,
    token: str,
    recaptcha_action: str,
    user_ip_address: str,
    user_agent: str,
    ja3: str,
) -> Assessment:
    """Create an assessment to analyze the risk of a UI action.
    Args:
        project_id: GCloud Project ID
        recaptcha_site_key: Site key obtained by registering a domain/app to use recaptcha services.
        token: The token obtained from the client on passing the recaptchaSiteKey.
        recaptcha_action: Action name corresponding to the token.
        user_ip_address: IP address of the user sending a request.
        user_agent: User agent is included in the HTTP request in the request header.
        ja3: JA3 associated with the request.
    """

    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
    event.user_ip_address = user_ip_address
    event.user_agent = user_agent
    event.ja3 = ja3

    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)
        )
        return

    # Check if the expected action was executed.
    if response.token_properties.action != recaptcha_action:
        print(
            "The action attribute in your reCAPTCHA tag does"
            + "not match the action you are expecting to score"
        )
        return
    else:
        # 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
        for reason in response.risk_analysis.reasons:
            print(reason)
        print(
            "The reCAPTCHA score for this token is: "
            + str(response.risk_analysis.score)
        )
        # Get the assessment name (id). Use this to annotate the assessment.
        assessment_name = client.parse_assessment_path(response.name).get("assessment")
        print(f"Assessment name: {assessment_name}")
    return response

Ruby

require "google/cloud/recaptcha_enterprise"

# Create an assessment to analyze the risk of a UI action.
#
# @param site_key [String] Site key obtained by registering a domain/app to use recaptcha services.
# @param token [String] The token obtained from the client on passing the recaptcha site_key.
# @param project_id [String] GCloud Project ID.
# @param recaptcha_action [String] Action name corresponding to the token.
# @return [void]
def create_assessment site_key:, token:, project_id:, recaptcha_action:
  # Create the reCAPTCHA client.
  client = ::Google::Cloud::RecaptchaEnterprise.recaptcha_enterprise_service

  request = { parent: "projects/#{project_id}",
              assessment: {
                event: {
                  site_key: site_key,
                  token: token
                }
              } }

  response = client.create_assessment request

  # Check if the token is valid.
  if !response.token_properties.valid
    puts "The create_assessment() call failed because the token was invalid with the following reason:" \
         "#{response.token_properties.invalid_reason}"
  # Check if the expected action was executed.
  elsif 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
    puts "The reCAPTCHA score for this token is: #{response.risk_analysis.score}"
    response.risk_analysis.reasons.each { |reason| puts reason }
  else
    puts "The action attribute in your reCAPTCHA tag does not match the action you are expecting to score"
  end
end

注:score=0.9 評価のレスポンスでは、reason=LOW_CONFIDENCE とが示される場合があります。これは、新しく作成したキーをフロントエンドに統合すると、reCAPTCHA が正確なリスク分析を返すまでに時間がかかるためです。したがって、正確なリスク分析を行うためには、フロントエンドでキーを作成して統合した後、返されたスコアに基づいてアクションを実行する前に 48 時間待つことをおすすめします。

次のステップ

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