Skip to main content
Questo documento presenterà una guida all’integrazione dell’API di riconoscimento del protocollo Recaptcha2, che consente agli utenti di completare la verifica senza dover riconoscere e selezionare le immagini del codice captcha di Recaptcha2, ma semplicemente inviando la Website Key per attivare la decodifica automatica in background.

​
Processo di richiesta

Per utilizzare l’API di riconoscimento del protocollo Recaptcha2, prima di tutto vai al Pannello di controllo di Ace Data Cloud per ottenere il tuo API Token, da conservare per uso futuro. Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di accesso che ti invita a registrarti e accedere; una volta completato, verrai riportato automaticamente alla pagina corrente. Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, senza dover richiedere separatamente per ogni servizio. La prima richiesta include un credito gratuito, che consente di provare il servizio gratuitamente; se il credito è insufficiente, puoi ricaricare il saldo generale nel pannello di controllo.
📘 Documentazione completa: API di riconoscimento del protocollo Recaptcha2 →

​
Utilizzo di base

Iniziamo a comprendere il modo di utilizzo di base, che consiste nell’inserire l’URL del sito web che deve elaborare il captcha, per ottenere il risultato elaborato. Prima di tutto, è necessario trasmettere un campo website_url, il nostro sito di esempio è: https://www.google.com/recaptcha/api2/demo, dobbiamo ottenere il website_key dalla pagina website_url, per farlo, apri questa pagina, premi F12 per accedere alla console e infine cerca globalmente recaptcha-demo nella pagina Element, otterremo il seguente risultato:

Dove la stringa corrispondente a data-sitekey è il valore di website_key, di seguito sono riportati i risultati dei parametri specifici:

Possiamo vedere che qui abbiamo impostato le intestazioni della richiesta, tra cui:
  • accept: il formato della risposta desiderata, qui impostato su application/json, ovvero formato JSON.
  • authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dopo la richiesta.
Inoltre, abbiamo impostato il corpo della richiesta, che include:
  • website_url: l’URL del sito web che deve elaborare il captcha.
  • website_key: l’identificatore della chiave del sito in Recaptcha2.
  • proxy: opzionale, porta il tuo proxy (Bring Your Own Proxy). Una volta impostato, il servizio utilizzerà l’IP del proxy fornito per decifrare il captcha, utile per controllare la qualità dell’IP di uscita (ad esempio, per evitare che l’IP del proxy pubblico venga bloccato dal sito di destinazione e restituisca 410 Gone). Il formato è scheme://[user:pass@]host:port, dove scheme supporta http/https/socks4/socks5, ad esempio http://user:pass@1.2.3.4:8080. Se non specificato, verrà utilizzato il proxy predefinito della piattaforma.
Dopo aver effettuato la selezione, puoi notare che a destra è stato generato il codice corrispondente, come mostrato nell’immagine:

Cliccando sul pulsante “Try” puoi effettuare un test, come mostrato nell’immagine sopra, qui abbiamo ottenuto il seguente risultato:
I risultati restituiti contengono più campi, descritti come segue:
  • token, il risultato della verifica dopo l’elaborazione del compito Recaptcha2.
  • started_at, finished_at: il tempo di inizio e di fine della richiesta, timestamp Unix (secondi, float).
  • elapsed: il tempo totale impiegato per l’elaborazione (secondi).
Possiamo vedere che abbiamo ottenuto il risultato della verifica del Recaptcha2, che possiamo utilizzare per POST o simulare l’invio al sito web di destinazione, utilizzabile una sola volta, con una validità di 120 secondi, si consiglia di utilizzarlo entro 60 secondi. Di seguito verrà fornito un segmento di codice Python per inviare il token elaborato al sito web di destinazione per superare il Recaptcha2. Prima di tutto, dobbiamo capire come il sito invia la richiesta POST, in modo da poter inserire il token generato. Dobbiamo prima aprire la console F12 e poi completare manualmente la verifica. Alla fine, possiamo vedere che il sito ha inviato una richiesta POST; dobbiamo solo esaminare la costruzione di questa richiesta POST. Il processo specifico è il seguente:
  • Prima completare manualmente la verifica, come mostrato nell’immagine qui sotto:

  • Poi cliccare su submit e osservare le variazioni nella rete della console, come mostrato nell’immagine qui sotto:

  • Analizza la costruzione della richiesta POST inviata, alla fine puoi fare clic destro su questa richiesta per copiare il codice CURL, come mostrato nell’immagine sottostante:

Dall’analisi dell’immagine sopra, si può notare che l’URL della richiesta POST è: https://www.google.com/recaptcha/api2/demo, dobbiamo solo inviare il parametro g-recaptcha-response, quindi dobbiamo solo passare il token elaborato nei dati sottostanti, il codice CURL specifico per la verifica del token è il seguente:
Il codice Python corrispondente per la verifica del token è il seguente:
Poi eseguiamo il codice e osserviamo che la console mostra il seguente risultato:

Infine, abbiamo superato la verifica del protocollo Recaptcha2. Inoltre, se desideri generare il codice di integrazione corrispondente, puoi semplicemente copiare il codice generato, ad esempio il codice CURL è il seguente:
Il codice di integrazione Python è il seguente:

​
Modalità asincrona (async)

Per impostazione predefinita, l’API è bloccante e sincrona: una richiesta attenderà fino a quando il token non sarà elaborato prima di restituire. Se stai facendo una rotazione di più risolutori (multi-solver rotation) e desideri “ricevere immediatamente il task_id dopo aver inviato il compito, per poi programmare altri risolutori e tornare più tardi a leggere il risultato”, puoi passare async: true nel corpo della richiesta. Passando async: true, l’interfaccia restituirà immediatamente un task_id, senza bloccare l’attesa:
Se desideri controllare attivamente i progressi, puoi utilizzare il task_id per interrogare POST /captcha/tasks (si consiglia ogni 3~5 secondi). Questa interfaccia non attiverà o accelererà l’elaborazione del compito; anche se non interroghi, perdi la connessione o esci dal client, il server continuerà a elaborare:
Durante l’elaborazione verrà restituito status: processing:
Al termine dell’elaborazione verrà restituito status: ready e il token:
Informazioni di fatturazione: in modalità asincrona, la creazione di un compito e la lettura dello stato “in elaborazione” non comportano costi; il cliente verrà addebitato una volta al primo successo della lettura dei risultati (coerente con il comportamento attuale e il prezzo della modalità sincrona). Il server gestirà autonomamente l’avanzamento del compito, ma non addebiterà in anticipo se il backend completa prima. Se il compito non ha successo entro 120 secondi, verrà terminato con un HTTP 504 timeout, senza costi. /captcha/tasks non è responsabile dell’avanzamento del compito.

​
Gestione degli errori

Quando chiami l’API, se si verifica un errore, l’API restituirà il codice di errore e le informazioni corrispondenti. Ad esempio:
  • 400 token_mismatched: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
  • 400 api_not_implemented: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
  • 401 invalid_token: Non autorizzato, token di autorizzazione non valido o mancante.
  • 429 too_many_requests: Troppe richieste, hai superato il limite di frequenza.
  • 500 api_error: Errore interno del server, qualcosa è andato storto sul server.

​
Esempio di risposta di errore

​
Conclusione

Attraverso questo documento, hai appreso come utilizzare l’API di riconoscimento del protocollo Recaptcha2 per consentire agli utenti di non dover riconoscere e selezionare le immagini del captcha Recaptcha2, ma di completare la verifica semplicemente inviando la Website Key. Speriamo che questo documento ti aiuti a integrare e utilizzare meglio questa API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.