# Subidas reanudables Cuando los usuarios suben archivos desde su dispositivo, cualquier interrupción de la red o problema del servidor podría hacer que la subida falle, lo que normalmente requeriría retransmitir el archivo completo. Las subidas reanudables pueden recuperarse sin inconvenientes de estas interrupciones y ofrecer una experiencia de usuario más sólida, eficiente y agradable. 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](/es/docs/api/assemblies-post.md). 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](https://tus.io). 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. Tus es un protocolo abierto y gratuito para realizar subidas reanudables de archivos mediante HTTP, con muchas [implementaciones de cliente de código abierto](https://tus.io/implementations) disponibles. Este documento describe la API del segundo método, el reanudable. Consta de dos etapas, que se describen en este documento. ###### 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 por tu cuenta las subidas reanudables. Esta documentación está destinada a quienes deseen desarrollar SDK, utilizar SDK sin integración con Tus o no utilizar ningún SDK proporcionado por Transloadit. ### Etapa 1: Crear una nueva Assembly Se crea una nueva Assembly enviando una solicitud POST `multipart/form-data` al endpoint para [crear Assemblies](/es/docs/api/assemblies-post.md). 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. ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```http 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](/es/docs/api/assembly-status-response.md) correspondiente, similar a la de este fragmento de ejemplo: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```jsonc { "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 estaAssembly. 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. ###### Nota Transloadit admite archivos de hasta 200 GB. Si necesitas un límite mayor para tu aplicación,[comunícate con nosotros](mailto:support@transloadit.com). Transloadit ejecuta un servidor [Tus](https://tus.io) 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](https://tus.io/protocols/resumable-upload)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](https://tus.io/implementations) 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](https://tus.io/protocols/resumable-upload#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](https://tus.io/protocols/resumable-upload#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](https://tus.io/protocols/resumable-upload). 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 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` delAssembly 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](/es/docs/topics/assembly-instructions.md#assembly-variables) 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](https://tus.io/protocols/resumable-upload#upload-metadata). ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```http 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: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```http 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 Tus mediante una solicitud PATCH: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```http 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 laAssembly, 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: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```http 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: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```http 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: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```http 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 Tus en las[preguntas frecuentes sobre Tus](https://tus.io/faq).