Subidas reanudables

Transloadit ofrece dos métodos para subir archivos a nuestros servidores:

1. Incluir los archivos en la solicitud POST multipart/form-data al crear una Assembly. Cualquier interrupción de esta solicitud hará que fallen las subidas y la Assembly.
2. Subir los archivos mediante el protocolo de subidas reanudables tus⁠. Las subidas pueden recuperarse de problemas de red o del servidor y, además, permiten que el usuario las pause y reanude cuando lo desee. El protocolo tus es abierto y gratuito para realizar subidas reanudables de archivos mediante HTTP, con muchas implementaciones de cliente de código abierto⁠ disponibles.

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

Etapa 1: Crear una nueva Assembly

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

Esto se consigue agregando el campo num_expected_upload_files a la solicitud POST multipart. Su valor es la cantidad de archivos que el cliente desea subir para esta Assembly. También deben incluirse 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 desea 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, similar a la 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 se encuentra en estado de subida y está lista para recibir archivos. La respuesta incluye la propiedad assembly_ssl_url, que identifica de manera ú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 subidas se han iniciado o finalizado.

Etapa 2: Subir cada archivo

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

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

Una subida mediante tus se realiza en dos pasos:

1. Primero, se crea un recurso de subida en el servidor tus. El cliente envía una solicitud POST⁠ e incluye la Assembly URL, el nombre y el tipo del archivo. El servidor responde con una URL de subida a la que el cliente puede enviar el contenido real del archivo.
2. Tras recibir la URL de subida, el cliente envía una solicitud PATCH⁠ a este endpoint con el contenido del archivo para efectuar la subida. Una vez que el archivo se ha transmitido por completo, el servidor tus lo incorpora sin inconvenientes a tu Assembly para procesarlo, sin requerir ninguna interacción adicional.

Puedes encontrar más información 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 subida

El primer paso consiste en crear un recurso de subida en el servidor del protocolo tus enviando una solicitud POST al endpoint especificado por tus_url. Deben incluirse metadatos especiales para asociar la subida con la Assembly creada previamente. En total, deben estar presentes tres valores 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

Todos los metadatos adicionales terminarán como una variable de Assembly en file.user_meta. Puedes utilizarla para realizar acciones dinámicas en tu Template para cada archivo, como alternativa a fields, que se comparte entre todos los archivos de una Assembly. Si necesitas crear ramificaciones según el contenido detectado, es preferible usar ${file.mime} y buscar coincidencias con familias MIME como image/*, video/* o audio/*. ${file.type} también está disponible como categoría general de Assembly Status, pero la coincidencia MIME suele ser la verificació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 14b1b490447d11e6aba4756b3e9d3a0d y el nombre de campo file-input. Los detalles exactos del encoding 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 aHR0cHM6Ly9hcGkyLnRyYW5zbG9hZGl0LmNvbS9hc3NlbWJsaWVzLzE0YjFiNDkwNDQ3ZDExZTZhYmE0NzU2YjNlOWQzYTBk,filename aXNhYWMucG5n,fieldname ZmlsZS1pbnB1dA==

Si la solicitud es correcta, el servidor crea un recurso de subida y devuelve su URL de subida 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 subida, el cliente debe enviar el contenido real del archivo a la URL de subida 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 subida tus, Transloadit la procesa automáticamente usando los parámetros que utilizaste para crear la Assembly, sin que tengas que hacer nada especial. Hasta que hayan finalizado todas las subidas 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 desea subir. El cliente puede elegir libremente subir estos archivos en paralelo o de forma secuencial, según las necesidades de la aplicación. Si intentas agregar a una Assembly más subidas tus de las que especificaste durante la creación de la Assembly, las adicionales se descartarán sin notificación.

Reanudación

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

Primero, el cliente envía una solicitud HEAD a la URL de subida 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 la cantidad de bytes recibidos en el encabezado Upload-Offset. Por ejemplo, la siguiente respuesta muestra una subida en la que se han recibido 3.000 de 10.000 bytes:

HTTP/1.1 204 No Content
Tus-Resumable: 1.0.0
Upload-Offset: 3000
Upload-Length: 10000

Los 7.000 bytes restantes pueden subirse 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 consultar más información sobre las subidas reanudables con el protocolo tus en las preguntas frecuentes sobre tus⁠.