Qu’est-ce qu’un Template ?
Un Template stocke de manière sécurisée des Assembly Instructions Transloadit dans un Workspace et est référencé dans les requêtes API au moyen d’un template_id. Il permet aux clients d’invoquer un flux de traitement prédéfini sans envoyer l’intégralité de ses Instructions.
Fonctionnement des Templates
Un Template Transloadit est une définition de flux de travail gérée au sein d’un Workspace, dont le JSON décrit les Assembly Steps nommés, leurs paramètres et la façon dont les sorties des premiers Steps sont transmises aux suivants. Référencer une définition enregistrée évite d’envoyer les Instructions complètes dans chaque requête de création, mais ne rend pas le flux de travail confidentiel : l’Assembly Status peut exposer template et merged_params. Les propriétés fournies dans params au moment de la requête, à l’exception de allow_steps_override lui-même, sont fusionnées récursivement avec le Template chargé en prenant le pas sur ses valeurs, dans les limites de sa politique de surcharge des Steps. Cette fusion permet aussi des variations à l’exécution. Les Templates se situent entre les requêtes de l’application et l’exécution des Assemblies, de sorte que la gestion de leurs modifications fait partie du contrat d’intégration.
Points clés
- 1Les noms des Steps servent de références dans les Assembly Instructions. Renommer un Step peut donc rompre les relations
useen aval, même lorsque chaque opération reste syntaxiquement valide. - 2Un
template_idsélectionne des instructions enregistrées, mais n’authentifie pas à lui seul une requête API ; l’authentification du compte et les éventuelles exigences de signature des requêtes restent des contrôles distincts. - 3Définissez
allow_steps_overridesurfalsedans le Template enregistré pour rejeter les requêtes qui fournissent aussi des Steps. Les autres paramètres de requête peuvent toujours remplacer les valeurs enregistrées. Exigez Signature Authentication pour les requêtes utilisant une Auth Key et faites en sorte qu’un serveur de confiance ne signe que les paramètres approuvés ; les jetons porteurs valides contournent cette exigence et restent soumis à leurs restrictions de portée et d’audience. Les signatures couvrentparamsaprès sérialisation, et non les champs distincts du formulaire de téléversement. Ces champs non signés alimentent${fields.*}et remplacent les valeurs signées defieldsqui portent le même nom ; ces contrôles ne suffisent donc pas à sécuriser les entrées dynamiques. Ne dérivez pas de ces champs des réglages que les appelants ne doivent pas pouvoir choisir. - 4Les Templates créés dans un Workspace ne permettent pas de fixer une version. Pour apporter une modification incompatible avec les versions précédentes en toute sécurité, créez un nouveau Template avec son propre
template_idet migrez les appelants vers celui-ci. Seuls les Builtin Templates de Transloadit sont versionnés par Transloadit.
Quand les Templates sont importants
Utilisez un Template pour centraliser les modifications du flux de travail et éviter d’envoyer les Assembly Instructions complètes dans chaque requête de création. Définissez allow_steps_override sur false pour empêcher les surcharges des Steps, et exigez Signature Authentication avec une génération de signatures par un système de confiance pour les requêtes utilisant une Auth Key. Ces contrôles ne limitent pas les champs de téléversement non signés et ne remplacent pas les restrictions de portée des jetons porteurs ; examinez donc séparément les entrées dynamiques. La mise à jour d’un Template partagé peut affecter tous les appelants ; les modifications incompatibles peuvent donc nécessiter un nouveau Template.