Den CAPTCHA-Solver in Express verwenden

Verwenden Sie Node.js 22 oder neuer und Express 5. Installieren Sie das offizielle JavaScript-SDK über die Tarball-Installation in der Dokumentation, statt davon auszugehen, dass es in der npm-Registry veröffentlicht ist. Das Beispiel erstellt einen einzelnen Solvethree-Client außerhalb der Handler.

• SOLVETHREE_API_KEY: der API-Schlüssel Ihres Workspace. Bewahren Sie ihn auf dem Server auf.
• INTEGRATION_KEY: ein separates Geheimnis für vertrauenswürdige interne Aufrufer. Das Beispiel verlangt es im Header x-integration-key; geben Sie es nicht an Browser-Clients weiter. Wenn Sie bereits Authentifizierungs-Middleware haben, verwenden Sie diese anstelle des Schutzes per gemeinsamem Schlüssel aus dem Beispiel.
• CAPTCHA_SITE: der Zielhostname, keine vollständige URL. Richten Sie vor dem Erstellen von Aufgaben ein aktives Website-Profil für Ihren Workspace ein; das Senden eines Hostnamens erstellt keines.
• SOLVETHREE_PROXY: der Proxy für dieses Ziel. Das Beispiel übergibt einen einzelnen Proxy und legt die Aktion auf login fest. Ändern Sie diese Aktion serverseitig, wenn Ihr Ziel eine andere verwendet.

Diese Anfrage verwendet die Standardkonfiguration für reCAPTCHA Enterprise. Sie benötigt site, action und einen Proxy – nicht type oder url. Siehe Website-Profil einrichten, falls das Ziel noch nicht konfiguriert ist.

// npm install express and the official solvethree SDK tarball.
import express from 'express';
import { Solvethree, SolvethreeError } from '@solvethree/sdk';
const app = express();
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
const secret = process.env.INTEGRATION_KEY;
if (!secret) throw new Error('Set INTEGRATION_KEY');
app.use((request, response, next) => {
  if (request.get('x-integration-key') !== secret) return response.sendStatus(401);
  next();
});
app.post('/captcha/tasks', async (request, response) => {
  const task = await client.createTask({
    site: process.env.CAPTCHA_SITE, action: 'login', proxy: process.env.SOLVETHREE_PROXY,
    requestId: request.get('x-request-id'),
  }, { waitMs: 0, signal: AbortSignal.timeout(20000) });
  response.json(task);
});
app.get('/captcha/tasks/:id', async (request, response) => {
  response.json(await client.getTask(request.params.id, { waitMs: 15000, signal: AbortSignal.timeout(25000) }));
});
app.use((error, request, response, next) => {
  if (error instanceof SolvethreeError) return response.status(502).json({ requestId: error.requestId, taskId: error.taskId });
  response.status(400).json({ error: 'Invalid task input or ID' });
});
app.listen(3000);

Beide Routen sind durch die Authentifizierungsprüfung geschützt. Der POST-Handler übernimmt Hostname, Aktion und Proxy aus der Serverkonfiguration, nicht aus dem Anfrage-Body. Nur die optionale Kennung für die Erstellung stammt vom Aufrufer.

1. 1.

   Request-ID vor der Erstellung zuweisen

   Senden Sie x-request-id mit 1–64 ASCII-Buchstaben, Ziffern, Unterstrichen oder Bindestrichen. Bewahren Sie die ID zusammen mit der logischen Anfrage auf, damit Sie die Aufgabe bei einem Verbindungs-Timeout wiederfinden können.

2. 2.

   Einmal eine POST-Anfrage an /captcha/tasks senden

   Der Handler ruft createTask mit waitMs: 0 auf und gibt die Aufgabe zurück. Bewahren Sie ihre ID auf. Eine erfolgreiche Antwort bedeutet, dass Sie eine Aufgabe haben, nicht unbedingt eine Lösung.

3. 3.

   Status per GET abrufen

   Rufen Sie /captcha/tasks/:id auf. Wiederholen Sie den Abruf, solange der Status pending oder solving ist; wiederholen Sie nicht die POST-Anfrage, um den Fortschritt zu prüfen. Beenden Sie den Abruf bei ready oder failed.

4. 4.

   Nur eine fertige Lösung verwenden

   Übermitteln Sie das Token mit den zurückgegebenen Werten für userAgent und secChUa und verwenden Sie dabei denselben konfigurierten Proxy und das vorgesehene Ziel. Das SDK übernimmt die Übermittlung nicht für Sie. Eine bereite Aufgabe bedeutet, dass eine Lösung generiert wurde, nicht dass das Ziel Ihre Anwendungsanfrage akzeptiert hat.

Der POST-SDK-Aufruf hat ein AbortSignal-Zeitlimit von 20 Sekunden. GET erlaubt eine Wartezeit von 15 Sekunden auf die Aufgabe innerhalb eines Zeitlimits von 25 Sekunden für den SDK-Aufruf. Eine GET-Antwort kann weiterhin einen nicht abgeschlossenen Zustand melden; prüfen Sie ihren Status, statt das Ende der Wartezeit als fehlgeschlagenen Lösungsversuch zu werten.

Ein Timeout bei der Erstellung beweist nicht, dass solvethree die Anfrage abgelehnt hat. Wenn Sie eine Aufgaben-ID erhalten haben, rufen Sie die Aufgabe ab. Andernfalls wiederholen Sie die Erstellung mit derselben Request-ID und unveränderten Aufgabeneingaben, um die bestehende Aufgabe wiederzufinden. Die Wiederverwendung dieser ID mit anderen Eingaben führt zu einem Konflikt. Ohne eine gespeicherte Request-ID besteht bei einer neuen POST-Anfrage das Risiko, eine separate Aufgabe zu erstellen.

Express 5 leitet abgelehnte asynchrone Handler an die Fehler-Middleware weiter. Das Beispiel gibt für SolvethreeError HTTP 502 zurück und legt nur die Anfrage- und Aufgabenkennungen offen – nicht den unverarbeiteten Fehler, Zugangsdaten oder die Lösung. Die HTTP-400-Fallback-Antwort ist allgemein gehalten; sie klassifiziert nicht jeden Nicht-SDK-Fehler präzise, auch keine Fehler durch überschrittene Zeitlimits.

Behandeln Sie HTTP-Fehler, bevor Sie eine Erfolgs-Payload auslesen. Unabhängig davon kann eine abgerufene Aufgabe den Status failed haben: Prüfen Sie ihre Felder errorCode und error und beenden Sie dann das Polling. Fehlgeschlagene Lösungsversuche werden erstattet, aber unveränderte ungültige Eingaben werden durch Wiederholung nicht korrigiert. Nutzen Sie die API-Fehlerreferenz, um den gemeldeten Fehler zu diagnostizieren.