Nutzerantwort-Tokens mit dem alten SiteVerify überprüfen

Auf dieser Seite wird beschrieben, wie Sie die Antwort eines Nutzers auf eine reCAPTCHA-Aufgabe im Backend Ihrer Anwendung mit dem Legacy-API-Endpunkt SiteVerify (https://www.google.com/recaptcha/api/siteverify) prüfen. Verwenden Sie diesen Endpunkt nur, wenn Sie eine Legacy-Integration oder ein Drittanbieter-Plug-in verwalten, das CreateAssessment nicht verwenden kann.

Hinweis

Um den SiteVerify-Endpunkt aufzurufen, benötigen Sie den geheimen Legacy-Schlüssel Ihres Schlüssels. Informationen zum Abrufen des geheimen Schlüssels in der Google Cloud Console finden Sie unter Geheimen Schlüssel in der Google Cloud Console abrufen. Bewahren Sie Ihren geheimen Schlüssel auf Ihrem Backend-Server sicher auf und geben Sie ihn niemals im clientseitigen Code preis.

Antwort-Token des Nutzers abrufen

Bei Legacy-Webintegrationen wird die nicht für Unternehmen bestimmte JavaScript API (https://www.google.com/recaptcha/api.js) geladen, die Methoden für das grecaptcha-Objekt anstelle von grecaptcha.enterprise bereitstellt. Sie können das Antworttoken des Nutzers auf Ihrem Frontend auf eine der folgenden Arten abrufen:

  • Aus dem g-recaptcha-response-POST-Parameter, wenn der Nutzer ein Formular auf Ihrer Website einreicht.
  • Durch Aufrufen von grecaptcha.getResponse(opt_widget_id), nachdem der Nutzer eine reCAPTCHA v2-Aufgabe abgeschlossen hat. Diese Methode gibt das Antwort-Token als String zurück oder einen leeren String, wenn die Challenge nicht abgeschlossen wurde. Der optionale Parameter opt_widget_id gibt die Widget-ID an, die von grecaptcha.render() zurückgegeben wird. Wenn er weggelassen wird, wird standardmäßig das erste erstellte Widget verwendet.
  • Als Stringargument, das an Ihre Callback-Funktion übergeben wird, wenn der Nutzer eine Aufgabe abschließt, sofern Sie den Namen der Callback-Funktion entweder im Attribut data-callback des HTML-Elements g-recaptcha oder im Parameter callback der Methode grecaptcha.render(container, parameters) angeben.
  • Aus dem aufgelösten Wert von Promise, der von grecaptcha.execute(site_key, {action: action_name}) für punktebasierte (v3)-Schlüssel zurückgegeben wird.

Die alten grecaptcha-Methoden (render, getResponse, execute, ready und reset) und g-recaptcha-Tag-Attribute verwenden dieselben Parameter wie die grecaptcha.enterprise-Entsprechungen. Weitere Informationen zu den Parametern finden Sie in der JavaScript API-Referenz für reCAPTCHA.

Informationen zur Migration zur aktualisierten reCAPTCHA JavaScript API finden Sie unter reCAPTCHA JavaScript API migrieren.

Tokeneinschränkungen

Jedes reCAPTCHA-Antworttoken eines Nutzers ist zwei Minuten lang gültig und kann nur einmal verifiziert werden, um Replay-Angriffe zu verhindern. Überprüfen Sie das Antworttoken innerhalb von zwei Minuten nach Erhalt mit reCAPTCHA. Wenn Sie ein neues Token benötigen, führen Sie die reCAPTCHA-Überprüfung noch einmal aus.

API-Anfrage

Senden Sie eine Anfrage mit dem folgenden Endpunkt und der folgenden Methode:

  • URL: https://www.google.com/recaptcha/api/siteverify (oder https://www.recaptcha.net/recaptcha/api/siteverify, wenn www.google.com nicht zugänglich ist; siehe reCAPTCHA global verwenden)
  • Methode: POST

Fügen Sie der Anfrage die folgenden POST-Parameter hinzu:

POST-Parameter Beschreibung
secret Erforderlich. Der geteilte geheime Schlüssel zwischen Ihrer Website und reCAPTCHA.
response Erforderlich. Das Antworttoken des Nutzers, das von der clientseitigen reCAPTCHA-Integration auf Ihrer Website bereitgestellt wird.
remoteip Optional. Die IP‑Adresse des Nutzers.

API-Antwort

Der SiteVerify-Endpunkt gibt ein JSON-Objekt zurück.

Bei Webintegrationen (Schlüssel für Score-basiertes v3, Checkbox v2 oder unsichtbares v2) hat die Antwort das folgende Format:

{
  "success": true|false,      // whether this request was a valid reCAPTCHA token for your site
  "score": number,            // the score for this request (0.0 - 1.0) for score-based (v3) keys
  "action": string,           // the action name for this request (important to verify)
  "challenge_ts": timestamp,  // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
  "hostname": string,         // the hostname of the site where the reCAPTCHA was solved
  "error-codes": [...]        // optional
}

Fehlercode-Referenz

In der folgenden Tabelle werden die Fehlercodes beschrieben, die im error-codes-Array angezeigt werden können:

Fehlercode Beschreibung
missing-input-secret Der Parameter secret fehlt.
invalid-input-secret Der Parameter secret ist ungültig oder fehlerhaft.
missing-input-response Der Parameter response fehlt.
invalid-input-response Der Parameter response ist ungültig oder fehlerhaft.
bad-request Die Anfrage ist ungültig oder fehlerhaft.
timeout-or-duplicate Die Antwort ist nicht mehr gültig, weil sie abgelaufen ist oder bereits verwendet wurde.

Nächste Schritte