Subidas de archivos, optimización de imágenes y tu propio bucket S3

Separa el trabajo en el momento de la subida del trabajo en el momento de la solicitud

Empieza con dos rutas en lugar de un vago «pipeline de optimización». En la ruta del momento de la subida, un navegador envía un archivo mediante Uppy y el protocolo tus a una Assembly de Transloadit. El Template guardado valida el archivo observado, crea las salidas que deban existir de inmediato y exporta los archivos seleccionados a S3. La aplicación almacena el ID de la Assembly y la identidad persistente del objeto en S3 junto con su registro del recurso.

En la ruta del momento de la solicitud, un navegador solicita una URL de Smart CDN. La URL identifica un Template guardado y una ruta de entrada en S3. En caso de fallo de caché, Transloadit importa ese objeto, aplica el Template con las Assembly Variables permitidas y entrega un resultado a través de /file/serve. La capa de entrega almacena en caché la respuesta; una solicitud en caliente puede reutilizar el derivado sin volver a ejecutar la transformación.

Almacena un archivo subido en S3 sin transformarlo

Usa un Template solo de subida cuando Transloadit deba recibir y exportar el archivo aceptado sin cambiar sus bytes multimedia. /upload/handle recibe la entrada y /s3/store selecciona :original. La ruta de destino usa Assembly Variables para que las subidas simultáneas no se sobrescriban entre sí, mientras el nombre de archivo original apto para URL sigue siendo reconocible.

El ejemplo hace referencia a credenciales de Template y establece acl: "private" porque /s3/store usa public-read de forma predeterminada. Establece bucket_region según la región de AWS real del bucket para evitar una búsqueda de GetBucketLocation y elimina s3:GetBucketLocation de la política de IAM de las credenciales. Trata un objeto público como una decisión explícita del producto y confirma el acceso efectivo a S3 por separado de la configuración del Robot.

{
  "allow_steps_override": false,
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "stored": {
      "use": ":original",
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "bucket_region": "us-east-1",
      "acl": "private",
      "path": "uploads/${unique_prefix}/${file.url_name}"
    }
  }
}

Recibe, valida, optimiza y exporta la subida

Usa un Template de imagen guardado para limitar lo que el código del navegador puede solicitar. /upload/handle recibe el archivo, /file/filter puede rechazar archivos cuyas propiedades detectadas no cumplan la política, /image/resize crea un derivado WebP fijo, y /image/optimize reduce esa salida. /s3/store exporta entonces exactamente los Steps indicados por su valor use. Apúntalo solo a optimized para guardar el derivado, solo a accepted_images para guardar el original aceptado, o a ambos para conservar los dos objetos. preserve_meta_data se deja deliberadamente en su valor predeterminado true para conservar los metadatos de la imagen, como la información de derechos de autor del fotógrafo, aceptando un pequeño aumento de tamaño incluso bajo la prioridad compression-ratio.

Uppy es la capa de subida del navegador, no el límite de autorización. Deja que el plugin de Transloadit solicite al servidor de la aplicación parámetros de Assembly firmados y de corta duración. Mantén allow_steps_override deshabilitado cuando el navegador no deba reemplazar los Steps guardados ni seleccionar otro destino. Reutiliza la ACL privada y la región real del bucket de AWS establecidas en el ejemplo solo de subida. Tanto ${file.id} como ${unique_prefix} son únicos por archivo exportado; este ejemplo de imagen usa el ${file.id} sin barras para que el segmento intermedio de la ruta siga siendo un solo componente, generando claves predecibles images/${file.id}/${file.url_name} que Smart CDN puede referenciar, mientras que los ejemplos de subida y de video usan ${unique_prefix} como directorio que evita colisiones. Como ${file.id} es único para cada archivo exportado, accepted_images y optimized resuelven a claves diferentes bajo images/; la plantilla de ruta compartida no sobrescribe, así que registra cada clave exportada por separado en el estado de la aplicación. Considera la subida completa para el producto solo después de que la aplicación haya conciliado el resultado de la Assembly y las claves persistentes de S3.

