Assembly Variables

Transloadit admite variables dentro de tus Assemblies para que puedas crear flujos de trabajo más potentes. Por ejemplo, puedes filtrar archivos según su width, influir en la ubicación de almacenamiento según su type y mucho más. Incluimos una lista completa de las variables de marcador de posición disponibles para Assembly Variables. Se pueden usar en el valor de cualquier parámetro de cualquier Robot.

• ${assembly.id} — El ID de la Assembly que representa la subida actual; es un UUIDv4 sin guiones.

• ${assembly.region} — La región de AWS donde se procesa la Assembly. Puedes usarla para importar archivos desde un bucket de la misma región y así reducir los costos y las latencias de transferencia de datos.

• ${assembly.parent_id} — El ID de la Assembly principal al reejecutarla.

• ${unique_prefix} — Un prefijo único de 33 caracteres que se usa para evitar colisiones entre nombres de archivo, como "f2/d3eeeb67479f11f8b091b04f6181ad".

  Observa el / en el prefijo. Si usas ${unique_prefix} en el parámetro path de 🤖/s3/store, por ejemplo, se crearán subdirectorios en tu bucket de S3. Puede que esto sea o no lo que deseas. Usa ${file.id} si necesitas un prefijo único sin barras diagonales.

• ${unique_original_prefix} — Es similar a ${unique_prefix}, con la diferencia de que dos resultados de encoding distintos del mismo archivo subido (el archivo original) tendrán aquí el mismo prefijo.

• ${previous_step.name} — El nombre del Step anterior que produjo el archivo actual.

• ${file.id} — El ID del archivo que se está procesando; es un UUIDv4 sin guiones.

• ${file.original_id} — El ID del archivo original del que deriva un archivo determinado. Por ejemplo, si usas un Robot de importación para importar archivos y luego les aplicas algún tipo de encoding, los archivos resultantes del encoding tendrán un ${file.original_id} que coincidirá con el ${file.id} del archivo importado.

• ${file.original_name} — El nombre del archivo original (incluida la extensión) del que deriva un archivo determinado. Por ejemplo, si usas un Robot de importación para importar archivos y luego les aplicas algún tipo de encoding, los archivos resultantes del encoding tendrán un ${file.original_name} que coincidirá con el ${file.name} del archivo importado.

• ${file.original_basename} — El nombre base del archivo original del que deriva un archivo determinado. Por ejemplo, si usas un Robot de importación para importar archivos y luego les aplicas algún tipo de encoding, los archivos resultantes del encoding tendrán un ${file.original_basename} que coincidirá con el ${file.basename} del archivo importado.

• ${file.original_path} — La ruta de importación del archivo original del que deriva un archivo determinado. Todos nuestros Robots de importación establecen ${file.original_path} según corresponda.

  Por ejemplo, si usas 🤖/s3/import para importar archivos desde Amazon S3, los archivos importados, así como todos los archivos derivados de ellos, tendrán un file.original_path igual a la ruta del archivo en S3, pero sin el nombre del archivo. Por lo tanto, si la ruta de S3 era "path/to/file.txt", file.original_path será "/path/to/". Si la ruta era "/a.txt", ${file.original_path} será "/".

  file.original_path siempre tendrá suficientes barras diagonales para que puedas usarlo de forma segura en el parámetro path de tu Step de exportación, de esta manera: "path": "${file.original_path}${file.name}". Esto resulta útil si quieres importar archivos, por ejemplo, desde S3, convertirlos de alguna manera y volver a almacenarlos en S3 con la misma estructura de archivos o una similar.

• ${file.name} — El nombre del archivo que se está procesando, incluida la extensión.

• ${file.url_name} — El nombre del archivo convertido en slug.

  Los nombres de archivo se transliteran y depuran para producir una versión segura para URL. Los caracteres no latinos se convierten a equivalentes latinos (por ejemplo, café.jpg → cafe.jpg, бубу.mov → bubu.mov) y los espacios en blanco o signos de puntuación se reemplazan por guiones. Los caracteres consecutivos no diferenciados pueden reducirse a un solo guion.

  Advertencia

  Debido a que los caracteres no latinos se transliteran a equivalentes latinos y otros caracteres complejos o símbolos especiales se reemplazan por guiones, pueden producirse colisiones entre nombres de archivo que no existían en el equipo original del usuario. Para evitarlo, usa siempre ${file.url_name} junto con ${unique_prefix} o ${file.md5hash}.

