Skip to main content
Dieser Artikel beschreibt eine Cloudflare Turnstile Protokoll Erkennungs-API-Integrationsanleitung, die es Benutzern ermöglicht, Turnstile-Captchas ohne Erkennung und Auswahl zu umgehen, indem sie einfach den Website-Schlüssel einreichen, um die automatische Dekodierung im Hintergrund durchzuführen und die Verifizierung abzuschließen.

​
Antragsprozess

Um die Cloudflare Turnstile Protokoll Erkennungs-API zu verwenden, gehen Sie zunächst zur Ace Data Cloud Konsole, um Ihr API-Token zu erhalten und es für zukünftige Verwendung zu speichern. Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, die Sie zur Registrierung und Anmeldung einlädt. Nach Abschluss werden Sie automatisch zur aktuellen Seite zurückgeleitet. Ein API-Token reicht aus, um auf alle Dienste der Plattform zuzugreifen, ohne dass für jeden Dienst separat beantragt werden muss. Bei der ersten Beantragung erhalten Sie ein kostenloses Kontingent, um es kostenlos auszuprobieren; wenn das Kontingent erschöpft ist, können Sie im Dashboard Ihr Guthaben aufladen.
📘 Vollständige Dokumentation: Cloudflare Turnstile Protokoll Erkennungs-API →

​
Grundlegende Nutzung

Zunächst sollten Sie die grundlegende Nutzung verstehen, indem Sie die URL der Website eingeben, die das Turnstile-Captcha verarbeitet, um das verarbeitete Ergebnis zu erhalten. Zuerst müssen Sie einfach ein website_url-Feld übergeben. Unsere Beispielwebsite ist: https://react-turnstile.vercel.app, und wir müssen den website_key auf der website_url-Seite abrufen. Öffnen Sie diese Webseite, drücken Sie F12, um die Konsole zu öffnen, und suchen Sie im Element-Bereich global nach cf-turnstile. Dort finden Sie das Container-Element, das Turnstile enthält, wobei der Wert von data-sitekey die Zeichenfolge ist, die dem website_key entspricht. Die festgelegten Request-Header umfassen:
  • accept: In welchem Format Sie die Antwort erhalten möchten, hier eingetragen als application/json, also im JSON-Format.
  • authorization: Der Schlüssel zur API-Nutzung, den Sie nach der Beantragung direkt auswählen können.
Zusätzlich wurde der Request-Body festgelegt, der Folgendes umfasst:
  • website_url: Die URL der Website, die das Captcha verarbeiten soll.
  • website_key: Der Website-Schlüssel-Identifikator (sitekey) in Cloudflare Turnstile.
  • action: Optionales Parameter, das nur übergeben werden muss, wenn die Zielwebsite eine benutzerdefinierte action für das Turnstile-Element festgelegt hat.
  • cdata: Optionales Parameter, das nur übergeben werden muss, wenn die Zielwebsite eine benutzerdefinierte cData für das Turnstile-Element festgelegt hat.
Klicken Sie auf die Schaltfläche „Try“, um einen Test durchzuführen, und wir erhalten folgendes Ergebnis:
Die Rückgabe enthält mehrere Felder, die wie folgt beschrieben werden:
  • token, das Ergebnis der Verifizierung des Turnstile-Captcha-Auftrags.
  • started_at, finished_at: Die Zeit, zu der die Anfrage bearbeitet und das Ergebnis erzeugt wurde, Unix-Zeitstempel (Sekunden, Fließkomma).
  • elapsed: Die gesamte Bearbeitungszeit (Sekunden).
Wir können sehen, dass wir das Verifizierungsergebnis des Turnstile-Captchas erhalten haben, das wir dann für POST oder zur Simulation der Einreichung an die Zielwebsite verwenden können, einmalige Verwendung, Gültigkeit 120s, empfohlen innerhalb von 60s zu verwenden. Bei der Einreichung wird dieser Token normalerweise als cf-turnstile-response-Parameter zusammen mit an die Zielwebsite gesendet. Der Python-Code zur Verifizierung des Tokens sieht wie folgt aus:
Wenn Sie außerdem den entsprechenden Integrationscode generieren möchten, können Sie ihn direkt kopieren, zum Beispiel sieht der CURL-Code wie folgt aus:
Der Python-Integrationscode sieht wie folgt aus:

