Ressources · 107
Tâches API asynchrones : suivre l’état, reprendre et annuler
Ne pas confondre requête acceptée, traitement démarré et résultat final d’une opération longue.
· 4 min
Ce que ce guide permet
- Établir les états
- Protéger le suivi
- Encadrer les consultations
- Tester l’annulation concurrente
- Gérer les traitements abandonnés
- Contractualiser la répétition et l’expiration
Contrôle express
- 202 signifie-t-il que la tâche est terminée ?
- L’annulation efface-t-elle tous les effets ?
- Faut-il continuer les consultations indéfiniment ?
Méthode pas à pas
- 01
Établir les états
Décrivez reçu, en attente, actif, terminé, échoué et annulation demandée. Une réponse 202 ne prouve pas la réussite ; définissez comment le client retrouvera l’issue finale.
Livrable : transitions et résultat faisant foi.
- 02
Protéger le suivi
Associez chaque identifiant au compte et à la portée de la demande. Vérifiez droits sur statut, résultat et annulation ; un identifiant difficile à deviner ne remplace pas l’autorisation.
Livrable : tests entre comptes.
- 03
Encadrer les consultations
Fixez fréquence et durée de consultation, état terminal et expiration des résultats. Préservez une référence permettant de reprendre après fermeture du navigateur sans relancer le traitement.
Livrable : politique de suivi et reprise.
- 04
Tester l’annulation concurrente
Simulez annulation pendant attente, exécution et publication du résultat. Définissez ce qui peut encore être interrompu et quels effets restent ; confirmez une issue réellement observée.
Livrable : courses et effets persistants.
- 05
Gérer les traitements abandonnés
Repérez tâches sans progression, erreurs répétées et résultats expirés. Attribuez reprise, clôture ou revue ; ne présentez pas une progression estimée comme une preuve de complétion.
Livrable : suivi des tâches orphelines.
- 06
Contractualiser la répétition et l’expiration
Décidez si une nouvelle soumission peut retrouver la tâche existante. Si une clé de répétition est utilisée, définissez son compte, sa durée, les paramètres associés et le comportement en cas de conflit. Testez une acceptation dont la réponse est perdue. Précisez séparément expiration du suivi et suppression du résultat : l’absence de résultat consultable ne prouve pas que le traitement n’a jamais eu lieu.
Livrable : contrat de répétition, d’expiration et de suivi après incident.
Choisir la suite selon l’état confirmé
Vérifiez l’état observé avant de choisir la suite.
En attente ou actif
Reprenez le suivi avec la même référence.
Annulation demandée
Vérifiez issue et effets déjà produits.
État terminal
Vérifiez résultat, droits et délai de conservation.
Préparer la reprise sans inventer un succès
Cas fictifs à adapter au contrat de votre service. Les résultats attendus sont des critères à tester, pas des résultats de clients.
| Situation | Action à préparer | Preuve attendue |
|---|---|---|
| La réponse d’acceptation est perdue | Retrouver la tâche via le mécanisme de répétition documenté ou vérifier la demande avant une nouvelle création. | Identifiant conservé, portée du contrat et nombre de tâches créées dans l’essai. |
| Le client cesse de consulter après son délai maximal | Conserver un état de suivi interrompu et une voie de reprise ; ne pas annoncer un échec métier sans preuve. | État serveur distinct du délai client et reprise de la même référence. |
| Une annulation arrive pendant la publication du résultat | Confirmer l’issue observée et rapprocher les effets ; une demande d’arrêt n’est pas un effacement. | Chronologie, état final et liste proportionnée des effets restants. |
| Le résultat expire alors que la personne revient | Expliquer l’expiration et appliquer la règle de récupération ou de nouvelle demande avec les droits nécessaires. | Délai documenté, accès refusés hors périmètre et aucune relance silencieuse. |
Fiche de travail à réutiliser
À compléter avec vos observations autorisées. Ces champs constituent une trame de travail, pas des résultats observés.
| Champ | Information à consigner |
|---|---|
| Référence | Compte, opération et identifiant |
| État | Transition, heure et source |
| Issue | Résultat, erreur ou effets restants |
| Acceptation | Même tâche retrouvée, droits vérifiés et issue ou incertitude explicitée |
Exemple d’application
Situation illustrative
Cas illustratif : un export est accepté puis le navigateur se ferme. Une nouvelle connexion retrouve la tâche en cours.
Décision et preuve attendue
Réutilisez l’identifiant, vérifiez le droit d’accès au résultat et proposez une annulation avec son état confirmé.
Distinguer les mécanismes
| Mécanisme | Utilité | Point de vigilance |
|---|---|---|
| Accepté | Demande reçue pour traitement | Ce n’est pas une réussite finale |
| Annulation demandée | Intention de stopper | Confirmer l’issue réelle |
| Terminé | Résultat disponible | Vérifier droits et conservation |
Indicateurs de pilotage
| Indicateur | Ce qu’il mesure | Première action |
|---|---|---|
| Tâches orphelines | Tâches sans progression qualifiée | Attribuer reprise ou clôture |
| Reprise | Cas repris sans duplication | Corriger les relances inutiles |
Erreurs fréquentes
- Présenter une acceptation comme un succès final
- Autoriser le résultat par le seul identifiant de tâche
- Consulter sans fréquence ni durée bornées
Questions fréquentes
202 signifie-t-il que la tâche est terminée ?
Non. Le traitement n’est pas nécessairement achevé. Le client doit pouvoir consulter une issue faisant foi.
L’annulation efface-t-elle tous les effets ?
Pas toujours. Certains effets peuvent déjà être produits ; précisez lesquels et comment les rapprocher.
Faut-il continuer les consultations indéfiniment ?
Non. Définissez une fréquence et une durée adaptées, exploitez l’indication de délai prévue par le service et arrêtez au résultat terminal. Un délai écoulé côté client ne transforme pas une tâche active en échec serveur.
Références officielles
Date de consultation des références : . La méthode et la fiche de travail proposent des contrôles à adapter à votre contexte ; elles ne constituent pas une certification.
Pour aller plus loin
Analyses associées