{
  "allow_steps_override": false,
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "accepted_images": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "regex", "^(image/jpeg|image/png|image/gif|image/webp|image/avif)$"]],
      "error_on_decline": true
    },
    "resized": {
      "use": "accepted_images",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": 1600,
      "height": 1600,
      "format": "webp"
    },
    "optimized": {
      "use": "resized",
      "robot": "/image/optimize",
      "priority": "compression-ratio",
      "preserve_meta_data": true
    },
    "stored": {
      "use": ["accepted_images", "optimized"],
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "bucket_region": "us-east-1",
      "acl": "private",
      "path": "images/${file.id}/${file.url_name}"
    }
  }
}

Codifica un video antes de almacenarlo en S3

Usa un Template solo de video cuando el objeto persistente en S3 deba ser una variante de reproducción y no la fuente subida. /video/encode lee :original y aplica un ajuste preestablecido ya probado. web/mp4/720p es un punto de partida concreto de MP4 de 1280×720, no una recomendación universal; valida las dimensiones de la fuente, la tasa de fotogramas, el audio, los subtítulos, la calidad, la compatibilidad con dispositivos, el tiempo de procesamiento y el costo según el contrato de reproducción del producto.

El ejemplo exporta el Step encoded y deja la fuente fuera de esa operación de almacenamiento. Añade un segundo Step /s3/store cuando la fuente deba permanecer disponible para una recodificación de mayor calidad, una auditoría o una migración. La codificación puede prolongarse más allá de una solicitud de la aplicación, así que concilia el Assembly Status o un callback de finalización verificado antes de tratar la clave de S3 como publicable.

{
  "allow_steps_override": false,
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "encoded": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "web/mp4/720p"
    },
    "stored": {
      "use": "encoded",
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "bucket_region": "us-east-1",
      "acl": "private",
      "path": "videos/${unique_prefix}/${file.url_name}"
    }
  }
}

Transforma un original de S3 bajo demanda mediante Smart CDN

Una integración de Smart CDN sigue empezando con un Template guardado. /s3/import resuelve la ruta de entrada usando credenciales de Template acotadas, /image/resize lee el valor ${fields.w} proporcionado en la URL y el valor ${browser.wanted_image_format} negociado en la solicitud, y /file/serve selecciona la respuesta. En esta ruta, el borde de Smart CDN de Transloadit deriva un encabezado x-tl-image-format de confianza y previamente normalizado a partir del encabezado Accept del cliente. El encabezado se escribe del lado del servidor y no puede ser controlado por el cliente; los desarrolladores solo hacen referencia a ${browser.wanted_image_format} en las Instructions, que se resuelve en el mismo valor avif, webp o jpg.

Una URL como https://my-workspace.tlcdn.com/responsive-image/images/a8d3eeeb67479f11f8b091b04f6181ad/canoe.jpg?w=640 proporciona images/a8d3eeeb67479f11f8b091b04f6181ad/canoe.jpg como el ${fields.input} implícito (la ruta después del nombre del Template, sin barra inicial) y 640 como ${fields.w}. Esa entrada es la clave images/${file.id}/${file.url_name} registrada para el original persistente accepted_images, que /s3/import lee para el redimensionamiento bajo demanda. El derivado optimizado es un objeto independiente bajo su propio prefijo ${file.id}. Como las dos salidas no comparten directorio, registra cada clave exportada en el estado de la aplicación en lugar de derivar una única clave a partir de la otra o de la URL de la solicitud.

Conserva el prefijo images/ completo en la URL de Smart CDN; no lo añadas de nuevo en el Template. Los valores de la consulta de Smart CDN llegan como cadenas de texto, por lo que la lista de anchos permitidos se compara con los literales de cadena "320" y "640"; un ancho no coincidente recurre a 1280. Mantener separados el mapeo de rutas y la lista de transformaciones permitidas facilita auditar qué objeto de S3 puede leerse y qué variante puede solicitarse.

No interpoles una ruta, un ancho, una calidad o un formato sin restricciones solo porque puedan llegar como un campo. Restringe la credencial de S3 a un prefijo previsto, haz que la aplicación de confianza busque la clave exportada en su registro de recursos y firma una URL que contenga esa clave exacta. La ruta del momento de la solicitud selecciona este Template guardado mediante su URL de Smart CDN en lugar de aceptar Assembly Instructions enviadas por el navegador, por lo que este ejemplo no usa el ajuste allow_steps_override de la subida. Usa la región real del bucket de AWS, como en el ejemplo solo de subida. Valida o asigna los valores de transformación en el Template. Las búsquedas simples como ${fields.input} son gratuitas, mientras que las comparaciones, operaciones aritméticas y expresiones ternarias son Dynamic Evaluation compleja: las ternarias de ancho y formato de este ejemplo invocan /script/run y se facturan en cada fallo de caché. La expresión de formato asigna el valor de respaldo jpg a null, de modo que las solicitudes sin preferencia por un formato moderno conserven el formato original en lugar de aplanar la transparencia o la animación mediante una recodificación innecesaria. Consulta la entrada ${browser.wanted_image_format} en la referencia de Assembly Variables. Mide la primera transformación sin caché por separado de la entrega en caché posterior.

