Quando os usuários enviam arquivos do próprio dispositivo, qualquer interrupção na rede ou problema no servidor pode fazer o upload falhar, geralmente exigindo que o arquivo inteiro seja retransmitido. Uploads retomáveis podem se recuperar dessas interrupções de forma transparente e oferecer uma experiência de uso mais robusta, eficiente e agradável.

A Transloadit oferece duas abordagens para enviar arquivos aos nossos servidores:

Os arquivos podem ser incluídos na requisição POST multipart/form-data ao criar uma Assembly. Qualquer interrupção nessa requisição fará com que os uploads e a Assembly falhem.
Os arquivos podem ser enviados usando o protocolo tus de upload retomável. Os uploads podem se recuperar de problemas de rede ou servidor, além de permitir que o usuário pause e retome os uploads quando quiser. tus é um protocolo aberto e gratuito para uploads retomáveis de arquivos via HTTP, com muitas implementações de cliente de código aberto que você pode usar.

Este documento descreve a API por trás da segunda abordagem, com uploads retomáveis. Ela consiste em duas etapas, que são descritas neste documento.

Para ver um exemplo de upload → processamento → armazenamento privado e um procedimento de teste de interrupção controlada, consulte o fluxo de trabalho para vídeos grandes no guia de upload de arquivos (English). Retomar a transferência não garante que o processamento ou a exportação sejam bem-sucedidos. Guarde o Assembly ID, confira o Assembly Status final e verifique os arquivos de saída armazenados antes de publicar um recurso. As configurações de novas tentativas do cliente e a recuperação após um recarregamento são independentes do próprio protocolo tus.

Para ver um exemplo de cliente Java, siga a DevTip sobre transferências retomáveis de arquivos com tus-java-client (English). Os tutoriais de upload de arquivos (English) também abordam formulários HTML e interfaces personalizadas para navegadores.

Observação

Muitas integrações prontas para uso, como o SDK para Node ou o Uppy, usam tus por padrão internamente para enviar arquivos. Se você usa uma delas, não precisa implementar uploads retomáveis por conta própria. Esta documentação se destina a quem quer desenvolver SDKs, usar SDKs sem integração com tus ou não usar nenhum SDK fornecido pela Transloadit.

Etapa 1: Criar uma nova Assembly

Uma nova Assembly é criada enviando uma requisição POST multipart/form-data ao endpoint para criar Assemblies. Nos uploads tradicionais, todos os arquivos seriam incluídos como partes adicionais nessa requisição. Nos uploads retomáveis, o cliente não inclui os arquivos nessa requisição, apenas informa à API da Transloadit quantos arquivos devem ser enviados.

Isso é feito adicionando o campo num_expected_upload_files à requisição POST multipart. Seu valor é o número de arquivos que o cliente quer enviar para essa Assembly. Campos adicionais para controlar as Assembly Instructions, como params, também devem ser incluídos.

O trecho a seguir contém um exemplo de requisição HTTP. O cliente fornece os dados de autenticação e as Assembly Instructions no campo params. O campo num_expected_upload_files especifica que o cliente quer enviar dois arquivos. No entanto, o conteúdo desses arquivos não é incluído nessa requisição.

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--

Se a criação da Assembly for bem-sucedida, a API retornará a resposta de Assembly Status correspondente, semelhante a este trecho de exemplo:

