Cuando los usuarios suben archivos desde su dispositivo, cualquier interrupción de la red o problema del servidor puede hacer que la carga falle, lo que normalmente obliga a retransmitir el archivo completo. Las cargas reanudables pueden recuperarse sin problemas de estas interrupciones y ofrecer una experiencia de usuario más robusta, eficiente y agradable.

Transloadit ofrece dos enfoques para subir archivos a nuestros servidores:

Los archivos pueden incluirse en la solicitud POST multipart/form-data al crear una Assembly. Cualquier interrupción de esta solicitud hará que fallen las cargas y la Assembly.
Los archivos pueden subirse con el protocolo de carga reanudable tus. Las cargas pueden recuperarse de problemas de red o del servidor y, además, el usuario puede pausarlas y reanudarlas cuando quiera. El protocolo tus es un protocolo abierto y gratuito para cargas reanudables de archivos a través de HTTP, con muchas implementaciones de cliente de código abierto que puedes usar.

Este documento describe la API del segundo enfoque, el reanudable. Consta de dos etapas, que se describen en este documento.

Para ver un ejemplo de carga → procesamiento → almacenamiento privado y un procedimiento de prueba de interrupción controlada, consulta el flujo de trabajo para videos grandes de la guía de carga de archivos. Reanudar la transferencia no garantiza que el procesamiento o la exportación se completen correctamente. Conserva el ID de la Assembly, comprueba el Assembly Status final y verifica los resultados almacenados antes de publicar un activo. La configuración de reintentos del cliente y la recuperación tras una recarga son independientes del propio protocolo tus.

Para ver un ejemplo de cliente en Java, sigue el DevTip sobre transferencias de archivos reanudables con tus-java-client. Los tutoriales de carga de archivos (English) también tratan los formularios HTML y las interfaces de navegador personalizadas.

Nota

Muchas integraciones listas para usar, como el SDK de Node o Uppy, usan internamente el protocolo tus de forma predeterminada para subir archivos. Si usas alguna de ellas, no necesitas implementar las cargas reanudables por tu cuenta. Esta documentación está dirigida a quienes quieren desarrollar SDKs, usar SDKs sin integración con el protocolo tus o no usar ningún SDK proporcionado por Transloadit.

Etapa 1: Crear una nueva Assembly

Una nueva Assembly se crea enviando una solicitud POST multipart/form-data al endpoint para crear Assemblies. Con las cargas tradicionales, todos los archivos se incluirían como partes adicionales de esta solicitud. Con las cargas reanudables, el cliente no incluye los archivos en esta solicitud, sino que solo indica a la API de Transloadit cuántos archivos se van a subir.

Para ello, se añade el campo num_expected_upload_files a la solicitud POST multipart. Su valor es el número de archivos que el cliente quiere subir para esta Assembly. También deben incluirse los campos adicionales para controlar las Assembly Instructions, como params.

El siguiente fragmento contiene un ejemplo de solicitud HTTP. El cliente proporciona los datos de autenticación y las Assembly Instructions en el campo params. El campo num_expected_upload_files indica que el cliente quiere subir dos archivos. Sin embargo, el contenido real de estos archivos no se incluye en esta solicitud.

POST /assemblies HTTP/1.1
Host: api2.transloadit.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryIAWBI8vxocZzsG03

------WebKitFormBoundaryIAWBI8vxocZzsG03
Content-Disposition: form-data; name="params"

