Périmètre sûr : ce guide s'applique exclusivement à vos propres applications, à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne porte ni sur l'automatisation de sites tiers, ni sur l'évasion de dispositifs anti-bot.
Dans un workflow Google Cloud, un CAPTCHA se traite comme n'importe quel appel réseau externe : votre composant envoie les paramètres du défi à un service de résolution, récupère un token, puis l'injecte dans la session qui a déclenché ce défi. Le vrai enjeu n'est pas de réussir une fois dans un notebook, mais de tenir sans surveillance dans un job planifié, une intégration continue ou une file d'attente interne. Ce guide montre comment câbler cette intégration avec l'API CaptchaAI pour qu'elle reste stable en production.
Où le CAPTCHA s'insère dans un workflow Google Cloud
Le principe est le même quel que soit l'ordonnanceur : un composant interne appelle CaptchaAI en HTTPS, obtient un token, puis le transmet à votre formulaire ou à votre route d'API. Que ce worker tourne dans un job Google Cloud, sur Cloud Run ou sur un hôte européen comme OVHcloud ou Scaleway, le contrat reste identique. Une seule API couvre les familles que vous rencontrez — reCAPTCHA v2 et v3, Cloudflare Turnstile, GeeTest v3, image et OCR — ce qui évite de maintenir un connecteur par type.
Le flux d'intégration, étape par étape
L'ordre ci-dessous absorbe les fenêtres de déploiement, les à-coups réseau et un changement de famille de CAPTCHA, sans intervention manuelle.
- Capturez exactement ce que le solveur attend. Inspectez la page ou l'appel réseau réel et n'extrayez que les paramètres requis (sitekey, URL de la page, action, proxy éventuel). Stocker plus crée de fausses pistes de diagnostic.
- Soumettez la tâche, puis traitez tout statut différent de « succès » comme une erreur : journalisez la réponse complète et remontez-la vers votre canal de supervision.
- Interrogez le résultat régulièrement : attendez 15 secondes avant la première requête, puis toutes les 5 secondes, avec un plafond strict de 120 secondes par tâche.
- Appliquez le token dans la même session que celle qui a déclenché le défi (même contexte de navigateur, même client HTTP, mêmes cookies). Une session incohérente est la première cause de rejet après résolution.
- Mesurez la latence, les retries et l'acceptation en aval. La réussite du solveur et celle du workflow sont deux métriques distinctes ; suivez les deux.
Gérer la clé API et les secrets
La clé CaptchaAI vit dans un coffre (Google Secret Manager, HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret de votre intégration continue, jamais dans le code source. Le déploiement la monte en variable d'environnement au runtime, et une rotation planifiée limite l'exposition en cas de fuite.
Exemple : appeler CaptchaAI depuis votre service
Exemple d'appel HTTP côté serveur, dans votre propre service :
import fetch from 'node-fetch';
const API_KEY = process.env.CAPTCHAAI_KEY;
export async function createTurnstileTask(siteKey, pageUrl) {
const res = await fetch('https://api.captchaai.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientKey: API_KEY,
task: {
type: 'TurnstileTaskProxyless',
websiteURL: pageUrl,
websiteKey: siteKey,
},
}),
});
const data = await res.json();
return data.taskId;
}
Observabilité et journalisation
Quel que soit le langage, instrumentez les appels CAPTCHA pour obtenir des métriques exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente. Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (OpenTelemetry, par exemple) : vous rejouez alors un scénario complet à partir d'un identifiant unique. Côté RGPD, minimisez les données personnelles écrites dans les logs — un identifiant de tâche et un horodatage suffisent à corréler, sans copier de contenu utilisateur.
Checklist avant la mise en production
Avant de fusionner l'intégration, vérifiez cinq points, chacun lié à une panne courante : les paramètres envoyés correspondent au HTML réel ; la clé API est stockée en secret, jamais en clair ; les durées d'appel et les codes retour sont tracés à chaque exécution ; une stratégie de retry idempotent (trois tentatives, backoff exponentiel borné) couvre les erreurs transitoires ; les tests sont rejouables depuis votre intégration continue. Rappel : une tâche résolue n'égale pas un workflow réussi.
Mesurer la réussite
Câblez quatre indicateurs dans le tableau de bord que vous utilisez déjà : la latence de première résolution (médiane et p95), le taux de réussite du solveur par famille de CAPTCHA, l'acceptation de bout en bout après application du token, et le coût par résolution acceptée. Le signal le plus utile reste l'écart entre la réussite du solveur et l'acceptation en aval : quand il se creuse, cherchez d'abord un problème de session ou de paramètres.
Dépannage : codes d'erreur courants
Les erreurs ci-dessous couvrent l'essentiel des tickets de support ; chaque ligne donne un correctif direct.
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la en secret CI. |
ERROR_KEY_DOES_NOT_EXIST |
Mauvaise clé de projet ou clé déjà tournée. | Confirmez la clé active dans le tableau de bord et faites tourner le secret. |
ERROR_ZERO_BALANCE |
Solde du compte sous le minimum par tâche. | Rechargez avant de réessayer et ajoutez une alerte de solde. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Paramètre requis manquant ou malformé. | Revalidez l'URL, le sitekey et les champs spécifiques face au HTML réel. |
CAPCHA_NOT_READY en boucle |
Interrogation trop précoce ou trop rapprochée. | Respectez l'attente initiale de 15 s puis la cadence de 5 s. |
| Token rejeté après résolution | Token appliqué dans une session différente de celle du défi. | Gardez résolution et envoi du formulaire dans la même session. |
FAQ
Comment stocker la clé API CaptchaAI dans un pipeline Google Cloud ?
Placez-la dans Google Secret Manager ou dans un secret de votre intégration continue, puis montez-la en variable d'environnement au runtime. Ne la committez jamais dans le dépôt et prévoyez une rotation régulière.
Combien de threads faut-il pour un workflow planifié ?
Cela dépend des résolutions simultanées, pas du volume total : CaptchaAI facture par thread, avec des résolutions illimitées par thread. Un job séquentiel tient souvent avec le plan BASIC ($15/mois, 5 threads) ; montez de palier seulement si plusieurs tâches tournent en parallèle.
Que se passe-t-il si la famille de CAPTCHA change sur la page ?
Vous changez le type de tâche (ou la méthode) et gardez la même boucle d'envoi et d'interrogation. Une seule API couvre reCAPTCHA v2 et v3, Cloudflare Turnstile, GeeTest v3 et l'image/OCR : l'intégration ne se réécrit pas à chaque changement de protection.
Faut-il vraiment appliquer le token dans la même session ?
Oui, c'est la règle qui évite la majorité des rejets. Le token est lié au contexte qui a déclenché le défi : conservez le même client HTTP, les mêmes cookies et le même contexte de navigateur entre la résolution et l'envoi du formulaire.
Guides connexes
- Le guide de démarrage rapide CaptchaAI
- Tester vos CAPTCHA en environnement autorisé
- Tester votre endpoint API sur vos formulaires
- Intégrer la résolution de CAPTCHA en intégration continue
- Résoudre reCAPTCHA v2 via l'API
Améliorez vos workflows CAPTCHA avec une approche méthodique. – Obtenez votre clé CaptchaAI.