• ${file.basename} — El nombre del archivo que se está procesando, sin la extensión. Esto te permite realizar acciones dinámicamente por archivo en lugar de por Assembly con fields.

• ${file.url_basename} — El nombre base del archivo convertido en slug (el nombre del archivo sin la extensión).

  Los nombres de archivo se transliteran y depuran para producir una versión segura para URL. Los caracteres no latinos se convierten a equivalentes latinos (por ejemplo, café.jpg → cafe.jpg, бубу.mov → bubu.mov) y los espacios en blanco o signos de puntuación se reemplazan por guiones. Los caracteres consecutivos no diferenciados pueden reducirse a un solo guion.

  Advertencia

  Debido a que los caracteres no latinos se transliteran a equivalentes latinos y otros caracteres complejos o símbolos especiales se reemplazan por guiones, pueden producirse colisiones entre nombres de archivo que no existían en el equipo original del usuario. Para evitarlo, usa siempre ${file.url_basename} junto con ${unique_prefix} o ${file.md5hash}.

• ${file.user_meta} — Las subidas mediante el protocolo tus, que usas para subir archivos a Transloadit, pueden incluir valores de metadatos. Todos los valores adicionales enviados terminarán en user_meta. Estos son metadatos personalizados que proporcionas tú, no el tipo de archivo ni el tipo MIME detectados por Transloadit.

• ${file.stepvars.*} — Valores escalares por archivo definidos en un Step anterior. Consulta Variables de Step para ver las reglas de herencia y un ejemplo.

• ${file.ext} — La extensión del archivo.

• ${file.size} — El tamaño del archivo en bytes.

• ${file.type} — Una categoría general de archivo detectada por Transloadit y expuesta en Assembly Status JSON, como image, video, audio, pdf, office, xls, swf o document. Úsala cuando necesites una categoría general o compatibilidad con flujos de trabajo existentes. Para realizar comprobaciones de contenido confiables, prefiere ${file.mime}.