{"auth":{"key":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"},"steps":{"encode":{"robot":"/image/resize"}}}
------WebKitFormBoundaryIAWBI8vxocZzsG03
Content-Disposition: form-data; name="num_expected_upload_files"

2
------WebKitFormBoundaryIAWBI8vxocZzsG03--

Si la creación de la Assembly se realiza correctamente, la API responde con la respuesta de Assembly Status correspondiente, que se parece a este fragmento de ejemplo:

{
    "ok": "ASSEMBLY_UPLOADING",
    "assembly_id": "b841ea401e1a11e7b37d7bda1b503cdd",
    "assembly_ssl_url": "https://api2-freja.transloadit.com/assemblies/b841ea401e1a11e7b37d7bda1b503cdd",
    "websocket_url": "https://api2-freja.transloadit.com/ws20277",
    "tus_url": "https://api2-freja.transloadit.com/resumable/files/",
    "expected_tus_uploads": 2,
    "started_tus_uploads": 0,
    "finished_tus_uploads": 0,
    // …
}

Podemos ver que la Assembly está en estado de carga y lista para recibir cargas. La respuesta incluye la propiedad assembly_ssl_url, que identifica de forma única esta Assembly. También incluye la propiedad tus_url, que define el endpoint al que deben subirse los archivos. Las propiedades expected_tus_uploads, started_tus_uploads y finished_tus_uploads describen cuántos archivos espera Transloadit para esta Assembly y cuántas cargas se han iniciado/finalizado.

Etapa 2: Subir cada archivo

Después de crear la Assembly en la primera etapa, el cliente ya puede empezar a subir archivos al servidor de cargas reanudables de Transloadit.

Nota

Transloadit admite archivos de hasta 200 GB. Si necesitas un límite mayor para tu aplicación, ponte en contacto con nosotros.

Transloadit ejecuta un servidor del protocolo tus con el software tusd. Su URL se indica en la propiedad tus_url del Assembly Status, como se describe en la primera etapa. Este servidor de cargas del protocolo tus cumple la especificación del protocolo y permite que los clientes del protocolo tus suban archivos. Puedes implementar tu propio cliente del protocolo tus siguiendo la especificación o elegir una de las implementaciones de cliente de código abierto en tu lenguaje de programación.

Una carga mediante el protocolo tus se realiza en dos pasos:

Primero, se crea un recurso de carga en el servidor del protocolo tus. El cliente envía una solicitud POST e incluye la Assembly URL, el nombre del archivo y los metadatos fieldname. El servidor responde con una URL de carga, a la que el cliente puede subir el contenido real del archivo.
Al recibir la URL de carga, el cliente envía una solicitud PATCH a este endpoint con el contenido del archivo para realizar la carga propiamente dicha. Una vez que el archivo se ha transmitido por completo, el servidor del protocolo tus introduce el archivo sin problemas en tu Assembly para su procesamiento, sin requerir ninguna interacción adicional.

Encontrarás más detalles sobre la semántica exacta de esta interacción en la especificación del protocolo. En la siguiente sección, nos centraremos en las partes relevantes para la integración con Transloadit.

Creación de la carga

El primer paso es crear un recurso de carga en el servidor del protocolo tus enviando una solicitud POST al endpoint indicado en tus_url. Deben incluirse metadatos especiales para asociar la carga con la Assembly creada previamente. En total, hay tres valores que deben estar presentes en los metadatos:

assembly_url: la Assembly URL obtenida de la propiedad assembly_ssl_url del Assembly Status en la primera etapa
filename: el nombre del archivo
fieldname: el equivalente a los nombres de los campos de entrada en los formularios HTML

Cualquier metadato adicional terminará como una Assembly Variable en file.user_meta. Puedes usarlo para hacer cosas de forma dinámica en tu Template por archivo, como alternativa a fields, que comparten todos los archivos de una Assembly. Si necesitas ramificar según el contenido detectado, es preferible usar ${file.mime} y comparar familias MIME como image/*, video/* o audio/*. ${file.type} también está disponible como categoría amplia de archivo en la respuesta de Assembly Status. Su valor es uno de los siguientes: "audio", "document", "image", "office", "pdf", "swf", "video", "xls", o null cuando no se detectó ninguna categoría. Los consumidores deben aceptar otros valores de cadena para que las categorías futuras sigan siendo compatibles. La comparación por MIME suele ser la comprobación más precisa.

En la solicitud de ejemplo siguiente, subimos un archivo llamado isaac.png, con un tamaño de 10.000 bytes, a la Assembly con el ID b841ea401e1a11e7b37d7bda1b503cdd y el nombre de campo file-input. Los detalles exactos de la codificación de los metadatos en Base64 se describen en la especificación del protocolo.

POST /resumable/files/ HTTP/1.1
Content-Length: 0
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Length: 10000
Upload-Metadata: assembly_url aHR0cHM6Ly9hcGkyLWZyZWphLnRyYW5zbG9hZGl0LmNvbS9hc3NlbWJsaWVzL2I4NDFlYTQwMWUxYTExZTdiMzdkN2JkYTFiNTAzY2Rk,filename aXNhYWMucG5n,fieldname ZmlsZS1pbnB1dA==

Si la solicitud es correcta, el servidor crea un recurso de carga y devuelve su URL de carga en el encabezado Location. Por ejemplo:

HTTP/1.1 201 Created
Tus-Resumable: 1.0.0
Location: https://api2-freja.transloadit.com/resumable/files/136058f2ef4dc9de3f5c23ceed591545

Transferencia de datos

Después de crear la carga, el cliente debe subir el contenido real del archivo a la URL de carga del protocolo tus mediante una solicitud PATCH:

PATCH /resumable/files/136058f2ef4dc9de3f5c23ceed591545 HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Offset: 0
Content-Length: 10000
Content-Type: application/offset+octet-stream

[content of file]

Cuando finaliza una carga del protocolo tus, Transloadit la procesa automáticamente con los parámetros que usaste para crear la Assembly, sin que tengas que hacer nada especial. Hasta que hayan finalizado todas las cargas del protocolo tus, la Assembly permanecerá en el estado ASSEMBLY_UPLOADING, aunque algunos de los archivos ya se hayan procesado.

Estos pasos se repiten para cada archivo que el cliente quiera subir. El cliente puede elegir libremente si sube estos archivos en paralelo o de forma secuencial, según las necesidades de la aplicación.

El número esperado de cargas indica a la Assembly cuántos archivos deben terminar de subirse; no es un límite estricto del número de recursos de carga del protocolo tus que se pueden crear. Se toleran recursos adicionales mientras la Assembly está en proceso de carga, para que un cliente pueda recuperarse cuando se haya perdido una respuesta de creación de carga. Los contadores de progreso usan el número esperado de cargas con mayor progreso, sin contar los recursos abandonados. Sube solo los archivos previstos y reutiliza cada URL de carga conocida al reanudar. Una vez que la Assembly sale de ASSEMBLY_UPLOADING, se rechaza la creación de nuevas cargas.

Reanudación

Si la transferencia de datos falla porque se interrumpió la red o el usuario pausó la carga, el cliente puede reanudar la carga desde el punto en que se detuvo.

Primero, el cliente envía una solicitud HEAD a la URL de carga para determinar cuántos datos pudo recibir el servidor antes de la interrupción:

HEAD /resumable/files/136058f2ef4dc9de3f5c23ceed591545 HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0

La respuesta incluye el número de bytes recibidos en el encabezado Upload-Offset. Por ejemplo, la siguiente respuesta muestra una carga en la que se han recibido 3.000 de 10.000 bytes:

HTTP/1.1 200 OK
Tus-Resumable: 1.0.0
Upload-Offset: 3000
Upload-Length: 10000

Los 7.000 bytes restantes pueden subirse entonces con otra solicitud PATCH:

PATCH /resumable/files/136058f2ef4dc9de3f5c23ceed591545 HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Offset: 3000
Content-Length: 7000
Content-Type: application/offset+octet-stream

[remaining content of file]

Encontrarás más información sobre las cargas reanudables con el protocolo tus en las preguntas frecuentes del protocolo tus.

Subidas reanudables

Etapa 1: Crear una nueva Assembly

Etapa 2: Subir cada archivo

Creación de la carga

Transferencia de datos

Reanudación