Templates

Un Template est une recette qui définit comment traiter les fichiers entrants.

Vous pouvez nous envoyer vos Assembly Instructions directement avec chaque requête, ou les enregistrer dans un Template et faire référence à son template_id dans vos requêtes.

Builtin Templates

Transloadit fournit également des Templates dont nous assurons la maintenance et la gestion des versions. Ces Builtin Templates constituent des points de départ stables et prêts à l’emploi pour les transformations courantes.

Consultez les Builtin Templates pour découvrir ceux qui sont disponibles et savoir comment les lister via l’API.

L’envoi direct d’Instructions permet un prototypage rapide, mais leur enregistrement dans un Template présente plusieurs avantages :

1. Vous pouvez éviter de transmettre des données sensibles et des détails d’implémentation avec chaque requête d’encodage. C’est particulièrement intéressant pour les intégrations dans les navigateurs.
2. Associées à "allow_steps_override": false, les Instructions ne peuvent pas être altérées.
3. En associant les Templates enregistrés aux Assembly Notifications, vous pouvez activer les Assembly Replays.
4. Si vous avez intégré Transloadit dans une application, vous pouvez modifier les paramètres d’encodage sans effectuer de déploiement ni attendre qu’un App Store publie une nouvelle version.

Comment créer un Template

1. Créez un Template dans votre compte.
2. Donnez un nom lisible par une personne à votre Template pour pouvoir le retrouver facilement par la suite.
3. Fournissez les Assembly Instructions au format JSON pour votre Template. Vous pouvez sélectionner des exemples dans une liste, laisser notre assistant générer des Instructions, dupliquer un Template existant ou partir de zéro.
4. Cliquez sur Enregistrer.

Une fois le Template enregistré, une page affiche le Template que vous avez créé. Son identifiant est indiqué en haut de la page, par exemple 4b62ee4dbb38455d96fe13d972ec3211. Vous pouvez ensuite copier-coller cet identifiant dans template_id de votre code d’intégration, ou consulter plus bas le Template Editor, où nous présentons déjà des exemples contenant cet identifiant.

Surcharge des Templates à l’exécution

Vous pourriez penser que ces éléments s’excluent mutuellement, mais il est possible de fournir à la fois template_id et steps dans params, ce qui vous permet de modifier le comportement d’un Template à l’exécution. En fait, toute autre propriété de params, à l’exception de allow_steps_override, sera fusionnée récursivement avec le Template chargé via template_id, en remplaçant les valeurs correspondantes.

Par exemple, examinons le Template suivant, qui gère un téléversement, encode une vidéo pour une bonne lecture sur iPad et enregistre le résultat sur S3 :

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "encoded": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "ipad-high"
    },
    "exported": {
      "use": "encoded",
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS",
      "bucket": "main-bucket"
    }
  }
}

Lorsque vous créez une Assembly, nous pouvons ajuster le comportement du Template à l’exécution, par exemple en ajoutant une propriété steps :

{
  "template_id": "4b62ee4dbb38455d96fe13d972ec3211",
  "steps": {
    "exported": {
      "bucket": "another-bucket"
    }
  }
}

Transloadit fusionne ensuite ces éléments pour créer les Assembly Instructions suivantes :

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "encoded": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "ipad-high"
    },
    "exported": {
      "use": "encoded",
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS",
      "bucket": "another-bucket"
    }
  }
}

Comme vous pouvez le constater, la valeur de bucket est passée de "main-bucket" à "another-bucket". Ce mécanisme peut être pratique et puissant dans des environnements de confiance.

Dans d’autres environnements, vous souhaiterez peut-être interdire la surcharge des Steps afin qu’un navigateur ne puisse pas modifier le comportement. Pour cela, définissez allow_steps_override sur false dans le Template enregistré, comme suit :

{
  "allow_steps_override": false,
  "steps": {
    // …
  },
}

Désormais, seul main-bucket sera utilisé, que des steps supplémentaires aient été fournis ou non.

Options des Templates

Outre steps et allow_steps_override, d’autres options permettent de contrôler le comportement d’une Assembly.

Comme la plupart peuvent aussi être définies sans utiliser de Templates, elles sont décrites dans la documentation de l’API pour créer une nouvelle Assembly. Cependant, si vous intégrez Transloadit dans des environnements non fiables tels que les navigateurs, une personne malveillante pourrait facilement les modifier. Pour permettre la modification dynamique des paramètres d’un Template dans des environnements non fiables, envisagez donc d’utiliser Signature Authentication.