Die CAPTCHA-API aus Spring Boot aufrufen

Die mitgelieferte Hilfsklasse verwendet Java 21+, Spring Web 7.0.10 und Gson 2.15.0. Behalten Sie in einem bestehenden Spring-Boot-Projekt die von Boot verwaltete kompatible Spring-Version bei, statt nur spring-web zu überschreiben, um dem Beispiel zu entsprechen. Fügen Sie Gson als Abhängigkeit hinzu, falls Ihre Anwendung es noch nicht enthält.

// Java 21+, Spring Web 7.0.10 and Gson 2.15.0; use your Boot dependency management.
// Save as CaptchaClient.java in your application's package.
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import java.net.http.HttpClient;
import java.time.Duration;
import org.springframework.http.MediaType;
import org.springframework.http.client.JdkClientHttpRequestFactory;
import org.springframework.web.client.RestClient;

public final class CaptchaClient {
    private final RestClient api;
    public CaptchaClient(String key) {
        var transport = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10))
            .followRedirects(HttpClient.Redirect.NEVER).build();
        var factory = new JdkClientHttpRequestFactory(transport);
        factory.setReadTimeout(Duration.ofSeconds(25));
        api = RestClient.builder().baseUrl("https://api.solvethree.com/v1")
            .requestFactory(factory).defaultHeader("Authorization", "Bearer " + key).build();
    }
    public JsonObject create(String site, String proxy, String requestId) {
        var input = new JsonObject();
        input.addProperty("site", site);
        input.addProperty("action", "login");
        input.addProperty("proxy", proxy);
        input.addProperty("requestId", requestId); // Save before calling create.
        String body = api.post().uri("/tasks?waitMs=0").contentType(MediaType.APPLICATION_JSON)
            .body(input.toString()).retrieve().body(String.class);
        return JsonParser.parseString(body).getAsJsonObject();
    }
    public JsonObject get(String id) {
        if (!id.matches("[A-Za-z0-9_-]+")) throw new IllegalArgumentException("Invalid task ID");
        String body = api.get().uri("/tasks/{id}?waitMs=15000", id)
            .retrieve().body(String.class);
        return JsonParser.parseString(body).getAsJsonObject();
    }
}
// Construct once with System.getenv("SOLVETHREE_API_KEY") in a server-side @Bean.
// Call create once, save its id, then get(id) until ready/failed or your deadline.
// RestClient throws on HTTP errors; keep the saved requestId and any known task id.

Speichern Sie die Klasse als CaptchaClient.java im Package Ihrer Anwendung. Erstellen Sie in einer serverseitigen @Bean-Factory-Methode einmalig eine Instanz mit der Umgebungsvariablen SOLVETHREE_API_KEY. Prüfen Sie beim Start, ob der Schlüssel konfiguriert ist. Die Hilfsklasse fügt ihn als Bearer-Authorization-Header hinzu; halten Sie ihn aus dem Browsercode heraus.

Verwenden Sie diese Bean per Konstruktorinjektion wieder. RestClient kann threadübergreifend wiederverwendet werden, aber jede Anfrage blockiert den aufrufenden Thread. Rufen Sie diese Methoden nicht in einer WebFlux-Ereignisschleife auf. Die REST-Client-Dokumentation von Spring beschreibt den synchronen Client.

Die Transportschicht verwendet ein Verbindungs-Timeout von 10 Sekunden, ein Lese-Timeout von 25 Sekunden und keine Weiterleitungen. Antworten werden als Strings gelesen und mit Gson geparst, nicht auf typisierte Antwortobjekte abgebildet.

Konfigurieren Sie vor dem Aufruf von create ein aktives Profil für die Zielwebsite in Ihrem Workspace. Das Senden eines Hostnamens und einer Aktion erstellt dieses Profil nicht. Lesen Sie die Anleitung zur Einrichtung eines Websiteprofils, falls die Website noch nicht konfiguriert ist.

• Übergeben Sie den Hostnamen als site, nicht als vollständige Seiten-URL. Eine reCAPTCHA-Anfrage hat kein Feld url oder type.
• Die Hilfsklasse setzt action fest auf login. Ändern Sie diesen Wert oder machen Sie ihn zu einem Methodenparameter, wenn die vorgesehene Anfrage eine andere Aktion verwendet.
• Übergeben Sie eine Proxy-URL. Die API verlangt genau eines der Felder proxy oder proxyCandidates; diese Hilfsklasse implementiert die Variante mit einem einzelnen Proxy.
• Die Hilfsklasse lässt recaptchaType weg, sodass die API ihren Standardwert enterprise-v3 verwendet.

