Flux de travail personnalisables pour le traitement multimédia avec Transloadit

Un flux de travail personnalisable doit exposer les quelques valeurs qui varient légitimement d’une tâche à l’autre tout en gardant son graphe de traitement sous contrôle. Les Assembly Instructions de Transloadit expriment ce graphe sous forme de Steps nommés, et un Template enregistré permet à une application de l’exécuter à plusieurs reprises sans renvoyer les informations d’identification pour le stockage ni la politique de transformation.

L’essentiel

• Référencez des ensembles d’informations d’identification de Template enregistrés au lieu de placer les secrets cloud dans les Assembly Instructions.
• Enregistrez l’identifiant du Template, le libellé du flux de travail de l’application, l’identifiant de l’Assembly, les entrées et le résultat final pour chaque exécution.

{
  "allow_steps_override": false,
  "auth": {
    "max_number_of_files": 1,
    "max_size": 52428800
  },
  "notify_url": "https://app.example.com/webhooks/transloadit",
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "accepted_images": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        ["${file.mime}", "regex", "^(image/jpeg|image/png|image/webp|image/avif)$"]
      ],
      "error_on_decline": true,
      "error_msg": "Upload a JPEG, PNG, WebP, or AVIF image."
    },
    "web_image": {
      "use": "accepted_images",
      "robot": "/image/resize",
      "width": 1600,
      "height": 1200,
      "resize_strategy": "fit",
      "format": "webp"
    },
    "thumbnail": {
      "use": "accepted_images",
      "robot": "/image/resize",
      "width": 320,
      "height": 320,
      "resize_strategy": "fillcrop",
      "format": "webp"
    },
    "export_web": {
      "use": "web_image",
      "robot": "/s3/store",
      "acl": "bucket-default",
      "credentials": "media-output",
      "path": "${fields.tenant_id}/${assembly.id}/web/${unique_prefix}/${file.url_name}"
    },
    "export_thumb": {
      "use": "thumbnail",
      "robot": "/s3/store",
      "acl": "bucket-default",
      "credentials": "media-output",
      "path": "${fields.tenant_id}/${assembly.id}/thumb/${unique_prefix}/${file.url_name}"
    }
  }
}

// Illustrative fragment: these objects come from your application, not the SDK.
const assembly = await transloadit.createAssembly({
  files: { image: inputPath },
  params: {
    template_id: process.env.TRANSLOADIT_TEMPLATE_ID,
    fields: {
      tenant_id: tenant.id,
    },
  },
})

await jobs.attachAssembly({
  jobId: job.id,
  assemblyId: assembly.assembly_id,
})

Détails techniques à connaître

• Un Step traitant les fichiers individuellement démarre dès qu’un Step en amont nommé dans sa valeur use émet un fichier ; seuls les Robots de fusion ou de regroupement attendent l’ensemble complet des entrées nommées. La position d’un Step dans l’objet JSON ne détermine pas l’ordre d’exécution.
• Les Assembly Variables telles que ${fields.tenant_id}, ${assembly.id} et ${file.url_name}, une version du nom du fichier courant du Step adaptée aux URL (sous forme de slug), extension comprise, sont résolues au moment de l’exécution et peuvent paramétrer les dimensions, les chemins et d’autres valeurs des Robots. Dans les exemples de chemins d’export, ${assembly.id} assure l’unicité de chaque exécution, tandis que ${unique_prefix}, qui contient des barres obliques, permet de distinguer les fichiers d’une même exécution.
• Définir allow_steps_override sur false dans un Template enregistré empêche les appelants de fusionner des Steps de remplacement dans ce Template. Les champs fournis à l’exécution nécessitent toujours une validation et une autorisation côté application.
• /file/filter peut comparer les propriétés des fichiers détectées par le serveur à des conditions définies dans un tableau. Une liste explicite de types MIME autorisés est plus sûre que le fait de se fier à une extension de fichier ou au type déclaré par le client.
• Les ensembles d’informations d’identification de Template conservent les secrets des destinations séparément du JSON du Template et peuvent être mis à jour sans recopier les clés dans chaque intégration.
• L’envoi des Assembly Notifications est retenté lorsque le destinataire ne renvoie pas de code de statut HTTP 2xx. Les systèmes consommateurs doivent vérifier la signature et tolérer les réceptions répétées, tardives ou dans le désordre.

Une approche pratique

Quand Transloadit est utile

Utilisez un Template enregistré pour relier /upload/handle, /file/filter, des Steps /image/resize parallèles et /s3/store. Verrouillez le graphe de traitement en définissant allow_steps_override sur false, transmettez des champs aux valeurs encadrées à l’exécution et rapprochez l’état de fin de traitement de celui de l’application à l’aide de l’Assembly Status et de webhooks vérifiés.

Périmètre architectural

Les Templates d’Assembly décrivent le traitement et le déplacement des fichiers. Ils ne gèrent ni les approbations produit, ni l’autorisation des tenants, ni l’état métier, ni l’historique de configuration d’une application ; conservez ces décisions dans le système qui lance et enregistre chaque tâche.