Flujos de trabajo de procesamiento multimedia personalizables

Conclusiones clave

Modela el flujo de trabajo como un grafo cuyas relaciones use hagan explícito el orden.
Mantén la política de procesamiento estable en un Template guardado y expón solo campos validados.
Ejecuta derivados independientes en paralelo. Los Steps por archivo procesan cada archivo emitido por los Steps ascendentes que leen; solo los Steps de fusión o agrupación esperan un conjunto completo.

Un flujo de trabajo personalizable debe exponer los pocos valores que legítimamente cambian según el trabajo, manteniendo controlado su grafo de procesamiento. Las Assembly Instructions de Transloadit expresan ese grafo como Steps con nombre, y un Template guardado permite que una aplicación lo ejecute repetidamente sin volver a enviar las credenciales de almacenamiento ni la política de transformación.

Dibuja las dependencias antes de escribir JSON

Empieza por los archivos y las decisiones, no por los nombres de los Robots. Identifica los archivos y derivados que produce el flujo de trabajo, las políticas de validación que aplica, los destinos en los que escribe y los casos de fallo que el producto debe manejar, como una entrada rechazada o un fallo de exportación. Luego dale a cada operación un nombre de Step que describa su resultado. En las Assembly Instructions, el valor use crea la arista entre un Step anterior y su consumidor; el orden de las claves en el objeto JSON no crea una secuencia de ejecución.

Los Steps independientes pueden leer el mismo archivo ascendente y ejecutarse simultáneamente. Dos Steps de redimensionamiento que provienen de un mismo Step de filtrado compartido no se esperan entre sí; cada uno comienza cuando el filtro emite un archivo. El JSON concreto para esta estructura aparece en la siguiente sección. Cada derivado se exporta a su propio prefijo, de modo que las variantes paralelas nunca comparten una clave. Un Robot de fusión es diferente: puede necesitar un conjunto agrupado de entradas nombradas antes de poder producir algo. Modela esa dependencia explícitamente en lugar de confiar en el orden aparente del JSON.

Los nodos son Steps

Cada Step con nombre invoca un Robot con un conjunto acotado de parámetros.

Las aristas provienen de use

La entrada ascendente declarada determina la disponibilidad y el flujo de datos.

Las ramas pueden superponerse

Los derivados que comparten una entrada pueden ejecutarse de forma independiente en lugar de convertirse en una cadena en serie.

Separa la política fija de los campos en tiempo de ejecución

Mantén la validación, los Robots permitidos, los roles de salida y los destinos en un Template guardado. Los valores que realmente varían según la solicitud pueden llegar como campos y referenciarse mediante variables ${fields.*}. Un ID de inquilino, un perfil de variante solicitado o un ID de recurso estable pueden ser razonables; un nombre de Robot arbitrario, una credencial de destino o una dimensión de salida sin restricciones, por lo general, no lo son.

Establece allow_steps_override en false en el Template cuando el código que llama no sea confiable y no deba fusionar nuevos Steps en el grafo guardado. Ese ajuste protege el grafo, no el significado de cada campo. Valida los campos en la aplicación antes de crear la Assembly: autoriza al inquilino, acepta solo perfiles conocidos, limita los rangos numéricos y rechaza claves desconocidas. El Template también debería usar valores predeterminados seguros o filtros en los casos en que un valor incorrecto pudiera generar una carga de trabajo excesiva. El Template completo a continuación incluye parámetros de validación de entrada, exportación y notificación, que se explican en las siguientes secciones.

Bloquear y parametrizar un flujo de trabajo de imágenes