• ${file.mime} — El tipo MIME del archivo según lo detecta Transloadit, normalmente durante la extracción de metadatos del lado del servidor en el flujo normal de subida. Puede diferir del tipo MIME informado originalmente por el cliente o el navegador. Prefiérelo para ramificaciones según el tipo de contenido y usa, cuando sea posible, coincidencias de familias MIME como image/*, video/* o audio/*.

• ${file.md5hash} — El hash MD5 del archivo. Este hash se calcula sobre el contenido del archivo, no solo sobre su nombre.

• ${file.*} — Cualquier propiedad del archivo disponible en el array de resultados finales, como ${file.meta.width}. No todas las claves de metadatos están disponibles para todos los tipos de archivo.

• ${fields.*} — Los campos enviados junto con la subida.

  Por ejemplo, en el caso de enviar un formulario donde Uppy se configuró para permitir fields: ['myvar'] y el formulario tenía una etiqueta como <input type="hidden" name="myvar" value="1" />, ${fields.myvar} contendría un valor de 1.

  Como alternativa, los campos también se pueden completar mediante programación de esta manera:

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

  En caso de conflicto, las variables derivadas de los campos del formulario tienen prioridad sobre las derivadas de la clave fields.

  Las solicitudes de Smart CDN rellenan el mismo espacio de nombres desde la URL. Los parámetros de consulta se convierten en valores ${fields.*}, y la ruta posterior al nombre del Template se convierte en el valor implícito ${fields.input} sin una barra inicial. Por ejemplo, https://my-app.tlcdn.com/image-template/images/canoe.jpg?w=640 proporciona ${fields.input} como images/canoe.jpg y 640 como ${fields.w}. Por lo tanto, usar ${fields.input} como path para 🤖/s3/import lee la clave de objeto images/canoe.jpg. Esta fuente basada en la URL es distinta de los campos de formulario durante la subida y de la clave fields de la Assembly descrita anteriormente.

• ${browser.wanted_image_format} — El formato de imagen preferido por la cabecera Accept del cliente que realiza la solicitud. Se resuelve como el formato entre "avif", "webp" y "jpg" que tenga el mayor peso de calidad (q) positivo, con preferencia en ese orden en caso de empate. Los intervalos comodín como */* e image/* no seleccionan AVIF ni WebP. Una cabecera ausente, vacía o compuesta solo por comodines se resuelve como "jpg". JPEG también es un candidato completo, por lo que image/avif;q=0.2,image/jpeg;q=1 se resuelve como "jpg".

  La variable también está disponible en las Assemblies normales. Las solicitudes del SDK y de la API sin una cabecera Accept significativa suelen usar el valor alternativo "jpg". Un edge de Smart CDN puede establecer en su lugar la cabecera fiable y normalizada previamente x-tl-image-format, que se resuelve como el mismo valor "avif", "webp" o "jpg" sin volver a interpretar Accept.

  El valor alternativo "jpg" describe la compatibilidad del cliente, no el archivo de entrada. Al usar 🤖/image/resize, asigna null a ese valor alternativo para conservar el formato de entrada en clientes sin una preferencia explícita por un formato moderno. Así se preservan la transparencia y la animación en lugar de recodificar innecesariamente la entrada como JPEG.

• ${Date.now()} — La fecha y hora actuales representadas como el número de milisegundos transcurridos desde la época UNIX, que se define como la medianoche al comienzo del 1 de enero de 1970, UTC. Técnicamente, no es una variable, sino que usa la evaluación dinámica de código.

Variables de Step por archivo

Usa el parámetro opcional stepvars para conservar un valor de un Step anterior y leerlo después como ${file.stepvars.key}, donde key es el nombre que asignaste. El mapa se adjunta a los archivos, no se comparte entre toda la Assembly y no modifica el contenido del archivo.

Cada valor debe resolverse como una cadena, un número finito, un booleano o null. No se admiten arrays ni objetos anidados. Puedes usar valores literales o Assembly Variables.

A menos que desactives la interpolación de variables para este campo, un valor que consiste en una sola variable conserva su tipo numérico o booleano; una cadena mixta sigue siendo una cadena. Tanto un null guardado como una clave no definida se leen como una cadena vacía mediante ${file.stepvars.key}, aunque el JSON de estado puede conservar null.

En :original (🤖/upload/handle), los valores se resuelven por separado para cada archivo subido después de extraer los metadatos, tanto en subidas multipart como tus.

Un Step de procesamiento puede ejecutar jobs separados para diferentes archivos de entrada. En cada job, los valores de stepvars se resuelven antes de ejecutar el Robot, usando las variables del primer archivo de entrada. Cada archivo emitido por ese job recibe los mismos valores resueltos. Los stepvars de Steps de procesamiento no pueden leer ${result.*}: una referencia simple como ${result.md5hash} se resuelve como una cadena vacía. Usa user_meta para valores que dependan de cada archivo de salida.

Los parámetros que se resuelven antes de ejecutar el Robot pueden leer claves heredadas, pero no los valores que asigna el propio Step. Lee los valores recién asignados en un Step posterior.

La herencia depende del Robot. Por ejemplo, 🤖/image/resize conserva el mapa del primer archivo de entrada. Los mapas de varias entradas no se fusionan y las ramas separadas mantienen mapas independientes. Algunos Robots crean archivos de salida nuevos sin heredar el mapa: 🤖/html/convert lo hace incluso al convertir un archivo HTML de entrada. Asigna explícitamente las claves necesarias en los stepvars de ese Step usando las variables del archivo de entrada. Las claves asignadas por el Step actual reemplazan las claves coincidentes que ya existen en sus archivos de salida; las demás claves existentes se conservan.

En un Step de procesamiento, un valor que se resuelve como un array u objeto provoca ROBOT_VALIDATION_BASE_ERROR cuando el Robot emite un archivo de resultado, no durante la interpolación previa a la ejecución. La misma validación de valores escalares se aplica en :original: elige variables que sepas que son escalares, como ${file.md5hash}, y no asignes el objeto ${file.meta} completo.

Si un Step no tiene archivo de entrada, las referencias ${file.*} como ${file.md5hash} se resuelven como una cadena vacía. Para capturar metadatos de archivos importados, asigna stepvars en un Step posterior que use esos archivos.

Conserva el hash de una imagen subida

Este fragmento de Assembly Instructions captura el MD5 de cada imagen subida antes de redimensionarla. Configura la credencial de Template de S3 indicada antes de usar el Step de exportación.

{
  "steps": {
    ":original": {
      "robot": "/upload/handle",
      "stepvars": {
        "source_md5": "${file.md5hash}",
        "stage": "uploaded"
      }
    },
    "resized": {
      "use": ":original",
      "robot": "/image/resize",
      "width": 640,
      "height": 640,
      "resize_strategy": "fit",
      "result": true,
      "stepvars": {
        "stage": "resized"
      }
    },
    "exported": {
      "use": "resized",
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS_NAME",
      "path": "${file.stepvars.source_md5}/${unique_prefix}/${file.url_name}"
    }
  }
}

El archivo resized conserva source_md5 de la subida y cambia stage a "resized". La ruta de exportación lee ese hash guardado, no el hash del archivo redimensionado. ${unique_prefix} mantiene la ruta única incluso cuando las subidas tienen contenido idéntico.

Los objetos de archivo en uploads y results exponen el mapa como stepvars en la Respuesta de Assembly Status. El mapa puede estar vacío ({}); trata el campo como opcional al interpretar las respuestas. En este ejemplo, result: true incluye los archivos redimensionados en results. Estos metadatos son visibles para la aplicación, por lo que no debes guardar secretos en ellos.

Elige el ámbito adecuado para los metadatos

• fields proporciona valores de la solicitud a nivel de Assembly mediante ${fields.*}; no es un mapa por archivo.
• stepvars guarda valores escalares con cada archivo para los Steps posteriores mediante ${file.stepvars.*}.
• user_meta es un mapa separado de metadatos personalizados, que también se usa en las subidas tus. Úsalo para datos JSON anidados o valores de Steps de procesamiento basados en cada archivo de salida mediante ${result.*}. Usa stepvars para conservar valores escalares de entrada sin mezclarlos con los metadatos personalizados de tu aplicación.

Ejemplo de Assembly Variables

Supongamos que no te gusta la ubicación donde se almacenan los archivos. De forma predeterminada, Transloadit procura no sobrescribir nada. Todos los Robots de exportación tienen un parámetro path con un valor predeterminado de "${unique_prefix}/${file.url_name}", lo que produce ubicaciones como: "f2/d3eeeb67479f11f8b091b04f6181ad/my-file-name.png".

Por ejemplo, podríamos cambiar el valor del parámetro a "${previous_step.name}/${file.id}.${file.ext}", lo que haría que las rutas quedaran de esta manera: "video-step-name/a8d3eeeb67479f11f8b091b04f6181ad.png".

No todas las Assembly Variables ofrecen el mismo nivel de unicidad; algunas son más únicas y, por lo tanto, más adecuadas como única base para la ubicación de almacenamiento. Estos son algunos ejemplos, ordenados de menor a mayor unicidad:

• ${file.ext} es igual para muchos archivos
• ${file.url_name} presenta una alta probabilidad de colisiones, especialmente entre usuarios y a lo largo del tiempo; por ejemplo: avatar.jpg
• ${previous_step.name} es igual para todos los archivos que son resultados del mismo Step
• ${assembly.id} es igual para todos los archivos dentro de una sola Assembly
• ${file.id}, al igual que ${unique_prefix}, es único para cada archivo

Si Assembly Variables no ofrecen suficiente flexibilidad para tu caso de uso, también ofrecemos ejecución dinámica de código mediante el Robot /script/run, que permite evaluar JavaScript desde tus Assembly Instructions.