Un Deferrable Airflow Operator pour CaptchaAI

Un deferrable operator règle le problème le plus coûteux d'un DAG qui doit franchir un CAPTCHA : l'attente. Pour obtenir un token, un operator classique garde un slot de worker occupé 30 à 120 secondes sans rien faire. La version deferrable libère ce slot, délègue l'attente au triggerer d'Airflow 2, et ne réveille la tâche qu'une fois le token prêt — vos workers restent disponibles pour le reste du pipeline.

Périmètre sûr : ce guide couvre vos propres applications, vos environnements de QA, de préproduction ou de production, et les sources pour lesquelles vous disposez d'une autorisation écrite — pas l'automatisation de sites tiers.

Pourquoi le motif deferrable change la donne

Le pattern deferrable d'Airflow 2 repose sur un trigger asynchrone exécuté dans le triggerer. Votre operator soumet la tâche à CaptchaAI, appelle self.defer(), puis rend la main : le triggerer prend en charge le polling sans mobiliser de worker. C'est exactement le profil d'une résolution CAPTCHA : une soumission rapide suivie d'une attente.

Ce découplage ne change rien à votre solde : CaptchaAI facture au thread, résolutions illimitées par thread, et le plan BASIC ($15/mois, 5 threads) autorise cinq résolutions simultanées. Libérer le worker Airflow ne libère pas le thread CaptchaAI, occupé le temps de la résolution — dimensionnez donc votre parallélisme sur le nombre de threads. L'API est unique pour reCAPTCHA v2, reCAPTCHA v3 et Cloudflare Turnstile : vous changez le type de tâche sans réécrire la boucle.

Séquence de résolution côté triggerer

1. Soumettez la tâche avec les seuls paramètres utiles (sitekey, URL de la page, action, proxy optionnel), récupérez son identifiant et journalisez toute réponse d'erreur.
2. Interrogez le résultat depuis le trigger : une quinzaine de secondes d'attente, puis toutes les 5 secondes avec un plafond strict par tâche.
3. Injectez le token dans la même session que celle qui a déclenché le défi (même navigateur, même client HTTP, même cookie jar). Une session dépareillée est la première cause de rejet. Mesurez ensuite latence, retries et acceptation en aval : la résolution et le workflow sont deux métriques distinctes.

Exemple : créer la tâche Turnstile

L'appel ci-dessous soumet une tâche Turnstile depuis votre propre service et renvoie l'identifiant à interroger :

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;
}

Secrets et périmètre RGPD

La clé CaptchaAI vit dans un coffre — HashiCorp Vault, AWS Secrets Manager, Azure Key Vault — ou dans un secret de votre CI, jamais dans le code du DAG. Le déploiement la monte en variable d'environnement au runtime, sans modification de code lors d'une rotation.

Si votre pipeline collecte des données, appliquez la minimisation du RGPD : ne journalisez pas le contenu des pages franchies, seulement les métadonnées techniques. Pour un worker hébergé chez OVHcloud, Scaleway ou en région eu-west-3 (Paris), gardez les journaux dans la zone du traitement.

Observabilité : les signaux à instrumenter

Instrumentez chaque appel CAPTCHA : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de file. Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (OpenTelemetry) — vous rejouez ainsi un scénario complet à partir d'un identifiant unique.

Liste de contrôle avant la mise en production

• Périmètre limité à vos applications ou à des sources autorisées ; clé CaptchaAI dans un coffre ou un secret CI.
• Le polling s'exécute dans le triggerer, pas dans un worker bloquant.
• Durées d'appel et codes retour tracés à chaque exécution.
• Retry idempotent avec backoff exponentiel borné, rejouable depuis votre CI.

FAQ

Pourquoi préférer un deferrable operator à un sensor classique ?

Un sensor en mode poke occupe un slot à chaque vérification, et le mode reschedule replanifie toute la tâche. Un deferrable operator confie l'attente au triggerer via self.defer() : le slot est rendu immédiatement, puis repris quand le token est prêt. Sur un pool qui résout beaucoup de CAPTCHA, le gain de capacité est net.

Quels codes d'erreur faut-il surveiller ?

Surveillez les erreurs de clé (espace parasite ou mauvais compte), le solde insuffisant, et les paramètres invalides (URL ou sitekey erronés). Journalisez chaque échec avec son identifiant de tâche : la plupart des tickets se résolvent en comparant les valeurs envoyées au HTML réel de la page.

Cette intégration est-elle compatible avec mes obligations RGPD ?

Oui, tant que vous restez dans le périmètre décrit ici. Limitez la collecte aux données nécessaires et ne journalisez pas le contenu sensible des pages. CaptchaAI n'a besoin que des paramètres du défi, pas de vos données métier.

Guides connexes

• Démarrage rapide CaptchaAI
• QA CAPTCHA en environnements autorisés
• Tester l'endpoint API sur vos formulaires
• Intégration CAPTCHA en CI
• Résoudre reCAPTCHA v2 via l'API

Fiabilisez vos workflows CAPTCHA avec une méthode reproductible. – Obtenez votre clé CaptchaAI.