Bewertungen für Websites erstellen

Auf dieser Seite wird erläutert, wie Sie eine Bewertung erstellen, damit Ihr Backend die Authentizität des von reCAPTCHA gesendeten Tokens überprüfen kann. Wenn der Endnutzer eine HTML-Aktion auslöst, sendet reCAPTCHA eine verschlüsselte Antwort, das reCAPTCHA-Antworttoken (auch als Token bezeichnet).

Für jede Art von reCAPTCHA-Schlüsselintegration (Kästchen oder Punktzahl) müssen Sie eine Bewertung erstellen, um die Ergebnisse von execute() in Ihrem Backend zu bewerten. Dazu reichen Sie das generierte Token an den Bewertungsendpunkt ein. reCAPTCHA verarbeitet das eingereichte Token und meldet die Gültigkeit und Punktzahl des Tokens.

Die ersten 10.000 monatlichen reCAPTCHA-Bewertungen sind kostenlos. Wenn Sie nach der monatlichen kostenlosen Testversion weiterhin Bewertungen erstellen möchten Nutzungslimit (10.000 Bewertungen pro Monat) müssen aktiviert sein. Abrechnung für Ihr Google Cloud-Projekt. Weitere Informationen zur Abrechnung Informationen zu reCAPTCHA finden Sie unter Zahlungsinformationen

Hinweise

  1. Umgebung für reCAPTCHA vorbereiten
  2. Sie benötigen die folgende Rolle für Identity and Access Management: reCAPTCHA Enterprise-Agent (roles/recaptchaenterprise.agent).
  3. Installieren Sie punktebasierte Schlüssel oder Kästchenschlüssel auf Ihrer Website.
  4. Richten Sie die Authentifizierung für reCAPTCHA ein.

    Die Authentifizierungsmethode, die Sie auswählen, hängt von der Umgebung ab, in der reCAPTCHA eingerichtet ist. In der folgenden Tabelle finden Sie Informationen zur Auswahl der geeigneten Authentifizierungsmethode und der unterstützten Benutzeroberfläche für die Authentifizierung:

    Umgebung Schnittstelle Authentifizierungsmethode
    Google Cloud
    • REST
    • Clientbibliotheken
    		 Verwenden Sie angehängte Dienstkonten.
    Lokal oder bei einem anderen Cloud-Anbieter REST Verwenden Sie API-Schlüssel oder die Workload Identity-Föderation.

    Wenn Sie API-Schlüssel verwenden möchten, empfehlen wir, die API-Schlüssel durch Anwenden von Einschränkungen für API-Schlüssel zu sichern.
    Clientbibliotheken

    Verwenden Sie:

Token abrufen

Rufen Sie mit einer der folgenden Methoden ein Token von Webseiten ab:

  • Der aufgelöste Wert, der durch den Aufruf von grecaptcha.enterprise.execute() zurückgegeben wird.
  • Verwenden Sie den POST-Parameter g-recaptcha-response, wenn ein Nutzer ein Formular auf Ihrer Website sendet.
  • Als Stringargument für Ihre Callback-Funktion, wenn data-callback entweder im g-recaptchaHTML-Tagattribut oder im Callback-Parameter in der Methode grecaptcha.enterprise.render angegeben ist

Sie können nur einmal auf das Token eines Nutzers zugreifen. Wenn Sie eine nachfolgende Aktion bewerten müssen, die ein Nutzer auf Ihrer Website ausführt, oder wenn ein Token abläuft, bevor eine Bewertung erstellt wird, müssen Sie execute() noch einmal aufrufen, um ein neues Token zu generieren.

Bewertung erstellen

Nachdem Sie die Authentifizierung eingerichtet haben, können Sie eine Bewertung erstellen. Senden Sie dazu eine Anfrage an die reCAPTCHA Enterprise API oder verwenden Sie die reCAPTCHA-Clientbibliotheken.

