Transloadit

Assembly Instructions

Pour découvrir les Assembly Instructions, examinons cet exemple :

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "imported_watermark": {
      "robot": "/http/import",
      "url": "https://transloadit.com/assets/images/face.jpg"
    },
    "resized": {
      "robot": "/image/resize",
      "use": {
        "steps": [
          { "name": ":original", "as": "base" },
          { "name": "imported_watermark", "as": "watermark" }
        ]
      },
      "width": 400,
      "height": 400,
      "watermark_position": "center",
      "watermark_size": "30%"
    },
    "exported": {
      "robot": "/s3/store",
      "use": [":original", "resized"],
      "credentials": "my_cloud_storage_credentials",
      "path": "/my_images/${file.id}/${file.url_name}"
    }
  }
}

L’exemple présente quatre Steps : :original, imported_watermark, resized et exported. Vous pouvez donner à vos Steps le nom de votre choix, à l’exception de :original, qui désigne les fichiers téléversés et doit utiliser le Robot 🤖/upload/handle  (English).

Remarquez que les Steps :original et imported_watermark servent tous deux d’entrées au Step resized via le paramètre use. Nous utilisons ici le regroupement de Steps via la syntaxe « as » pour transmettre plusieurs fichiers au Step resized en même temps : la clé « as » attribue à l’un le rôle d’image de base et à l’autre celui de filigrane à apposer sur l’image de base. Les différents Robots offrent des possibilités différentes pour la syntaxe « as », ce qui la rend très puissante !

Le Step exported utilise ensuite simplement la plupart des autres Steps comme entrées et stocke les fichiers sur S3, un par un, sans regroupement de Steps. Les variables utilisées, ${file.id} et ${file.url_name}, sont accessibles à tous les Steps et peuvent servir à créer un nom de fichier unique pour chaque fichier.

Ainsi, nous pourrons traiter les fichiers téléversés, leur ajouter un filigrane et exporter sur S3 à la fois l’image téléversée et sa version redimensionnée avec filigrane.

Les Steps n’ont pas tous besoin d’entrées. Notre Step imported_watermark, par exemple, fournit le premier fichier d’entrée en le téléchargeant ; c’est donc là que nous omettrons use. Parmi les autres Robots qui ne nécessitent pas de fichiers d’entrée, citons 🤖/html/convert  (English), qui peut faire une capture d’écran d’un site web et créer ainsi le premier fichier, ou 🤖/upload/handle  (English), qui reçoit les fichiers des visiteurs de votre application plutôt que d’un autre Step.

Un simple changement nous permettrait de rendre cette application véritablement dynamique. Imaginez que vous remplaciez l’URL statique du Step imported_watermark par une URL dynamique provenant d’un champ de votre application. Il nous suffit de remplacer la valeur du paramètre "url" par "${fields.watermark_url}" dans notre Template, puis de fournir l’URL du filigrane via un champ de notre formulaire web HTML (ou via un champ POST supplémentaire dans notre requête) pour rendre l’ajout de filigranes véritablement dynamique !

Paramètres des Steps

Comme vous pouvez le voir, chaque Step est défini comme un objet doté de quelques propriétés, ou paramètres. Il s’agit en fait, pour la plupart, de paramètres de Robot, car ils définissent, par exemple, la propriété width d’une image après redimensionnement. Ils sont tous décrits dans la documentation des Robots  (English) correspondante. Il existe toutefois aussi 5 paramètres qui pilotent le moteur de l’Assembly lui-même, en définissant quels Robots sont appelés et comment ils sont interconnectés :

  • use

    string | Array<string> | Array<object> | object

    Indique quel(s) Step(s) utiliser comme entrée.

    • Vous pouvez choisir n’importe quel nom pour les Steps, sauf ":original" (réservé aux téléversements des utilisateurs gérés par Transloadit)
    • Vous pouvez fournir plusieurs Steps en entrée à l’aide de tableaux : 
      {
  "use": [
    ":original",
    "encoded",
    "resized"
  ]
}
    • Vous pouvez également étiqueter les Steps d’entrée avec as pour transmettre une intention sémantique aux Robots : 
      {
  "use": [
    {
      "name": ":original",
      "as": "image"
    },
    {
      "name": ":original",
      "as": "mask"
    }
  ]
}

  • robot — obligatoire

    string

    Indique quel Robot doit traiter les fichiers transmis à ce Step.

    Consultez tous les Robots  (English), chacun avec ses propres paramètres, comme width pour contrôler la façon dont une image est redimensionnée. La liste complète des paramètres de chaque Robot figure dans la documentation des Robots.

  • result

    boolean(par défaut : false)

    Indique si les résultats de ce Step doivent figurer dans l’Assembly Status JSON

  • force_accept

    boolean(par défaut : false)

    Forcer un Robot à accepter un type de fichier qu’il aurait ignoré.

    Par défaut, les Robots ignorent les fichiers qu’ils ne connaissent pas. Le Robot 🤖/video/encode  (English), par exemple, ignorera volontiers les images en entrée.

    Avec le paramètre force_accept défini sur true, vous pouvez forcer les Robots à accepter tous les fichiers qui leur sont envoyés. Cela entraîne généralement des erreurs et ne doit être utilisé que pour le débogage ou pour traiter des cas limites.

  • ignore_errors

    boolean | Array<meta | execute>(par défaut : [])

    Ignore les erreurs pendant certaines phases du traitement.

    Si vous définissez cette valeur sur ["meta"], le Robot ignorera les erreurs lors de l’extraction des métadonnées.

    Si vous définissez cette valeur sur ["execute"], le Robot ignorera les erreurs lors de la phase d’exécution principale.

    Définir cette valeur sur true équivaut à ["meta", "execute"] : les erreurs seront alors ignorées dans les deux phases.

Pour des conseils pratiques et des combinaisons de valeurs (y compris le comportement propre aux importations), consultez Le paramètre ignore_errors.

Ordre d’exécution

Afin d’accélérer les Assemblies, les Steps seront exécutés dès que les Steps qui leur servent d’entrées produiront des fichiers. Autrement dit, de nombreuses opérations sont traitées en parallèle. Par exemple, supposons que vous souhaitiez encoder une vidéo téléversée et aussi en extraire des miniatures :

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "encoded": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "web/mp4/1080p"
    },
    "thumbed": {
      "use": ":original",
      "robot": "/video/thumbs",
      "count": 4
    },
    "exported": {
      "use": ["encoded", "thumbed"],
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS"
    }
  }
}

Les Steps encoded et thumbed seront exécutés en parallèle dès que le téléversement du premier fichier sera terminé. Le Step exported est déclenché pour chacun des fichiers provenant de encoded et thumbed. Il est probable que les miniatures arrivent dans votre bucket S3 avant la vidéo encodée, même si les miniatures ont été définies plus tard. L’ordre des Steps n’a donc pas vraiment d’importance. Le paramètre use définit l’entrée de chaque Step et détermine ainsi l’enchaînement de nos Steps.

Filtrage pour rendre les Steps conditionnels

Grâce au Robot 🤖/file/filter  (English), vous pouvez exécuter des Steps en fonction des propriétés d’un fichier. Cela vous permet de créer des Assembly Instructions qui prennent en charge les téléversements vidéo comme audio, rejettent les fichiers trop petits, n’appliquent un effet qu’aux images présentant des zones transparentes, etc. Ces possibilités et bien d’autres sont aussi décrites dans la documentation du Robot.

Assembly Variables

Pour plus d’informations sur les Assembly Variables comme ${file.id}, ${assembly.id}, ${fields.*}, entre autres, consultez la page Assembly Variables qui leur est consacrée.