Skip to main content
Denna artikel kommer att introducera en Cloudflare Turnstile protokolligenkänning API integrationsbeskrivning, som gör det möjligt för användare att verifiera utan att behöva identifiera och klicka på Turnstile CAPTCHA, utan endast genom att skicka in Website Key för att uppnå automatisk avkodning i bakgrunden och slutföra verifieringen.

​
Ansökningsprocess

För att använda Cloudflare Turnstile protokolligenkänning API, börja med att gå till Ace Data Cloud-konsolen för att hämta din API-token, som du kan spara för framtida bruk. Om du inte har loggat in eller registrerat dig, kommer du automatiskt att omdirigeras till inloggningssidan för att registrera dig och logga in, och efter att ha slutfört detta kommer du automatiskt att återvända till den aktuella sidan. En API-token kan användas för att anropa alla tjänster på plattformen, utan att behöva ansöka separat för varje tjänst. Första gången du ansöker får du en gratis kvot för att prova; om kvoten tar slut kan du ladda på allmän balans i konsolen.
📘 Fullständig dokumentation: Cloudflare Turnstile protokolligenkänning API →

​
Grundläggande användning

Först bör du förstå den grundläggande användningen, vilket innebär att du anger URL:en för den webbplats som behöver hantera Turnstile CAPTCHA, så får du det bearbetade resultatet. Du behöver först enkelt skicka ett website_url-fält, vår exempelwebbplats är: https://react-turnstile.vercel.app, vi behöver hämta website_key från website_url-sidan. Öppna denna webbsida, tryck på F12 för att gå till konsolen, och gör en global sökning på cf-turnstile på Element-sidan, så hittar du behållarelementet som bär Turnstile, där data-sitekey motsvarar en sträng som är värdet av website_key. De inställda begärningshuvudena inkluderar:
  • accept: vilken typ av svar du vill ta emot, här fylls i som application/json, det vill säga JSON-format.
  • authorization: nyckeln för att anropa API:et, som kan väljas direkt efter ansökan.
Dessutom ställs begärningskroppen in, inklusive:
  • website_url: URL:en för webbplatsen som behöver hantera CAPTCHA.
  • website_key: webbplatsens nyckelidentifierare (sitekey) i Cloudflare Turnstile.
  • action: valfri parameter, som endast behöver skickas om målsidan har ställt in en anpassad action för Turnstile-komponenten.
  • cdata: valfri parameter, som endast behöver skickas om målsidan har ställt in en anpassad cData för Turnstile-komponenten.
Klicka på “Try” knappen för att göra ett test, här får vi följande resultat:
Det returnerade resultatet har flera fält, som beskrivs nedan:
  • token, verifieringsresultatet efter att ha bearbetat Turnstile CAPTCHA-uppgiften.
  • started_at, finished_at: tiden för när denna begäran började bearbetas och när resultatet producerades, Unix-tidsstämpel (sekunder, flyttal).
  • elapsed: den totala tiden för denna bearbetning (sekunder).
Vi kan se att vi har fått verifieringsresultatet för att bearbeta Turnstile CAPTCHA, och vi kan använda det för att POST:a eller simulera en inlämning till målsidan, engångsanvändning, giltighetstid 120 sekunder, rekommenderas att använda inom 60 sekunder. Vid inlämning skickas vanligtvis denna token som cf-turnstile-response-parameter till målsidan, koden för att anropa tokenverifieringen i Python ser ut som följer:
Om du vill generera motsvarande integrationskod kan du direkt kopiera den som genereras, till exempel CURL-koden ser ut som följer:
Python-integrationskoden ser ut som följer:

​
Asynkron läge (async)

Som standard är API:et synkront och blockerande: en begäran kommer att vänta tills tokenbearbetningen är klar innan den returneras. Om du gör en multipel lösare rotation och vill “få task_id omedelbart efter att ha skickat in uppgiften, först schemalägga andra lösare, och sedan återkomma för att läsa resultatet”, kan du skicka in async: true i begärningskroppen. När du skickar in async: true kommer gränssnittet omedelbart att returnera en task_id, utan att blockera och vänta:
Om du vill kontrollera framstegen aktivt kan du använda den task_id för att fråga POST /captcha/tasks (rekommenderas var 3-5 sekund). Detta gränssnitt kommer inte att utlösa eller påskynda uppgiftsbearbetningen; även om du inte frågar, tappar internetanslutningen eller stänger klienten, kommer servern fortfarande att fortsätta bearbeta:
Under bearbetning kommer det att returnera status: processing; när bearbetningen är klar kommer det att returnera status: ready och token:
Avgiftsbeskrivning: I asynkront läge debiteras inte skapandet av uppgifter och läsning av “bearbetning pågår”-status; klienten debiteras en gång när den första framgångsrika resultatet läses (samma som nuvarande beteende och priser för synkront läge). Servern kommer att driva uppgiften själv, men kommer inte att debitera i förväg bara för att bakgrunden är klar. Om uppgiften inte lyckas inom 120 sekunder kommer den att avslutas med HTTP 504 timeout, utan debitering. /captcha/tasks ansvarar inte för att driva uppgiften.
Notering: Cloudflare Turnstile stöder för närvarande inte egen proxy (Bring Your Own Proxy), så detta gränssnitt accepterar inte proxy-parametern; om den skickas in kommer det att returnera 400 invalid_proxy.

​
Felhantering

När du anropar API:et, om du stöter på fel, kommer API:et att returnera motsvarande felkod och information. Till exempel:
  • 400 token_mismatched：Dålig begäran, möjligtvis på grund av saknade eller ogiltiga parametrar.
  • 400 invalid_proxy：Dålig begäran, proxy stöds inte för denna captcha-typ.
  • 401 invalid_token：Obehörig, ogiltig eller saknad auktoriseringstoken.
  • 429 too_many_requests：För många begärningar, du har överskridit hastighetsgränsen.
  • 500 api_error：Internt serverfel, något gick fel på servern.

​
Felrespons exempel

​
Slutsats

Genom detta dokument har du fått en förståelse för hur man använder Cloudflare Turnstile-protokollet för att identifiera API så att användare inte behöver identifiera och klicka på Turnstile-verifieringen, utan endast behöver skicka in Website Key för att möjliggöra automatisk avkodning i bakgrunden och slutföra verifieringen. Vi hoppas att detta dokument kan hjälpa dig att bättre integrera och använda detta API. Om du har några frågor, tveka inte att kontakta vårt tekniska supportteam.