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 sources pour lesquelles vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni l'évasion de protections anti-bot.
Un job Spark Structured Streaming qui rencontre un CAPTCHA sur un portail autorisé n'a que deux issues : s'arrêter en attendant une intervention humaine, ou déléguer la résolution à un service comme CaptchaAI, récupérer un token et poursuivre le micro-batch. Seule la seconde voie tient dans un pipeline planifié qui tourne sans surveillance. Ce guide montre comment intégrer cet appel proprement, pour qu'il tienne en production, pas seulement dans un notebook de démonstration.
Architecture cible : où placer l'appel CaptchaAI
Un job de streaming traite ses données par micro-lots ; y coder en dur un appel réseau sans borne de temps expose tout le pipeline au premier délai venu. Le schéma qui tient sépare trois responsabilités :
- Détection — le job Spark repère l'étape protégée par un CAPTCHA.
- Résolution — un composant dédié (UDF ou service compagnon) contacte CaptchaAI en HTTPS, attend le token avec un plafond de temps, puis renvoie soit le token, soit une erreur explicite.
- Injection — le token est appliqué dans le formulaire ou la route d'API cible, dans la même session que celle qui a déclenché le défi.
Chaque étape est tracée (identifiant de tâche, durée, code retour), ce qui facilite la détection de régressions lors des montées de version de Spark comme du portail visé.
Le flux d'intégration, étape par étape
Le même contrat vaut pour tout langage capable de faire du HTTP :
- Capturez les paramètres exacts attendus par la famille de CAPTCHA — sitekey, URL de page, éventuel proxy — sans en stocker davantage.
- Soumettez la tâche à l'API et récupérez le
taskIdretourné. - Interrogez le résultat après un premier délai d'attente, puis à intervalle court, avec un plafond de temps dur par tâche.
- Injectez le token dans la même session que celle qui a déclenché le défi — même contexte, mêmes cookies.
- Tracez la latence et les tentatives : la réussite de la résolution et celle du workflow sont deux métriques distinctes.
Traitez tout statut inattendu comme une erreur : journalisez la réponse et remontez-la à votre supervision.
Gérer la clé API et les secrets
- La clé CaptchaAI ne vit jamais dans le code source : stockez-la dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou un secret CI.
- Le déploiement la monte en variable d'environnement au runtime ; le worker Spark la lit depuis là.
- Faites tourner la clé régulièrement et branchez une alerte de solde sur votre tableau de bord, pour ne jamais découvrir un compte à zéro en pleine nuit.
Exemple de code côté service
Voici un appel HTTP côté serveur, dans votre propre service compagnon, qui crée une tâche Turnstile et renvoie son identifiant :
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;
}
Le taskId renvoyé sert ensuite à interroger le résultat. La même logique vaut pour reCAPTCHA v2, reCAPTCHA v3 ou GeeTest v3 : seul le type de tâche change, la boucle d'obtention du token reste identique.
Observabilité et journalisation
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 interne. Ces signaux alimentent vos tableaux de bord de QA et distinguent la réussite de la résolution de la réussite du workflow — deux métriques à suivre séparément. Séparez les journaux par environnement (développement, préproduction, production) et corrélez les identifiants à votre traçage distribué, par exemple via OpenTelemetry. Vous pourrez ainsi rejouer un scénario complet à partir d'un identifiant unique et localiser l'incident plus vite.
Déployer les workers en Europe : latence et RGPD
Le contexte de déploiement compte autant que le code. Si vos données et vos utilisateurs sont en Europe, hébergez vos workers Spark au plus près — une région comme eu-west-3 (Paris), ou une instance chez OVHcloud ou Scaleway — pour réduire la latence aller-retour. L'appel à CaptchaAI reste une requête HTTPS sortante ; la facturation se fait en dollars US, quelle que soit votre région. Côté conformité, appliquez la minimisation du RGPD : ne journalisez que les paramètres nécessaires à la résolution (sitekey, URL de page) et purgez les identifiants de tâche selon votre politique de rétention. Un CAPTCHA reste une étape technique et ne dispense pas de la base juridique du traitement en aval.
Dépannage
| 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_ZERO_BALANCE |
Solde du compte sous le minimum par tâche. | Rechargez avant de relancer et ajoutez une alerte de solde. |
| Token refusé après résolution | Token appliqué dans une session différente de celle du défi. | Gardez la résolution et l'envoi du formulaire dans la même session. |
Liste de contrôle avant la mise en production
- Le périmètre est strictement limité à vos propres applications ou à des sources autorisées par écrit.
- La clé CaptchaAI est stockée dans un coffre ou un secret CI, jamais dans le code source.
- L'appel de résolution est isolé dans un composant dédié, borné en temps et testable.
- Les durées d'appel, les codes retour et les identifiants de tâche sont tracés pour chaque exécution.
- Une stratégie de retry idempotent avec backoff exponentiel borné couvre les erreurs transitoires.
- La latence, le taux de réussite et la consommation apparaissent sur un tableau de bord par environnement.
FAQ
Comment résoudre un CAPTCHA sans figer le micro-batch Spark ?
Bornez l'appel dans le temps et isolez-le. Un premier délai d'attente, puis un polling court avec un plafond dur par tâche : au-delà, renvoyez une erreur que le job traite comme un échec transitoire, au lieu d'attendre indéfiniment. Le micro-batch reste prévisible.
Quel plan CaptchaAI choisir pour un pipeline planifié ?
La facturation se fait par thread simultané, avec des résolutions illimitées par thread. Un job à faible concurrence démarre très bien en BASIC ($15/mois, 5 threads) ; passez à STANDARD ($30/mois, 15 threads) ou ADVANCE ($90/mois, 50 threads) quand votre parallélisme réel dépasse les threads disponibles.
Que faire quand le token est refusé après résolution ?
La cause la plus fréquente est une session incohérente : le token a été appliqué dans un contexte différent de celui qui a déclenché le défi. Injectez-le toujours dans la même session HTTP ou le même contexte navigateur d'origine, avant son expiration. Si le refus persiste, revalidez le sitekey et l'URL de page face au HTML réellement servi.
Guides connexes
- le démarrage rapide de CaptchaAI
- tester le CAPTCHA en environnements autorisés
- tester l'endpoint API sur vos formulaires
- intégrer la résolution de CAPTCHA en CI
- résoudre reCAPTCHA v2 via l'API
Fiabilisez vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