{
    "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 a Assembly está no estado de upload e pronta para receber uploads. A resposta inclui a propriedade assembly_ssl_url, que identifica essa Assembly de forma única. Ela também inclui a propriedade tus_url, que define o endpoint para o qual os arquivos devem ser enviados. As propriedades expected_tus_uploads, started_tus_uploads e finished_tus_uploads descrevem quantos arquivos a Transloadit espera receber para essa Assembly e quantos uploads foram iniciados/concluídos.

Etapa 2: Enviar cada arquivo

Depois que a Assembly é criada na primeira etapa, o cliente pode começar a enviar arquivos ao servidor de uploads retomáveis da Transloadit.

Observação

A Transloadit aceita arquivos de até 200 GB. Se você precisar de um limite maior para sua aplicação, entre em contato.

A Transloadit executa um servidor tus usando o software tusd. A URL desse servidor é fornecida pela propriedade tus_url no Assembly Status, conforme descrito na primeira etapa. Esse servidor de upload tus segue a especificação do protocolo e permite que clientes tus enviem arquivos. Você pode implementar seu próprio cliente tus seguindo a especificação ou escolher uma das implementações de cliente de código aberto na sua linguagem de programação.

Um upload via tus ocorre em dois passos:

Primeiro, um recurso de upload é criado no servidor tus. O cliente envia uma requisição POST e inclui a Assembly URL, o nome do arquivo e os metadados de fieldname. O servidor responde com uma URL de upload, para a qual o cliente pode enviar o conteúdo do arquivo.
Ao receber a URL de upload, o cliente envia uma requisição PATCH a esse endpoint com o conteúdo do arquivo para realizar o upload. Quando o arquivo tiver sido totalmente transmitido, o servidor tus encaminhará o arquivo de forma transparente à sua Assembly para processamento, sem exigir nenhuma interação adicional.

Mais detalhes sobre a semântica exata dessa interação estão disponíveis na especificação do protocolo. Na próxima seção, vamos nos concentrar nas partes relevantes para a integração com a Transloadit.

Criação de upload

O primeiro passo é criar um recurso de upload no servidor tus enviando uma requisição POST ao endpoint especificado por tus_url. Metadados específicos devem ser incluídos para associar o upload à Assembly criada anteriormente. Ao todo, três valores devem estar presentes nos metadados:

assembly_url: a Assembly URL obtida da propriedade assembly_ssl_url no Assembly Status na primeira etapa
filename: o nome do arquivo
fieldname: o equivalente aos nomes dos campos de entrada em formulários HTML

Quaisquer metadados adicionais se tornarão uma Assembly Variable em file.user_meta. Você pode usar isso para executar ações dinamicamente no seu Template por arquivo, como alternativa a fields, que é compartilhado por todos os arquivos de uma Assembly. Se precisar definir caminhos diferentes com base no conteúdo detectado, prefira ${file.mime} e faça a correspondência com famílias MIME como image/*, video/* ou audio/*. ${file.type} também está disponível como uma categoria ampla de arquivo na resposta de Assembly Status. Seu valor é um dos seguintes: "audio", "document", "image", "office", "pdf", "swf", "video", "xls" ou null quando nenhuma categoria foi detectada. Os consumidores devem aceitar outros valores de string para manter a compatibilidade com categorias futuras. A correspondência por MIME costuma ser a verificação mais precisa.

Na requisição de exemplo abaixo, estamos enviando um arquivo chamado isaac.png, com tamanho de 10.000 bytes, para a Assembly com ID b841ea401e1a11e7b37d7bda1b503cdd e nome de campo file-input. Os detalhes exatos da codificação dos metadados usando Base64 estão descritos na especificação do 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==

Para uma requisição correta, o servidor cria um recurso de upload e retorna sua URL de upload no cabeçalho Location. Por exemplo:

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

Transferência de dados

Após a criação do upload, o cliente deve enviar o conteúdo do arquivo para a URL de upload tus, usando uma requisição 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]

Quando um upload tus é concluído, a Transloadit o processa automaticamente usando os parâmetros que você usou para criar a Assembly, sem exigir nenhuma ação especial da sua parte. Até que todos os uploads tus sejam concluídos, a Assembly permanecerá no estado ASSEMBLY_UPLOADING, mesmo que alguns dos arquivos já tenham sido processados.

Esses passos são repetidos para cada arquivo que o cliente quer enviar. O cliente pode escolher livremente enviar esses arquivos em paralelo ou em sequência, dependendo das necessidades da aplicação.

A contagem esperada de uploads informa à Assembly quantos arquivos devem concluir o upload; ela não é um limite estrito para o número de recursos de upload tus que podem ser criados. Recursos extras são tolerados enquanto a Assembly está no estado de upload, para que um cliente possa se recuperar caso uma resposta de criação de upload tenha sido perdida. Os contadores de progresso consideram a quantidade esperada de uploads, selecionando os que têm maior progresso e excluindo recursos abandonados. Envie apenas os arquivos pretendidos e reutilize cada URL de upload conhecida ao retomar. Assim que a Assembly sai de ASSEMBLY_UPLOADING, a criação de novos uploads é rejeitada.

Retomada

Se a transferência de dados falhar porque a rede foi interrompida ou o usuário pausou o upload, o cliente poderá retomar o upload do ponto em que parou.

Primeiro, o cliente envia uma requisição HEAD à URL de upload para determinar quantos dados o servidor conseguiu receber antes da interrupção:

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

A resposta inclui o número de bytes recebidos no cabeçalho Upload-Offset. Por exemplo, a resposta a seguir mostra um upload em que 3.000 de 10.000 bytes foram recebidos:

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

Os 7.000 bytes restantes podem então ser enviados usando outra requisição 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]

Mais informações sobre uploads retomáveis com tus estão disponíveis nas perguntas frequentes sobre tus.