Résoudre les CAPTCHA dans AWS Step Functions Express

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 décrit ni l'automatisation de sites tiers, ni la neutralisation de protections anti-bot.

Pour résoudre un CAPTCHA à l'intérieur d'un workflow AWS Step Functions Express, appelez l'API CaptchaAI depuis une tâche Lambda, récupérez le token, puis transmettez-le à l'état suivant de votre machine à états. Le vrai défi n'est pas de le faire fonctionner une fois, mais de le rendre stable pour tourner sans surveillance à travers vos déploiements et vos coupures réseau.

Pourquoi Step Functions Express impose une architecture solide

Les workflows Express visent un fort volume et une courte durée : une exécution ne peut pas dépasser cinq minutes, et la sémantique est « au moins une fois ». Votre étape de résolution CAPTCHA peut donc être rejouée : elle doit être idempotente et ne jamais dépendre d'un état local entre deux invocations.

Le scénario type : un job planifié ou un worker interne, hébergé par exemple en région eu-west-3 (Paris), doit franchir une étape protégée par un CAPTCHA dans votre propre application. La première exécution passe vite ; le tout est que cela tienne ensuite, malgré les déploiements et un changement occasionnel de famille de CAPTCHA sur la page.

Architecture cible : l'appel CaptchaAI dans la machine à états

Le flux tient en trois états successifs de la machine à états :

1. Résoudre — un état Task invoque une Lambda qui appelle CaptchaAI en HTTPS et récupère le token.
2. Injecter — l'état suivant applique ce token dans la même session que celle qui a déclenché le défi ; une session dissociée est la première cause de rejet après résolution.
3. Vérifier — un dernier état confirme l'acceptation en aval avant de clôturer l'exécution.

Tracez chaque transition (identifiant d'exécution, durée d'obtention du token, code retour HTTP) pour détecter les régressions dès la montée de version, avant que le taux de réussite ne s'effondre.

Gérer la clé API CaptchaAI et les secrets

La clé CaptchaAI vit dans un coffre (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault) ou dans un secret d'intégration continue, jamais dans le code source. La Lambda la charge en variable d'environnement au démarrage, et votre rôle IAM restreint l'accès au seul secret concerné. Côté conformité, minimisez les données personnelles dans les logs et vérifiez vos obligations RGPD.

Créer une tâche Turnstile depuis une Lambda

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

Le même contrat se transpose à toute autre famille prise en charge : reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, image/OCR et grilles. Vous changez le type de tâche, la boucle reste identique.

Observabilité : métriques CAPTCHA par environnement

Instrumentez les appels CAPTCHA pour obtenir des signaux exploitables : durée d'obtention du token, code retour HTTP et identifiant de tâche. Mesurez la latence médiane (p50) et la latence de queue (p95) : la première dit si l'intégration est saine, la seconde si vos délais d'expiration sont bien dimensionnés.

Séparez les journaux par environnement et corrélez chaque identifiant à votre traçage distribué (par exemple OpenTelemetry). Surveillez enfin l'écart entre « solve réussi » et « workflow accepté » : l'alerte utile porte sur leur différence.

Liste de contrôle avant la mise en production

Dépannage

Les erreurs ci-dessous couvrent l'essentiel des tickets sur ce type d'intégration ; chaque ligne se corrige sans quitter l'éditeur.

FAQ

Faut-il un workflow Standard ou Express pour ces appels ?

Express convient dans la plupart des cas : une résolution de token tient largement dans la limite de cinq minutes. Passez à un workflow Standard seulement si votre orchestration englobe des étapes longues autour du CAPTCHA ou si vous avez besoin de l'historique d'exécution détaillé.

Combien de threads CaptchaAI prévoir pour une exécution parallèle ?

Comptez un thread par CAPTCHA résolu simultanément. Si vos workflows Express lancent au plus dix résolutions en même temps, le plan STANDARD ($30/mois, 15 threads) laisse de la marge. Seul le pic de simultanéité compte, pas le volume mensuel.

Comment gérer les erreurs transitoires dans la machine à états ?

Utilisez les champs natifs Retry et Catch de Step Functions plutôt que de coder la logique dans la Lambda : fixez un nombre maximal de tentatives, un intervalle initial et un facteur de backoff, puis routez les échecs terminaux vers un état de repli qui journalise l'identifiant de tâche.

CaptchaAI prend-il en charge hCaptcha dans ce workflow ?

Non — hCaptcha n'est pas encore pris en charge, pas plus que FunCaptcha (Arkose Labs). CaptchaAI couvre reCAPTCHA v2/v3, Cloudflare Turnstile et Challenge, GeeTest v3 et les CAPTCHA image et en grille ; CaptchaFox, Friendly Captcha et Lemin sont en bêta.

Guides connexes

• Le démarrage rapide CaptchaAI
• La QA CAPTCHA en environnements autorisés
• Tester l'endpoint API sur vos formulaires
• Intégrer la résolution CAPTCHA en CI
• Résoudre reCAPTCHA v2 via l'API

Passez d'un prototype fragile à une intégration reproductible et mesurée. – Obtenez votre clé CaptchaAI.