Paramètre avancé use

Regroupement des Steps

Certains Robots peuvent rassembler les résultats de plusieurs Steps lors d’un seul appel. Par exemple, le Robot 🤖/file/compress EN (English) créerait normalement une archive pour chaque fichier qui lui est transmis. Cependant, si vous définissez bundle_steps sur true, il créera une archive contenant tous les fichiers de résultat de chaque Step que vous lui transmettez.

Pour activer le regroupement, fournissez un objet comme celui ci-dessous au paramètre use :

"use": {
  "steps": [
    ":original",
    "encoded",
    "resized"
  ],
  "bundle_steps": true
}

Regrouper par fichier d’origine

Le paramètre group_by_original organise les fichiers de sortie selon leur fichier d’entrée d’origine. Il est donc indispensable dans les flux de travail où vous souhaitez vous assurer que les sorties sont regroupées avec le fichier d’entrée qui les a produites, par exemple avec le Robot 🤖/file/compress EN (English). Dans ce cas, vous pouvez choisir de créer une archive distincte pour chaque fichier téléversé ou importé, plutôt qu’une archive contenant tous les fichiers téléversés d’origine (ou une archive par fichier de sortie).

Exemple :

"compress": {
  "use": {
    "steps": ["thumbnails"],
    "bundle_steps": true,
    "group_by_original": true
  },
  "robot": "/file/compress"
}

Cette configuration indique que le Step compress doit prendre en compte les sorties du Step thumbnails, les regrouper par fichier d’origine, puis les compresser en conséquence.

Champs

Vous pouvez filtrer et sélectionner des fichiers spécifiques selon le nom de leur champ à l’aide du paramètre fields. Lorsque ce tableau est spécifié, le Step correspondant ne sera exécuté que pour les fichiers soumis par l’intermédiaire d’un des champs dont le nom est indiqué.

Les noms des champs doivent correspondre à ceux des champs de type fichier de votre formulaire HTML, tels qu’ils sont définis dans l’attribut name de la balise du champ. Avec un SDK côté serveur, le nom du champ correspond à myFieldName1, par exemple dans $transloadit->addFile('myFieldName1', './chameleon.jpg').

Exemple :

"use": {
  "steps": [":original"],
  "fields": ["myFieldName1"]
}

Ce paramètre est défini sur true par défaut, ce qui signifie que tous les champs sont acceptés.

Utiliser as

Les Robots acceptent parfois plusieurs entrées. Par exemple, 🤖/video/merge EN (English) peut créer un diaporama à partir de contenu audio et d’images. Vous pouvez associer différents Steps aux entrées appropriées en indiquant à quel type de fichier assimiler chaque Step.

"use": {
  "steps": [
    { "name": "audio_encoded", "as": "audio" },
    { "name": "images_resized", "as": "image" }
  ]
}

Ordre des Steps

L’ordre est parfois important. Par exemple, avec notre famille de Robots de concaténation, il peut être utile de préciser l’ordre exact dans lequel concaténer vos médias. Dans ces cas, vous pouvez ajouter un indice à la fin du type de fichier, en commençant à 1. Vous pouvez également, de manière facultative, filtrer par le nom du champ multipart. C’est le cas dans cet exemple, où tous les fichiers proviennent de la même source (téléversements des utilisateurs finaux), mais avec des noms <input> différents :

"use": {
  "steps": [
    { "name": ":original", "fields": "myFirstVideo", "as": "video_1" },
    { "name": ":original", "fields": "mySecondVideo", "as": "video_2" },
    { "name": ":original", "fields": "myThirdVideo", "as": "video_3" }
  ]
}

Lorsque l’emplacement à attribuer au fichier n’est pas évident, vous pouvez utiliser des Assembly Variables pour le préciser. Par exemple, vous pourriez transmettre un fichier texte au Robot 🤖/image/resize EN (English) pour incruster le texte dans une image. Mais qu’en est-il si vous incrustez plusieurs filigranes dans l’image ? Comment indiquer le fichier texte que vous souhaitez utiliser ? Vous pouvez le spécifier via ${use.text_1} pour indiquer le premier fichier texte transmis.

Exemple :

"watermarked": {
  "robot": "/image/resize",
  "use": {
    "steps": [
      { "name": "resized", "as": "base" },
      { "name": "transcribed", "as": "text" }
    ]
  },
  "text": [
    {
      "text": "Hi there",
      "valign": "top",
      "align": "left"
    },
    {
      "text": "From the 'transcribed' Step: ${use.text_1}",
      "valign": "bottom",
      "align": "right",
      "x_offset": 16,
      "y_offset": -10
    }
  ]
}

Fournir le filigrane via un Assembly Step

Vous pouvez également transmettre le fichier image de base et l’image du filigrane à un Assembly Step via le paramètre use. Vous pouvez ainsi inclure les deux dans le téléversement ou utiliser les résultats d’autres Assembly Steps comme entrées de votre Step utilisant le Robot 🤖/image/resize EN (English).

Pour cela, il vous suffit d’utiliser la syntaxe as :

"my_image_step": {
  "robot": "/image/resize",
  "use": {
    "steps": [
      { "name": ":original", "as": "base" },
      { "name": "watermark_step", "as": "watermark" }
    ]
  }
}

Ici, la sortie d’un Step watermark_step sert de filigrane, tandis que l’image de base provient des fichiers téléversés.

Si vous utilisez plusieurs champs de type fichier, vous pouvez indiquer à Transloadit quel champ fournit l’image de base et lequel fournit le filigrane. Supposons que vous disposiez de deux champs de type fichier nommés the_image et the_watermark. Ces Assembly Instructions permettront de le faire fonctionner grâce à la condition fields :

"my_image_step": {
  "robot": "/image/resize",
  "use": {
    "steps": [
      { "name": ":original", "fields": "the_image", "as": "base" },
      { "name": ":original", "fields": "the_watermark", "as": "watermark" }
    ]
  }
}

Veuillez noter que le paramètre watermark_url du Robot continuera de fonctionner.