Traiter des lots de fichiers avec une concurrence maîtrisée

Pourquoi ne pas tout envoyer en même temps

Lorsque vous automatisez le traitement de nombreux fichiers, envoyer toutes les requêtes en même temps peut compliquer le suivi des tâches terminées, en cours ou en échec. Une rafale de requêtes ne permet pas non plus de savoir avec certitude ce qui s’est passé si le processus est interrompu. Concevoir une file avec une limite de tâches actives et un état par fichier peut aider à organiser le travail. Ce sont toutefois des choix propres à votre intégration, et non des comportements garantis par toutes les API.

Les API proposent différents modèles. L’[API Batch d’OpenAI](https://help.openai.com/es-es/articles/9197833-batch-api-faq) permet d’envoyer des requêtes pour un traitement asynchrone. Microsoft documente le regroupement de requêtes et d’opérations dans l’[API REST/OData de SharePoint Online](https://learn.microsoft.com/es-es/sharepoint/dev/sp-add-ins/make-batch-requests-with-the-rest-apis). Ces exemples ont des portées différentes et ne définissent pas de règle de concurrence commune aux autres services.

• Consultez la documentation du point de terminaison que vous utiliserez.
• Identifiez chaque tâche par fichier.
• Distinguez les fonctions documentées par l’API des choix propres à votre file.

Avant de commencer : lire le contrat de l’API

Vérifiez les entrées acceptées par le point de terminaison, les réponses renvoyées et si le résultat est fourni directement ou traité de manière asynchrone. Cherchez également si la documentation précise des limites, des identifiants permettant de consulter la progression ou les conditions de répétition d’une opération. Si un comportement n’est pas défini, ne le présumez pas : consultez le fournisseur ou concevez un test contrôlé.

Consignez ces conditions dans une fiche d’intégration et distinguez l’acceptation d’une requête de l’achèvement du travail. Apification permet d’intégrer Cloud et ses services via REST API, OpenAPI et webhooks ; cela ne signifie pas que tous les services partagent les mêmes limites, états ou politiques de nouvelle tentative. Consultez la documentation du service concerné.

• Consignez le point de terminaison, la méthode, le format d’entrée et la réponse attendue.
• Notez uniquement les limites et les règles de nouvelle tentative spécifiées.
• Déterminez quelle réponse confirme l’acceptation et laquelle confirme l’achèvement.

Concevoir une file avec un état par fichier

Vous pouvez représenter chaque fichier comme une tâche indépendante dans votre application. Enregistrez un identifiant interne, la référence du fichier et ses paramètres, ainsi que l’état local, le nombre de tentatives et le résultat ou l’erreur pertinente. Si l’API renvoie un identifiant distant et documente un moyen de consulter l’état, conserver cet identifiant peut faciliter le suivi.

Utilisez des états locaux aux significations claires, par exemple : en attente, en cours, terminé et à examiner. Ne les présentez pas comme des états du fournisseur, sauf si sa documentation les définit ainsi. Leur persistance aide votre application à repérer les tâches incomplètes après une interruption, mais ne permet pas à elle seule de savoir si une opération distante a été exécutée. Protégez les secrets et les identifiants dans vos journaux.

• Consignez le résultat de chaque tâche, et pas seulement le total du lot.
• Distinguez les états locaux de ceux renvoyés par l’API.
• Conservez le contexte nécessaire à l’analyse sans enregistrer de secrets.

Choisir et ajuster le niveau de concurrence

Sans connaître l’API et ses conditions, il n’est pas possible de recommander une valeur de départ universelle. Comme principe de conception, rendez configurable le nombre de tâches simultanées et commencez par un test à petite échelle. Observez les réponses et les restrictions communiquées par le fournisseur ; ajustez ensuite la limite en tenant compte de la documentation et des résultats des tests.

La taille totale du lot et le nombre de tâches simultanées sont deux notions différentes : un grand lot peut être traité par groupes plus petits. Si votre architecture utilise plusieurs consommateurs, réfléchissez à la coordination de la limite globale ; ne supposez pas que chaque consommateur peut utiliser séparément toute la capacité autorisée par l’API.

• Commencez avec peu d’éléments et une limite configurable.
• Ajustez cette limite en fonction de la documentation et des réponses observées.
• Tenez compte de l’activité combinée de tous les consommateurs.

Classer les erreurs et limiter les nouvelles tentatives

Classez les erreurs à partir des réponses et des règles de l’API concernée. Certaines peuvent nécessiter de corriger le fichier ou les paramètres ; d’autres peuvent justifier une nouvelle tentative si la documentation l’autorise. Ne déduisez pas une politique universelle du seul texte de l’erreur. Enregistrez le code et le contexte utile au diagnostic, sans exposer de données sensibles.

Comme choix de conception, vous pouvez fixer un nombre maximal de tentatives et un délai d’attente entre celles-ci pour les cas où une nouvelle tentative est autorisée. Si l’état d’une opération est incertain, l’expiration du délai d’attente ne prouve pas que le service ne l’a pas traitée : évitez de la renvoyer à l’aveugle. Si l’API documente un mécanisme d’idempotence, respectez ses conditions ; sinon, ne présumez pas qu’une répétition est sans risque.

• Pour chaque erreur, déterminez s’il faut réessayer, corriger ou examiner.
• Consignez chaque tentative et évitez les boucles de nouvelle tentative sans fin.
• Traitez avec prudence les requêtes dont le résultat est incertain.

Reprendre un lot interrompu

Au redémarrage de votre application, chargez l’état persistant et conservez les tâches terminées. Pour celles qui étaient en cours, vérifiez si l’API propose un moyen documenté de consulter leur état à partir d’un identifiant. Si l’incertitude ne peut pas être levée, définissez une politique explicite ou envoyez ces tâches en révision plutôt que de les remettre automatiquement en file.

Attribuez une identité stable à chaque tâche et traitez les modifications du fichier ou des paramètres comme des travaux distincts. Apification permet de consulter l’historique des éléments dans Cloud, de télécharger des versions antérieures et de restaurer du contenu. Ces fonctions facilitent l’examen des changements dans Cloud, mais ne remplacent pas le suivi des requêtes et ne garantissent pas l’idempotence d’une opération d’API.

• Ignorez les tâches terminées et examinez celles qui étaient en cours.
• Ne considérez pas une réponse perdue comme la preuve que l’opération a échoué.
• Consignez les changements d’entrée ou de paramètres afin de distinguer les travaux.

Déroulement opérationnel et tests

Un déroulement possible consiste à valider les fichiers, à créer une tâche persistante pour chacun, à traiter ces tâches dans la limite définie et à consigner chaque réponse. À la fin, présentez les résultats en séparant les tâches terminées, celles qui nécessitent une correction et celles dont l’état reste incertain. Ce sont des choix de conception pour votre intégration, et non des garanties concernant le fonctionnement d’une API externe.

Avant la mise en production, testez les interruptions et les réponses incertaines, par exemple une expiration du délai d’attente ou une panne entre l’envoi et l’enregistrement du résultat. Vérifiez que l’application conserve assez de contexte pour l’analyse et qu’elle ne renvoie pas automatiquement les tâches terminées ou de résultat inconnu. Adaptez ces tests aux capacités documentées du service. Apification propose un assistant guidé pour traiter des documents, des images, de la vidéo, de l’audio et des données, ainsi que des options d’intégration par API ; consultez la documentation du service pour confirmer les opérations disponibles via l’API.

• Validez les entrées et définissez ce que signifie l’achèvement de chaque tâche.
• Testez les interruptions et les états incertains en fonction des capacités documentées du fournisseur.
• À la fin du lot, identifiez les tâches en attente, les erreurs corrigeables et celles à examiner.

Questions fréquentes