Transloadit

Qu’est-ce qu’une Assembly ?

Une Assembly Transloadit est une exécution des Assembly Instructions sur des fichiers téléversés, importés ou générés par le flux de travail lui-même. Chaque exécution possède un assembly_id unique qui l’identifie dans les requêtes API ultérieures.

Fonctionnement des Assemblies

Une Assembly est le processus de traitement créé à l’exécution lorsqu’une requête associe des Assembly Instructions à des sources d’entrée : fichiers téléversés, fichiers récupérés par des Steps d’importation ou fichiers qu’un Robot crée lui-même, comme une capture d’écran de site web ou une image générée à partir d’une consigne textuelle. Les Instructions sont fournies directement sous la forme steps ou par référence à un Template enregistré via template_id ; le Template stocke la configuration, tandis que l’Assembly en est une exécution particulière. Les Steps démarrent dès que les Steps dont ils dépendent produisent des fichiers, ce qui permet à un même fichier source d’alimenter plusieurs branches exécutées en parallèle. Transloadit rend compte de l’exécution dans un document Assembly Status unique, renvoyé lors de la création de l’Assembly, accessible à son URL de statut et envoyé à notify_url si cette valeur est définie. Ce document évolue pendant le téléversement ou l’exécution de l’Assembly ; une fois l’exécution dans un état terminal, il contient soit ok avec l’état final, soit error avec un code d’erreur.

Points clés

  1. Une réponse HTTP de réussite à la requête de création signifie que l’Assembly a été acceptée, pas que le traitement a réussi. L’Assembly est toujours en cours tant que ok vaut ASSEMBLY_UPLOADING, ASSEMBLY_EXECUTING ou ASSEMBLY_REPLAYING ; seule la valeur ASSEMBLY_COMPLETED indique une réussite. Les valeurs ASSEMBLY_CANCELED et REQUEST_ABORTED apparaissent également sous ok sans indiquer une réussite, et une requête de statut peut renvoyer HTTP 200 alors que le corps contient error. Faites donc dépendre la suite du traitement du corps de la réponse, et non du statut HTTP.
  2. La valeur assembly_id fait office de droit d’accès : toute personne qui la connaît peut demander l’Assembly Status, y compris les champs soumis et les résultats, sans authentification supplémentaire. Veillez à ce que l’identifiant et les URL de statut ne figurent ni sur des pages publiques ni dans des éléments partagés avec des tiers non fiables. L’option quiet ne fait que raccourcir la réponse de création ; elle ne restreint pas les personnes qui peuvent ensuite consulter le statut.
  3. La création d’une Assembly n’est pas idempotente. Réessayer la requête de création, par exemple après un dépassement du délai d’attente, peut démarrer une seconde Assembly avec sa propre valeur assembly_id, et l’ajout d’un nonce de signature ne l’empêche pas. Dédupliquez les nouvelles tentatives dans votre application.
  4. Les fichiers de résultat sont regroupés sous le nom du Step qui les a produits, et non dans l’ordre des téléversements. Un téléversement peut produire plusieurs résultats ; associez-les aux téléversements à l’aide de original_id. Les Steps qui se limitent au stockage des fichiers n’ajoutent aucune entrée, et les résultats peuvent être partiels après une erreur. Les URL des résultats sur le stockage temporaire de Transloadit expirent ; ajoutez donc un Step d’exportation lorsque les fichiers doivent être conservés.

Quand les Assemblies comptent

Stockez la valeur assembly_id sur votre serveur lorsqu’un processus de traitement doit interroger périodiquement le statut, recueillir les résultats ou associer une notification entrante à la requête qui a déclenché ce processus de traitement. Traitez cette valeur comme un secret, car l’identifiant seul suffit pour consulter l’Assembly Status. Décidez avant le lancement comment votre application prendra connaissance du résultat, en interrogeant périodiquement l’URL de statut ou en définissant notify_url, car la réponse à la requête de création confirme uniquement que l’Assembly a été acceptée.

Références

Transformer vos connaissances sur les médias en une chaîne de traitement opérationnelle

Reliez les téléversements, le traitement, l’IA, le stockage et la diffusion via une seule API déclarative — la pile d’encodage, la montée en charge et l’évolution constante des formats sont prises en charge pour vous.

Essayer Transloadit gratuitement