Zur Verbesserung der Erkennung empfehlen wir, beim Erstellen von Bewertungen die folgenden zusätzlichen Werte zu übergeben:

  • userAgent: Der User-Agent ist in der HTTP-Anfrage im Anfrageheader enthalten. Weitere Informationen finden Sie unter Weitere Informationen zum Anfrageheader User-Agent in der Dokumentation zum Mozilla Developer Network.
  • userIpAddress: Die IP-Adresse des Nutzers, der eine Anfrage an Ihr Back-End sendet, ist in der HTTP-Anfrage verfügbar. Wenn Sie einen Proxyserver verwenden, ist die IP-Adresse im X-Forwarded-For-Anfrageheader verfügbar. Weitere Informationen zum Abrufen der IP-Adresse finden Sie unter X-Forwarded-For.
  • ja3: JA3 ist eine Open-Source-Methode zum Erstellen von TLS-Client-Fingerabdrücken. Weitere Informationen zur Verwendung von JA3 zum Erstellen eines TLS-Fingerabdrucks finden Sie in der JA3-Dokumentation, .

So können Sie Ihre Website und mobilen Anwendungen besser vor fortgeschrittenen Angriffsmustern und von Menschen verursachtem Missbrauch schützen.

Die Methode zum Erstellen einer Bewertung ist für punktebasierte und Kästchen von Websiteschlüsseln identisch.

REST API

Erstellen Sie eine Bewertung, indem Sie eine Anfrage an die reCAPTCHA API senden. Sie können entweder die gcloud CLI oder den API-Schlüssel für die Authentifizierung verwenden.

gcloud CLI verwenden

Erstellen Sie mit der Methode projects.assessments.create eine Bewertung. Senden Sie diese Anfrage an den API-Endpunkt v1.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Google Cloud-Projekt-ID
  • TOKEN: vom Aufruf grecaptcha.enterprise.execute() zurückgegebenes Token
  • KEY_ID: der reCAPTCHA-Schlüssel, der mit der Website oder Anwendung verknüpft ist. Weitere Informationen finden Sie unter reCAPTCHA-Schlüssel.
  • USER_AGENT: Der User-Agent in der Anfrage vom Gerät des Nutzers.
  • USER_IP_ADDRESS: die IP-Adresse in der Anfrage vom Gerät des Nutzers.
  • JA3: JA3-Fingerabdruck für den SSL-Client. Wir empfehlen, salesforce/ja3 zum Berechnen von JA3 zu verwenden.
  • USER_ACTION: die vom Nutzer initiierte Aktion, die Sie für action angegeben haben im grecaptcha.enterprise.execute()-Aufruf enthalten, z. B. login.

    Weitere Informationen Siehe Aktionsnamen.

HTTP-Methode und URL:

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

JSON-Text der Anfrage:

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

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

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

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

$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

Sie sollten in etwa folgende JSON-Antwort erhalten:

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

Wir empfehlen, JSON-Parser im nicht strengen Parsing-Modus zu verwenden, um Ausfälle zu vermeiden, wenn der JSON-Antwort zusätzliche Felder hinzugefügt werden.

API-Schlüssel verwenden

Erstellen Sie eine Bewertung mit der Methode projects.assessments.create. Senden Sie diese Anfrage an den API-Endpunkt v1.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • API_KEY: API-Schlüssel, der dem aktuellen Projekt zugeordnet ist
  • PROJECT_ID: Ihre Google Cloud-Projekt-ID
  • TOKEN: vom Aufruf grecaptcha.enterprise.execute() zurückgegebenes Token
  • KEY_ID: der reCAPTCHA-Schlüssel, der der Website oder App zugeordnet ist. Weitere Informationen finden Sie unter reCAPTCHA-Schlüssel.
  • USER_AGENT: der User-Agent in der Anfrage vom Gerät des Nutzers.
  • USER_IP_ADDRESS: die IP-Adresse in der Anfrage vom Gerät des Nutzers.
  • JA3: JA3-Fingerabdruck für den SSL-Client. Wir empfehlen, salesforce/ja3 zum Berechnen von JA3 zu verwenden.
  • USER_ACTION: Die vom Nutzer initiierte Aktion, die Sie im grecaptcha.enterprise.execute()-Aufruf für action angegeben haben, z. B. login.

    Weitere Informationen finden Sie unter Aktionsnamen.

HTTP-Methode und URL:

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

JSON-Text der Anfrage:

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

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

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

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

$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

Sie sollten in etwa folgende JSON-Antwort erhalten:

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

Wir empfehlen, JSON-Parser im nicht strengen Parsing-Modus zu verwenden, um Ausfälle zu vermeiden, wenn der JSON-Antwort zusätzliche Felder hinzugefügt werden.

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

Nächste Schritte