Bewertung erstellen

Auf dieser Seite erfahren Sie, wie Sie das reCAPTCHA-Antworttoken eines Nutzers im Back-End Ihrer Anwendung bewerten.

Für jede Art von Website-Schlüsselintegration (Kästchen oder Punktzahl) müssen Sie das generierte Token an den Bewertungsendpunkt senden. reCAPTCHA Enterprise verarbeitet das gesendete Token und meldet die Gültigkeit und Punktzahl des Tokens.

Hinweis

Wählen Sie die beste Methode zum Einrichten von reCAPTCHA Enterprise in Ihrer Umgebung und schließen Sie die Einrichtung ab.

Antworttoken des Nutzers abrufen

Sie haben zwei Möglichkeiten, das Antwort-Token des Nutzers von den Webseiten abzurufen:

  • Der aufgelöste Wert, der vom Aufruf an grecaptcha.enterprise.execute() zurückgegeben wird.
  • g-recaptcha-response POST verwenden, wenn ein Nutzer das Formular auf Ihrer Website absendet.
  • Als Stringargument für Ihre Callback-Funktion, wenn data-callback entweder im HTML-Tag-Attribut g-recaptcha oder im Callback-Parameter in der Methode grecaptcha.enterprise.render.

Informationen zum Abrufen des Antworttokens des Nutzers aus mobilen Apps finden Sie unter CAPTCHA Enterprise in iOS-Apps einbinden oder reCAPTCHA Enterprise in Android-Apps integrieren.

Sie können nur einmal auf das reCAPTCHA-Antworttoken jedes 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

Erstellen Sie eine Bewertung, indem Sie eine Anfrage an die reCAPTCHA Enterprise API oder die reCAPTCHA Enterprise-Clientbibliotheken senden. Sie sollten die Methode auswählen, mit der eine Prüfung erstellt wird, je nachdem, wo Sie reCAPTCHA Enterprise eingerichtet haben.

Auswahlmethode erstellen

Die Methoden zum Erstellen einer Bewertung hängen von Ihrer Umgebung ab:

Umgebung Methoden zum Erstellen einer Bewertung
Google Cloud App Engine oder GKE reCAPTCHA Enterprise-Clientbibliotheken
Google Cloud Compute Engine

Eine der folgenden Optionen:

  • reCAPTCHA Enterprise REST API mit dem gcloud-Tool zur Authentifizierung
  • reCAPTCHA Enterprise-Clientbibliotheken
Drittanbieter-Cloud oder lokale Umgebung, die Dienstkonten unterstützt

Eine der folgenden Optionen:

  • reCAPTCHA Enterprise REST API mit dem gcloud-Tool zur Authentifizierung
  • reCAPTCHA Enterprise-Clientbibliotheken
Cloud oder Drittanbieter-Clouds, die keine Dienstkonten unterstützen reCAPTCHA Enterprise REST API mit API-Schlüsseln für die Authentifizierung
Migrierte Umgebung mit zusätzlichen reCAPTCHA Enterprise-Features wie Multi-Faktor-Authentifizierung (MFA)

Eine der folgenden Optionen:

  • reCAPTCHA Enterprise REST API mit dem gcloud-Tool zur Authentifizierung
  • reCAPTCHA Enterprise REST API mit API-Schlüsseln für die Authentifizierung

Bewertung mit der REST API oder Clientbibliotheken erstellen

Nachdem Sie die passende Methode zum Erstellen einer Bewertung ausgewählt haben, führen Sie die folgenden Schritte aus, um eine Bewertung zu erstellen.

REST API

Erstellen Sie eine Bewertung, indem Sie eine Anfrage an die reCAPTCHA Enterprise API senden. Sie können entweder das gcloud-Tool oder den API-Schlüssel zur Authentifizierung verwenden.

Mit dem gcloud-Tool authentifizieren

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

Ersetzen Sie diese Werte in den folgenden Anweisungen:

  • PROJECT_ID: Ihre Google Cloud-Projekt-ID
  • TOKEN: vom Aufruf grecaptcha.enterprise.execute() zurückgegebenes Token
  • KEY: reCAPTCHA-Schlüssel, der mit der Website/App verknüpft ist
  • USER_ACTION (nur für punktbasierte Websiteschlüsselintegrationen): Die vom Nutzer initiierte Aktion, die Sie für action im Aufruf von grecaptcha.enterprise.execute() festgelegt haben, z. B. login. Weitere Informationen finden Sie unter Aktionen.

HTTP-Methode und URL:

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

JSON-Text der Anfrage:

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY",
    "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 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

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

$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

Sie sollten eine JSON-Antwort ähnlich wie diese 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",
    "expectedAction": "USER_ACTION"
  },
  "name": "projects/PROJECT_ID/assessments/b6ac310000000000"
}

Mit einem API-Schlüssel authentifizieren

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

Ersetzen Sie diese Werte in den folgenden Anweisungen:

  • 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
  • KEYkey: reCAPTCHA Schlüssel, der der Website/App zugeordnet ist
  • USER_ACTION (nur für punktbasierte Websiteschlüsselintegrationen): Die vom Nutzer initiierte Aktion, die Sie für action im Aufruf von grecaptcha.enterprise.execute() festgelegt haben, z. B. login. Weitere Informationen finden Sie unter Aktionen.

HTTP-Methode und URL:

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

JSON-Text der Anfrage:

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY",
    "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/v1beta1/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/v1beta1/projects/PROJECT_ID/assessments?key=API_KEY" | Select-Object -Expand Content

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

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

C#

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

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

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

            RecaptchaEnterpriseServiceClient client =
                RecaptchaEnterpriseServiceClient.Create();

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

            Assessment response = client.CreateAssessment(createAssessmentRequest);

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

                }

            }

        }
    }
}

Go

package main

import (
  "context"
  "fmt"

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

func main() {

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

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

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

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

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

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

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

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

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 = "user_response_token";
          String projectPath = "projects/your_project_name";
          String recaptchaAction = "name_of_action_to_protect";

          RecaptchaEnterpriseServiceClient client =
                  RecaptchaEnterpriseServiceClient.create();

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

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

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

          Assessment response =
                  client.createAssessment(createAssessmentRequest);

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

Node.js

    function main() {

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

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

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

    const assessment = ({
        event: event
    });

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

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

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

main();

PHP

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

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

 $client = new RecaptchaEnterpriseServiceClient();

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

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

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

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

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

Python

  from google.cloud import recaptchaenterprise_v1

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

  client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()

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

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

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

  response = client.create_assessment(request)

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

Ruby

  require "google/cloud/recaptcha_enterprise/v1"

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

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

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

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

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

  response = client.create_assessment(request)

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

Nächste Schritte