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

Transloadit ofrece dos métodos 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 las cargas y la Assembly fallen.
Los archivos pueden subirse mediante el protocolo de carga reanudable tus. Las cargas pueden recuperarse de problemas de red o del servidor y, además, permiten al usuario pausarlas y reanudarlas cuando lo desee. tus es un protocolo abierto y gratuito para cargas de archivos reanudables a través de HTTP con muchas implementaciones de cliente de código abierto que puedes utilizar.

Este documento describe la API que permite utilizar el segundo método, el de las cargas reanudables. 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 vídeos grandes en 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 archivos de salida almacenados antes de publicar un recurso. La configuración de reintentos del cliente y la recuperación después de recargar la página son independientes del propio protocolo tus.

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

Nota

Muchas integraciones listas para usar, como el SDK de Node o Uppy, utilizan tus de forma predeterminada internamente para subir archivos. Si utilizas una de ellas, no necesitas implementar las cargas reanudables por tu cuenta. Esta documentación está destinada a quienes quieran desarrollar SDK, utilizar SDK sin integración con tus o prescindir por completo de los SDK proporcionados 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. Para 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.

Esto se consigue añadiendo el campo num_expected_upload_files a la solicitud POST multiparte. 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 especifica que el cliente quiere subir dos archivos. Sin embargo, el contenido 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 Assembly se crea correctamente, la API responde con la respuesta de Assembly Status correspondiente, que tiene un aspecto similar al de 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 archivos. 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 se deben subir 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 o finalizado.

Etapa 2: Subir cada archivo

Una vez creada 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 superior para tu aplicación, ponte en contacto con nosotros.

Transloadit ejecuta un servidor tus mediante el software tusd. Su URL se proporciona en la propiedad tus_url del Assembly Status, como se describe en la primera etapa. Este servidor de cargas tus cumple la especificación del protocolo y permite a los clientes tus subir archivos. Puedes implementar tu propio cliente 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 tus se realiza en dos pasos:

Primero, se crea un recurso de carga en el servidor 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 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. Una vez transmitido el archivo completo, el servidor tus lo incorpora de forma transparente a tu Assembly para su procesamiento, sin requerir ninguna interacción adicional.

Puedes encontrar 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 consiste en crear un recurso de carga en el servidor tus enviando una solicitud POST al endpoint especificado por tus_url. Deben incluirse metadatos especiales para asociar la carga con la Assembly creada anteriormente. 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 se incluirá como una Assembly Variable en file.user_meta. Puedes utilizar esto para realizar acciones dinámicas en tu Template por archivo como alternativa a fields, que se comparte entre todos los archivos de una Assembly. Si necesitas establecer distintas rutas de ejecución según el contenido detectado, da preferencia a ${file.mime} y comprueba la coincidencia con familias MIME como image/*, video/* o audio/*. ${file.type} también está disponible como categoría general del 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 ha detectado ninguna categoría. Los consumidores deben aceptar otros valores de cadena para mantener la compatibilidad con futuras categorías. La comprobación de coincidencias MIME suele ser 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 mediante 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 la cabecera 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 del archivo a la URL de carga 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 tus, Transloadit la procesa automáticamente utilizando los parámetros que usaste para crear la Assembly, sin que tengas que hacer nada especial. Hasta que finalicen todas las cargas 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 subir estos archivos en paralelo o de forma secuencial, según las necesidades de la aplicación.

El número de cargas previsto indica a la Assembly cuántos archivos deben terminar de subirse; no es un límite estricto para el número de recursos de carga tus que pueden crearse. Se admiten recursos adicionales mientras la Assembly está en estado de carga para que el cliente pueda recuperarse si se pierde una respuesta de creación de carga. Los contadores de progreso utilizan el número previsto de cargas, seleccionando las que más hayan avanzado y excluyendo 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 interrumpe la red o el usuario pausa la carga, el cliente puede reanudarla desde el punto en el 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 la cabecera Upload-Offset. Por ejemplo, la siguiente respuesta muestra una carga en la que se han recibido 3.000 de los 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 mediante 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]

Puedes encontrar más información sobre las cargas reanudables con tus en las preguntas frecuentes de tus.

Subidas reanudables

Etapa 1: Crear una nueva Assembly

Etapa 2: Subir cada archivo

Creación de la carga

Transferencia de datos

Reanudación