{
  "allow_steps_override": false,
  "max_number_of_files": 1,
  "max_size": 52428800,
  "notify_url": "https://app.example.com/webhooks/transloadit",
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "accepted_images": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        ["${file.mime}", "regex", "^(image/jpeg|image/png|image/webp|image/avif)$"]
      ],
      "error_on_decline": true,
      "error_msg": "Upload a JPEG, PNG, WebP, or AVIF image."
    },
    "web_image": {
      "use": "accepted_images",
      "robot": "/image/resize",
      "width": 1600,
      "height": 1200,
      "resize_strategy": "fit",
      "format": "webp"
    },
    "thumbnail": {
      "use": "accepted_images",
      "robot": "/image/resize",
      "width": 320,
      "height": 320,
      "resize_strategy": "fillcrop",
      "format": "webp"
    },
    "export_web": {
      "use": "web_image",
      "robot": "/s3/store",
      "acl": "private",
      "credentials": "media-output",
      "path": "${fields.tenant_id}/${assembly.id}/web/${unique_prefix}/${file.url_name}"
    },
    "export_thumb": {
      "use": "thumbnail",
      "robot": "/s3/store",
      "acl": "private",
      "credentials": "media-output",
      "path": "${fields.tenant_id}/${assembly.id}/thumb/${unique_prefix}/${file.url_name}"
    }
  }
}

Ejecutar el Template guardado con campos validados

// Illustrative fragment: these objects come from your application, not the SDK.
const assembly = await transloadit.createAssembly({
  files: { image: inputPath },
  params: {
    template_id: process.env.TRANSLOADIT_TEMPLATE_ID,
    fields: {
      tenant_id: tenant.id,
    },
  },
})

await jobs.attachAssembly({
  jobId: job.id,
  assemblyId: assembly.assembly_id,
})

Política estable

Las elecciones de Robot, la validación, los destinos de exportación y los roles de los resultados pertenecen a una configuración controlada.

Variación acotada

Los campos exponen un contrato pequeño en lugar de dejar todo el grafo bajo control de quien llama.

Dos capas de validación

La autorización de la aplicación y las salvaguardas del Template abordan distintas rutas de fallo y abuso.

Valida las entradas antes de un procesamiento costoso

Coloca comprobaciones económicas y deterministas antes de generar los derivados. El max_size a nivel de Assembly y de Template limita el tamaño combinado de toda la subida (toda la subida se cancela si el total lo supera, incluso cuando cada archivo individual está por debajo de ese límite), y max_number_of_files limita cuántos archivos puede contener la solicitud. Para un límite de tamaño por archivo, usa /file/filter en ${file.size}, que evalúa cada archivo individualmente y también puede inspeccionar el tipo MIME detectado por el servidor y los metadatos extraídos. Cuando una entrada no compatible deba hacer fallar todo el trabajo, establece error_on_decline y proporciona un mensaje que le indique al usuario qué debe cambiar.