​
Asynchroner Modus (async)

Standardmäßig ist die API synchron blockierend: Eine Anfrage wartet, bis die Tokenverarbeitung abgeschlossen ist, bevor sie zurückgegeben wird. Wenn Sie eine Multi-Solver-Rotation durchführen und „nach der Einreichung der Aufgabe sofort die task_id erhalten möchten, um andere Solver zu planen und später zurückzukehren, um die Ergebnisse abzurufen“, können Sie im Anfragekörper async: true übergeben. Nach der Übergabe von async: true gibt die Schnittstelle sofort eine task_id zurück, ohne zu blockieren:
Um den Fortschritt aktiv zu überprüfen, können Sie diese task_id verwenden, um POST /captcha/tasks abzufragen (empfohlen alle 3-5 Sekunden). Diese Schnittstelle löst oder beschleunigt die Aufgabenbearbeitung nicht; selbst wenn Sie nicht abfragen, die Verbindung unterbrochen wird oder der Client beendet wird, wird der Server weiterhin die Verarbeitung durchführen:
Während der Verarbeitung wird status: processing zurückgegeben; nach Abschluss der Verarbeitung wird status: ready und der Token zurückgegeben:
Abrechnungsinformationen: Im asynchronen Modus werden die Erstellung von Aufgaben und das Abrufen des „verarbeiteten“ Status nicht berechnet; der Client wird einmal berechnet, wenn er das erste erfolgreiche Ergebnis abruft (entspricht dem aktuellen Verhalten und den Preisen im synchronen Modus). Der Server wird die Aufgaben selbstständig vorantreiben, aber es wird keine Gebühr erhoben, nur weil die Verarbeitung im Hintergrund abgeschlossen ist. Wenn die Aufgabe innerhalb von 120 Sekunden nicht erfolgreich ist, wird sie mit HTTP 504 timeout beendet, ohne Gebühren. /captcha/tasks ist nicht dafür verantwortlich, die Aufgaben voranzutreiben.
Hinweis: Cloudflare Turnstile unterstützt derzeit keine eigenen Proxys (Bring Your Own Proxy), daher akzeptiert diese Schnittstelle keinen proxy-Parameter; wenn übergeben, wird 400 invalid_proxy zurückgegeben.

​
Fehlerbehandlung

Wenn beim Aufruf der API ein Fehler auftritt, gibt die API den entsprechenden Fehlercode und die Informationen zurück. Zum Beispiel:
  • 400 token_mismatched：Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter.
  • 400 invalid_proxy：Ungültige Anfrage, Proxy wird für diesen Captcha-Typ nicht unterstützt.
  • 401 invalid_token：Unbefugt, ungültiger oder fehlender Autorisierungstoken.
  • 429 too_many_requests：Zu viele Anfragen, Sie haben das Rate-Limit überschritten.
  • 500 api_error：Interner Serverfehler, etwas ist auf dem Server schiefgegangen.

​
Fehlerantwort Beispiel

​
Fazit

Durch dieses Dokument haben Sie gelernt, wie Sie die Cloudflare Turnstile-Protokoll-Identifizierungs-API verwenden, um Benutzern die Identifizierung und das Klicken auf das Turnstile-Captcha zu ersparen, indem Sie lediglich den Website-Schlüssel einreichen, um die automatische Dekodierung im Hintergrund durchzuführen und die Überprüfung abzuschließen. Wir hoffen, dass dieses Dokument Ihnen hilft, die API besser zu integrieren und zu nutzen. Bei Fragen wenden Sie sich bitte jederzeit an unser technisches Support-Team.