Transloadit

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.

  • ${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.

  • ${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.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.

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.