{
  "steps": {
    "imported": {
      "robot": "/s3/import",
      "credentials": "my_s3_credentials",
      "bucket_region": "us-east-1",
      "path": "${fields.input}"
    },
    "resized": {
      "use": "imported",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": "${fields.w === '320' ? 320 : fields.w === '640' ? 640 : 1280}",
      "format": "${browser.wanted_image_format === 'jpg' ? null : browser.wanted_image_format}"
    },
    "served": {
      "use": "resized",
      "robot": "/file/serve",
      "cache_duration": 604800
    }
  }
}

Decide qué almacenar de forma permanente y qué generar bajo demanda

Mantener un original en S3 aporta una fuente estable para reprocesar, pero no exige almacenar cada variante responsiva. Exporta las salidas canónicas que el producto necesite con independencia de la caché: el archivo maestro aprobado, una imagen de anuncio para el mercado, un recurso de impresión o un derivado inmutable de lanzamiento. Deja que Smart CDN cree variantes de presentación acotadas cuyas dimensiones dependan del dispositivo o diseño solicitante.

Por el contrario, no dependas únicamente de una ruta bajo demanda cuando la primera solicitud no pueda tolerar la latencia de procesamiento, un editor deba aprobar los píxeles exactos o los sistemas posteriores requieran un objeto persistente antes de la publicación. En ese caso, crea y exporta el derivado en la Assembly del momento de la subida. La misma aplicación puede usar ambos enfoques para distintas clases de salida sin cambiar quién conserva el origen de forma persistente.

Protege la aplicación, el bucket y la superficie de transformación

Crea credenciales de Template independientes con privilegios mínimos cuando las exportaciones de subida y las importaciones de Smart CDN necesiten acciones o prefijos distintos de AWS. Mantén las claves de AWS en bruto, el Auth Secret de Transloadit y las Instructions sin restricciones fuera de los paquetes del navegador. El servidor de la aplicación debe autorizar al usuario, seleccionar el Template y emitir únicamente los parámetros de subida de corta duración o la URL firmada de Smart CDN adecuados para ese recurso.

Una subida exitosa o una firma válida no es una aprobación de publicación. Valida el tipo MIME detectado y el tamaño en la Assembly, asocia los callbacks de forma idempotente con el inquilino y la Assembly esperados, y expone un resultado solo después de que el objeto persistente y el registro de la aplicación coincidan. Para Smart CDN, diseña el versionado de la fuente, el vencimiento de la URL, la duración de la caché y la eliminación en conjunto, de modo que reemplazar una clave de S3 no pueda dejar activa una dirección de derivado no deseada.

Compara con un pipeline nativo de AWS

Un diseño nativo puede subir archivos mediante una URL prefirmada de S3, reaccionar a eventos de creación de objetos, procesarlos con Lambda u otro servicio de cómputo, almacenar derivados y entregarlos a través de una CDN. Eso puede ser una buena opción cuando la carga de trabajo se mantiene dentro de los límites de tiempo de ejecución admitidos y el equipo quiere operar por sí mismo la autorización, los reintentos, las colas, los códecs, la concurrencia, la observabilidad y la recuperación ante fallos.

Compara rutas completas de producción en lugar de un único cambio de tamaño exitoso. Prueba subidas interrumpidas, fuentes grandes, imágenes con formato incorrecto, orientación y color, eventos duplicados, exportaciones parciales, picos de concurrencia, transformaciones en frío, invalidación de caché, latencia regional y eliminación. Incluye el tiempo de ingeniería y operaciones junto con los costos de subida, procesamiento, almacenamiento, solicitudes y salida de datos. La elección relevante es qué responsabilidades operativas quiere asumir el equipo.