1. 1.

   Anfrage-ID vor der Erstellung speichern

   Wählen Sie eine requestId aus 1–64 ASCII-Buchstaben, Ziffern, Unterstrichen oder Bindestrichen. Speichern Sie sie vor dem Aufruf von create zusammen mit den Task-Eingaben. Damit können Sie denselben Task wiederfinden, falls die Antwort auf die Erstellung verloren geht.

2. 2.

   create aufrufen und die zurückgegebene id speichern

   Rufen Sie die Methode create der Bean mit dem Hostnamen, dem Proxy und der gespeicherten Anfrage-ID auf. Sie sendet eine POST-Anfrage an /v1/tasks mit waitMs=0. Speichern Sie die zurückgegebene id; verwenden Sie für spätere Abfragen diese Task-ID, nicht die Anfrage-ID.

3. 3.

   get aufrufen, bis der Task einen Endstatus erreicht

   Übergeben Sie die gespeicherte Task-ID an get. Jede Abfrage fordert waitMs=15000 an und blockiert, während sie auf die Antwort wartet. Fragen Sie bei pending oder solving weiter ab, solange die auf Anwendungsebene festgelegte Zeitgrenze nicht erreicht ist. Beenden Sie die Abfragen bei ready oder failed. Die HTTP-Timeouts begrenzen einzelne Anfragen, nicht die gesamte Polling-Schleife.

4. 4.

   Lösung erst bei Bereitschaft auslesen

   Übermitteln Sie bei reCAPTCHA solution.token an das vorgesehene Ziel – nicht die Task-ID. Verwenden Sie die zurückgegebenen Werte userAgent und secChUa mit demselben erfolgreichen Proxy. Ersetzen Sie sie nicht durch andere Browser-Header und ändern Sie die Ziel-URL nicht. Ein bereiter Task liefert eine Lösung; er bestätigt nicht, dass das Ziel Ihre nachfolgende Anfrage akzeptiert hat.

Beim create-Aufruf tritt ein Timeout auf, bevor Sie eine Task-ID erhalten.

Der Server hat den Task möglicherweise erstellt, obwohl Ihr Client die Antwort nicht erhalten hat.

Probiere Folgendes: Wiederholen Sie zur Wiederherstellung dieselbe Task-Anfrage mit der gespeicherten requestId. Bei übereinstimmenden Eingaben wird der vorhandene Task zurückgegeben. Erzeugen Sie nur dann eine neue Anfrage-ID, wenn Sie einen neuen logischen Task erstellen möchten.

Ein get-Aufruf schlägt auf HTTP-Ebene fehl.

RestClient.retrieve() löst bei nicht erfolgreichen HTTP-Antworten eine Ausnahme aus. Das entspricht nicht dem Task-Status failed.

Probiere Folgendes: Behandeln Sie den HTTP-Fehler, bevor Sie versuchen, eine Erfolgsantwort auszulesen. Behalten Sie die bekannte Task-ID zur Wiederherstellung bei, statt einen weiteren Task zu erstellen. Ermitteln Sie die Ursache ungültiger Eingaben, bevor Sie diese unverändert erneut senden.

Die Task-Antwort hat den Status failed.

Lesen Sie die Felder errorCode und error aus; site-unreachable ist ein möglicher Task-Fehlercode.

Probiere Folgendes: Beenden Sie die Abfragen für diesen Task und beheben Sie die gemeldete Ursache, bevor Sie einen weiteren starten. Fehlgeschlagene Lösungsversuche werden erstattet; gehen Sie nicht davon aus, dass der Fehler auf unzureichendes Guthaben hinweist.

Die Wiederverwendung einer Anfrage-ID verursacht einen Konflikt.

Vergleichen Sie die neuen Task-Eingaben mit den für diese Anfrage-ID gespeicherten Eingaben.

Probiere Folgendes: Verwenden Sie die ursprünglichen Eingaben, um den vorhandenen Task wiederzufinden. Verwenden Sie eine neue Anfrage-ID für absichtlich abweichende Task-Eingaben.

Hinweise zur Interpretation von Fehlern finden Sie unter CAPTCHA-API-Fehler.