Transloadit

Assembly Variables

Transloadit prend en charge les variables dans vos Assemblies pour vous permettre de créer des flux de travail plus puissants. Vous pouvez, par exemple, filtrer les fichiers selon width, adapter leur emplacement de stockage selon type, et bien plus encore. Nous avons inclus une liste complète des variables de substitution disponibles pour les Assembly Variables. Elles peuvent être utilisées dans la valeur de n’importe quel paramètre de n’importe quel Robot.

  • ${assembly.id} — L’identifiant de l’Assembly représentant le téléversement en cours, au format UUIDv4 sans tirets.

  • ${assembly.region} — La région AWS dans laquelle l’Assembly est traitée. Vous pourriez l’utiliser pour importer des fichiers depuis un bucket de la même région, afin de réduire les coûts de transfert de données et les latences.

  • ${assembly.parent_id} — L’identifiant de l’Assembly parente lors de la réexécution de cette Assembly parente.

  • ${unique_prefix} — Un préfixe unique de 33 caractères servant à éviter les collisions de noms de fichiers, comme "f2/d3eeeb67479f11f8b091b04f6181ad".

    Remarquez le / dans le préfixe. Si vous utilisez ${unique_prefix} dans le paramètre path du Robot 🤖/s3/store  (English), par exemple, cela créera des sous-répertoires dans votre bucket S3. Cela peut être souhaité ou non. Utilisez ${file.id} si vous avez besoin d’un préfixe unique sans barres obliques.

  • ${unique_original_prefix} — Cette valeur est semblable à ${unique_prefix}, sauf que deux résultats d’encodage différents du même fichier téléversé (le fichier d’origine) auront ici la même valeur de préfixe.

  • ${previous_step.name} — Le nom du Step précédent qui a produit le fichier actuel.

  • ${file.id} — L’identifiant du fichier en cours de traitement, au format UUIDv4 sans tirets.

  • ${file.original_id} — L’identifiant du fichier d’origine dont un fichier donné est issu. Par exemple, si vous utilisez un Robot d’importation pour importer des fichiers, puis les encodez d’une manière ou d’une autre, les fichiers résultant de l’encodage auront une valeur ${file.original_id} correspondant à la valeur ${file.id} du fichier importé.

  • ${file.original_name} — Le nom du fichier d’origine (extension comprise) dont un fichier donné est issu. Par exemple, si vous utilisez un Robot d’importation pour importer des fichiers, puis les encodez d’une manière ou d’une autre, les fichiers résultant de l’encodage auront une valeur ${file.original_name} correspondant à la valeur ${file.name} du fichier importé.

  • ${file.original_basename} — Le nom de base du fichier d’origine dont un fichier donné est issu. Par exemple, si vous utilisez un Robot d’importation pour importer des fichiers, puis les encodez d’une manière ou d’une autre, les fichiers résultant de l’encodage auront une valeur ${file.original_basename} correspondant à la valeur ${file.basename} du fichier importé.

  • ${file.original_path} — Le chemin d’importation du fichier d’origine dont un fichier donné est issu. Tous nos Robots d’importation définissent ${file.original_path} en conséquence.

    Par exemple, si vous utilisez le Robot 🤖/s3/import  (English) pour importer des fichiers depuis Amazon S3, les fichiers importés, ainsi que tous les fichiers qui en sont issus, auront une valeur file.original_path égale au chemin du fichier sur S3, mais sans le nom du fichier. Ainsi, si le chemin S3 était "path/to/file.txt", file.original_path vaudrait "/path/to/". Si le chemin était "/a.txt", ${file.original_path} vaudrait "/".

    file.original_path contiendra toujours suffisamment de barres obliques pour que vous puissiez l’utiliser sans risque dans le paramètre path de votre Step d’exportation, comme ceci : "path": "${file.original_path}${file.name}". C’est pratique si vous souhaitez importer des fichiers depuis S3, par exemple, les convertir d’une manière ou d’une autre, puis les stocker à nouveau sur S3 dans la même arborescence (ou une arborescence similaire).

  • ${file.name} — Le nom du fichier en cours de traitement, extension comprise.

  • ${file.url_name} — Le nom du fichier sous forme de slug.

    Les noms de fichiers sont translittérés et nettoyés pour produire une version compatible avec les URL. Les caractères non latins sont convertis en équivalents latins (par exemple, café.jpg → cafe.jpg, бубу.mov → bubu.mov), et les espaces ou la ponctuation sont remplacés par des tirets. Des caractères consécutifs non distincts peuvent être regroupés en un seul tiret.

  • ${file.basename} — Le nom du fichier en cours de traitement, sans son extension. Cela vous permet d’effectuer des opérations dynamiques par fichier plutôt que par Assembly avec fields.

  • ${file.url_basename} — Le nom de base du fichier sous forme de slug (le nom du fichier sans son extension).

    Les noms de fichiers sont translittérés et nettoyés pour produire une version compatible avec les URL. Les caractères non latins sont convertis en équivalents latins (par exemple, café.jpg → cafe.jpg, бубу.mov → bubu.mov), et les espaces ou la ponctuation sont remplacés par des tirets. Des caractères consécutifs non distincts peuvent être regroupés en un seul tiret.

  • ${file.user_meta.*} — Les métadonnées personnalisées par fichier fournies par les téléversements tus ou les instructions du Robot. Consultez la section Métadonnées personnalisées pour connaître les règles d’héritage et obtenir un exemple complet.

  • ${file.ext} — L’extension du fichier.

  • ${file.size} — La taille du fichier en octets.

  • ${file.type} — Une catégorie générale de fichier détectée par Transloadit et exposée dans le JSON d’état de l’Assembly, comme image, video, audio, pdf, office, xls, swf ou document. Utilisez cette valeur si vous avez besoin d’une catégorie générale ou d’une compatibilité avec les flux de travail existants. Pour des vérifications robustes du contenu, privilégiez ${file.mime}.

  • ${file.mime} — Le type MIME du fichier tel que détecté par Transloadit, généralement lors de l’extraction des métadonnées côté serveur dans le flux de téléversement normal. Il peut différer du type MIME initialement indiqué par le client ou le navigateur. Privilégiez cette valeur pour la logique conditionnelle selon le type de contenu, en utilisant si possible des correspondances par famille MIME comme image/*, video/* ou audio/*.

  • ${file.md5hash} — L’empreinte MD5 du fichier. Cette empreinte est calculée sur le contenu du fichier, et pas seulement sur son nom.

  • ${file.*} — Toute propriété de fichier disponible dans le tableau des résultats finaux, comme ${file.meta.width}. Toutes les clés de métadonnées ne sont pas disponibles pour tous les types de fichiers.

  • ${fields.*} — Les champs envoyés avec le téléversement.

    Par exemple, lors de l’envoi d’un formulaire où Uppy était configuré pour autoriser fields: ['myvar'] et où le formulaire contenait une balise comme <input type="hidden" name="myvar" value="1" />, ${fields.myvar} contiendrait la valeur 1.

    Les champs peuvent aussi être renseignés par programmation, comme ceci :

    {
  "steps": {
    "store": {
      "use": "encoded",
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS_NAME",
      "path": "${assembly.id}/${fields.subdir}/356"
    }
  },
  "fields": {
    "subdir": "bar"
  }
}

    En cas de conflit, les variables issues des champs du formulaire ont priorité sur celles issues de la clé fields.

    Les requêtes du Smart CDN renseignent ce même espace de noms à partir de l’URL plutôt qu’à partir des champs de formulaire envoyés lors du téléversement. Les paramètres de requête deviennent des valeurs ${fields.*}, et le chemin après le nom du Template devient la valeur implicite ${fields.input}, sans barre oblique initiale. Par exemple, https://my-app.tlcdn.com/image-template/images/canoe.jpg?w=640 fournit à ${fields.input} la valeur images/canoe.jpg et à ${fields.w} la valeur 640. Avec ${fields.input} comme valeur de path, le Robot 🤖/s3/import lit donc la clé d’objet images/canoe.jpg. Ce mode de renseignement à partir de l’URL est distinct des champs de formulaire envoyés lors du téléversement et de la clé fields de l’Assembly décrits ci-dessus.

  • ${browser.wanted_image_format} — Le format d’image privilégié par l’en-tête Accept du client à l’origine de la requête. Il correspond à celui des formats "avif", "webp" ou "jpg" dont la pondération de qualité (q) positive est la plus élevée, en privilégiant cet ordre en cas d’égalité. Les plages de types de médias avec caractères génériques telles que */* et image/* n’expriment pas de choix explicite du client en faveur d’AVIF ou de WebP pour cette variable. Un en-tête absent, vide ou ne contenant que des caractères génériques donne la valeur "jpg". JPEG est lui aussi un candidat à part entière : image/avif;q=0.2,image/jpeg;q=1 donne donc la valeur "jpg".

    La variable est également disponible pour les Assemblies ordinaires. Les requêtes des SDK et de l’API sans en-tête Accept significatif utilisent couramment la valeur de repli "jpg". Un nœud périphérique du Smart CDN peut à la place définir un en-tête x-tl-image-format de confiance, déjà normalisé, qui donne la même valeur "avif", "webp" ou "jpg" sans analyser à nouveau Accept.

    La valeur de repli "jpg" décrit la prise en charge côté client, et non le fichier d’entrée. Lorsque vous utilisez le Robot 🤖/image/resize  (English), associez cette valeur de repli à null pour conserver le format d’entrée pour les clients sans préférence explicite pour un format moderne. Cela préserve la transparence et l’animation au lieu de réencoder inutilement le fichier d’entrée en JPEG.

  • ${Date.now()} — La date et l’heure actuelles, représentées par le nombre de millisecondes écoulées depuis l’époque UNIX, définie comme minuit au début du 1er janvier 1970, UTC. Techniquement, il ne s’agit pas d’une variable : cette expression utilise l’évaluation dynamique de code.

Métadonnées personnalisées avec user_meta

Utilisez le paramètre facultatif user_meta pour associer des valeurs JSON à chaque fichier produit par un Step. Les Steps suivants les lisent via ${file.user_meta.key}. Ces valeurs peuvent inclure des objets et des tableaux imbriqués. Elles ne modifient pas le contenu du fichier et n’écrasent pas les propriétés de confiance telles que file.id ou file.meta.

Pour les Steps de traitement, les valeurs sont évaluées séparément pour chaque fichier produit, après l’exécution du Robot. Dans user_meta, ${file.*} désigne le premier fichier d’entrée et ${result.*} désigne le fichier produit. Par exemple, /file/hash peut stocker ${result.meta.hash}. Seules les propriétés de sortie déjà disponibles à ce stade peuvent être utilisées : cette évaluation a lieu avant l’extraction ultérieure des métadonnées et le stockage temporaire. ${result.*} n’est pas disponible dans les paramètres ordinaires des Robots.

Sur :original (/upload/handle), les valeurs sont évaluées séparément pour chaque téléversement avant l’extraction des métadonnées. Ne vous appuyez pas sur les empreintes ou les dimensions extraites à ce stade. Pour préserver l’empreinte du fichier téléversé, affectez ${file.md5hash} à une clé de métadonnées personnalisées dans le premier Step de traitement, comme illustré ci-dessous.

L’héritage dépend du Robot. /image/resize transmet les métadonnées du premier fichier d’entrée ; il ne combine pas les dictionnaires provenant de plusieurs entrées. Les Robots qui créent de nouveaux fichiers de sortie, comme /html/convert, peuvent ne pas hériter du dictionnaire. Affectez explicitement les clés requises à l’aide de ${file.user_meta.key} dans ces Steps. Les valeurs du Step actuel remplacent les clés de premier niveau correspondantes déjà présentes sur son fichier de sortie ; les objets imbriqués sont remplacés, et non fusionnés en profondeur.

Préserver l’empreinte de l’image téléversée

Configurez l’ensemble d’informations d’identification de Template pour S3 avec le nom indiqué et fournissez le champ de requête customer avant d’utiliser cet exemple. Le Step de redimensionnement enregistre l’empreinte de l’image d’entrée ; le Step d’exportation lit la valeur stockée plutôt que l’empreinte du fichier redimensionné.

{
  "steps": {
    ":original": {
      "robot": "/upload/handle",
      "user_meta": {
        "stage": "uploaded"
      }
    },
    "resized": {
      "use": ":original",
      "robot": "/image/resize",
      "width": 640,
      "height": 640,
      "resize_strategy": "fit",
      "result": true,
      "user_meta": {
        "source_md5": "${file.md5hash}",
        "stage": "resized",
        "source": {
          "name": "${file.name}"
        },
        "tags": [
          "profile",
          "${fields.customer}"
        ]
      }
    },
    "exported": {
      "use": "resized",
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS_NAME",
      "path": "${file.user_meta.source_md5}/${unique_prefix}/${file.url_name}"
    }
  }
}

Le résultat resized inclut user_meta avec source_md5, la valeur stage mise à jour, un objet source imbriqué et un tableau tags. ${unique_prefix} garantit l’unicité des chemins d’exportation, même pour des téléversements identiques. Les objets fichiers exposent ces métadonnées dans la réponse Assembly Status. N’y placez aucun secret.

Choisir la bonne portée des métadonnées

fields contient les valeurs de requête au niveau de l’Assembly. meta contient les métadonnées détectées du fichier. user_meta contient les valeurs personnalisées par fichier, y compris les métadonnées supplémentaires fournies par les téléversements tus. Une valeur absente ou null est lue comme une chaîne vide via une simple Assembly Variable ; une variable numérique ou booléenne utilisée seule conserve son type.

Exemple d’Assembly Variables

Supposons que l’emplacement de stockage des fichiers ne vous convienne pas. Par défaut, Transloadit veille à ne rien écraser. Tous les Robots d’exportation  (English) ont un paramètre path dont la valeur par défaut est "${unique_prefix}/${file.url_name}", ce qui produit des emplacements tels que : "f2/d3eeeb67479f11f8b091b04f6181ad/my-file-name.png".

Nous pourrions, par exemple, remplacer la valeur du paramètre par "${previous_step.name}/${file.id}.${file.ext}", ce qui donnerait des chemins ressemblant à "video-step-name/a8d3eeeb67479f11f8b091b04f6181ad.png".

Toutes les Assembly Variables ne se valent pas : certaines offrent une meilleure unicité (et conviennent donc mieux pour définir à elles seules l’emplacement de stockage). Voici quelques exemples, classés du moins unique au plus unique :

  • ${file.ext} est identique pour de nombreux fichiers
  • ${file.url_name} présente un risque élevé de collisions, notamment entre utilisateurs et au fil du temps, par exemple : avatar.jpg
  • ${previous_step.name} est identique pour tous les fichiers résultant du même Step
  • ${assembly.id} est identique pour tous les fichiers d’une même Assembly
  • ${file.id} ainsi que ${unique_prefix} sont uniques pour chaque fichier

Si les Assembly Variables n’offrent pas assez de souplesse pour votre cas d’usage, nous proposons aussi l’évaluation dynamique de code, à l’aide du Robot /script/run  (English), qui permet d’évaluer du JavaScript à partir de vos Assembly Instructions.