El ejemplo limita deliberadamente el recorrido a un solo archivo subido. Aumentar max_number_of_files hace relevante el comportamiento de rechazo con varios archivos. Prefiere una lista explícita de formatos permitidos, como JPEG, PNG, WebP y AVIF, cuando la operación descendente solo admite imágenes de navegador. Una regla amplia image/* acepta formatos que el destino podría no renderizar, mientras que la extensión del nombre de archivo y el valor MIME informado por el navegador son solo afirmaciones del cliente. Decide por separado si un archivo rechazado debe hacer fallar toda una Assembly de varios archivos, desaparecer de una rama o entrar en otra rama; esos son comportamientos del producto, no ajustes incidentales del filtro.

Primero, comprobaciones económicas

Rechaza las entradas no adecuadas antes de que comiencen transformaciones costosas o lentas.

Propiedades detectadas por el servidor

Usa el MIME y los metadatos extraídos en lugar de confiar solo en las extensiones.

Comportamiento de rechazo explícito

Elige si un archivo rechazado termina el trabajo o simplemente deja de avanzar por una rama.

Exporta con credenciales y rutas que puedas rotar

Crea credenciales de Template para el destino de almacenamiento y haz referencia a su nombre desde el Robot de exportación. Las Assembly Instructions contienen entonces una etiqueta de credencial estable en lugar de una clave de acceso y un secreto. Rotar la credencial almacenada actualiza las próximas ejecuciones sin necesidad de copiar un nuevo secreto en el código fuente, en los parámetros del navegador ni en cada Template que la use. /s3/store establece acl en public-read de forma predeterminada, así que configúralo como private a menos que los archivos exportados deban ser públicamente legibles.

Construye las rutas de destino a partir de identificadores validados del inquilino o del recurso, el ID de la Assembly, el rol de la variante y el ${unique_prefix} generado por la plataforma de Transloadit. Este prefijo único de 33 caracteres por archivo contiene una barra diagonal, por lo que se expande en un subdirectorio de dos niveles dentro de la clave de almacenamiento y evita que entradas con el mismo nombre dentro de una Assembly colisionen. Asigna a cada derivado paralelo un segmento de ruta distinto según el rol de la variante, como web/ o thumb/, para que sus exportaciones nunca colisionen en la misma clave. No uses un nombre de archivo de subida sin sanear como única clave, y decide qué debe hacer un reintento si el objeto ya existe. Una exportación idempotente escribe el mismo objeto previsto o comprueba y concilia el destino antes de crear otro. Registra la clave de almacenamiento final de cada resultado para que la eliminación y el reemplazo puedan encontrar todas las copias más adelante.

Etiqueta de la credencial

Separa la rotación de secretos del JSON del flujo de trabajo que la referencia.

Entradas de ruta estables

Los identificadores de inquilino, recurso, Assembly y variante hacen que los resultados sean trazables.

Contrato de sobrescritura

Define si una clave de destino existente se reemplaza, se rechaza, se versiona o se concilia.

Opera cada ejecución como una máquina de estados asíncrona

Guarda un registro de trabajo de la aplicación antes de iniciar la Assembly. Incluye el actor, el inquilino, el identificador del archivo de entrada, el ID de Template, los campos validados, la etiqueta del flujo de trabajo de la aplicación y una clave de operación estable. La etiqueta del flujo de trabajo de la aplicación y la clave de operación son identificadores locales que se almacenan únicamente en tu propia base de datos; nunca se envían a Transloadit. Agrega el ID de la Assembly en cuanto se devuelva. Este registro permite que los reintentos comprueben si ya hay un trabajo equivalente activo o completo, en lugar de crear una segunda exportación tras un tiempo de espera agotado.

Configura notify_url cuando el trabajo deba finalizar en segundo plano; como se muestra en el Template anterior, defínelo en el Template guardado para que cada ejecución lo herede. Verifica la firma de la notificación con el Auth Secret perteneciente a la Auth Key usada para esa Assembly, devuelve HTTP 200 con prontitud ante una entrega válida y procesa los duplicados de forma idempotente. Un trabajo de conciliación periódico debería comparar el trabajo activo local con el Assembly Status para que un callback perdido no deje un registro varado. Supervisa la latencia, la clase de fallo, los bytes procesados, las salidas y los reintentos de webhook según la etiqueta del flujo de trabajo de la aplicación.

Clave de operación

Evita que un reintento del código que llama cree en silencio procesamiento y exportaciones duplicados.

Webhook verificado

Autentica los datos de finalización mientras permite que la solicitud original termine rápidamente.

Conciliación

Repara el estado local cuando las notificaciones llegan retrasadas, duplicadas o no llegan.

Prueba los cambios con datos de prueba representativos

Un flujo de trabajo solo es tan estable como las entradas usadas para probarlo. Mantén pequeños datos de prueba para cada formato aceptado, dimensiones límite, transparencia, orientación, animación, entrada de gran tamaño y un tipo explícitamente rechazado. Verifica el rol, el formato, las dimensiones, la ruta de almacenamiento y el estado final de la salida, en lugar de comprobar únicamente que la Assembly se completó. Incluye un fallo de destino y una notificación duplicada para que la ruta de recuperación se ponga a prueba antes de un incidente.

Registra el comportamiento previsto en la configuración de la aplicación o en el control de versiones, y asocia esa etiqueta con cada ejecución. Cuando el Template guardado cambie, pruébalo en un Workspace que no sea de producción o con destinos aislados, revisa el costo y los metadatos, y desplaza primero una porción limitada del tráfico. Si los resultados empeoran, dirige el trabajo nuevo de vuelta al comportamiento controlado anterior y concilia cualquier Assembly que ya esté en curso en lugar de asumir que se detuvo.

Matriz de formatos

Cubre las entradas y las variaciones de metadatos que el producto promete aceptar.

Datos de prueba de fallos

Demuestra el rechazo, el fallo de exportación, la entrega duplicada y el comportamiento de reejecución, además del éxito.

Implementación acotada

Limita el costo y el impacto en el cliente mientras se mide un flujo de trabajo modificado bajo tráfico real.

Detalles técnicos que conviene conocer

Un Step por archivo comienza en cuanto un Step anterior nombrado en su valor use emite un archivo; solo los Robots de fusión o agrupación esperan un conjunto completo de entradas nombradas. La posición de un Step dentro del objeto JSON no determina el orden de ejecución.
Las Assembly Variables, como ${fields.tenant_id}, ${assembly.id} y ${file.url_name} (una versión segura para URL, con formato slug, del nombre del archivo del Step actual, incluida su extensión), se resuelven en el momento de la ejecución y pueden parametrizar dimensiones, rutas y otros valores de Robot. En las rutas de exportación de ejemplo, ${assembly.id} aporta unicidad por cada ejecución y ${unique_prefix}, que contiene una barra, mantiene los archivos de una ejecución diferenciados.
Establecer allow_steps_override en false en un Template guardado impide que el código que llama fusione Steps de reemplazo en ese Template. Los campos en tiempo de ejecución igualmente necesitan validación y autorización del lado de la aplicación.
/file/filter puede comparar las propiedades de archivo detectadas por el servidor con condiciones de array. Una lista de MIME permitidos específica es más segura que confiar en la extensión del nombre de archivo o en el tipo reportado por el cliente.
Las credenciales de Template mantienen los secretos de destino separados del JSON del Template y pueden actualizarse sin copiar claves en cada integración.
Las Assembly Notifications se reintentan cuando el receptor no devuelve HTTP 200. Los consumidores deben verificar la firma y tolerar entregas duplicadas, retrasadas o fuera de orden.

Un enfoque práctico

1
Dibuja las entradas requeridas, los derivados, los Steps que leen de varios derivados, las exportaciones y los límites de fallo.
2
Guarda y bloquea un Template cuyas entradas variables estén deliberadamente limitadas.
3
Envía un archivo representativo e inspecciona cada Step en el Assembly Status.
4
Añade un manejo verificado de webhooks, persistencia idempotente, datos de prueba y un lanzamiento controlado.

Un flujo de trabajo multimedia de cuatro etapas

Cuándo resulta útil Transloadit

Usa un Template guardado para conectar /upload/handle, /file/filter, Steps paralelos de /image/resize y /s3/store. Bloquea el grafo de procesamiento estableciendo allow_steps_override en false, pasa campos acotados en tiempo de ejecución y concilia la finalización mediante el Assembly Status y webhooks verificados.

Límite de la arquitectura

Los Templates de Assembly describen el procesamiento y el movimiento de archivos. No poseen las aprobaciones del producto, la autorización del inquilino, el estado del negocio ni el historial de configuración de una aplicación; mantén esas decisiones en el sistema que inicia y registra cada trabajo.

Preguntas frecuentes

¿El orden de los Steps en el JSON controla la ejecución?

No. Las dependencias use controlan cuándo puede ejecutarse un Step. Los Steps independientes pueden ejecutarse en paralelo aunque uno aparezca más adelante en el objeto.

¿Un Template bloqueado puede seguir aceptando valores personalizados?

Sí. allow_steps_override: false impide que quienes llaman reemplacen los Steps de procesamiento. La aplicación aún puede enviar campos utilizados por las variables ${fields.*}, y debe validar y autorizar esos valores.

¿Deben aparecer las claves de almacenamiento en la nube en las Assembly Instructions?

No. Guárdalas como credenciales de Template y haz referencia al nombre de la credencial desde el Robot de almacenamiento. Esto mantiene los secretos fuera del JSON del flujo de trabajo y hace que la rotación sea independiente.

¿Cómo debería cambiar un flujo de trabajo de forma segura?

Mantén la etiqueta del flujo de trabajo de la aplicación y el historial de configuración en tu propio sistema, prueba los cambios con datos de prueba representativos y desplaza el tráfico de forma deliberada. Conserva suficiente información sobre cada trabajo para explicar qué comportamiento produjo sus resultados.

¿Qué ocurre cuando un webhook se entrega dos veces?

Trata la entrega duplicada como algo normal. Verifica la firma, busca la Assembly o la clave de operación, y haz que la misma actualización final se pueda aplicar de nuevo de forma segura sin duplicar recursos ni eventos visibles para el usuario.

Flujos de trabajo de procesamiento multimedia personalizables con Transloadit