Principais pontos
- Use
/upload/handleseguido de/tus/storepara retransmitir um arquivo enviado, sem alterações, a um endpoint compatível com tus. - Execute
/image/optimizeantes de/tus/storequando o sistema receptor precisar receber uma imagem otimizada. - Execute
/video/encodecom uma predefinição testada antes de/tus/storequando o destino precisar receber uma versão para reprodução.
O tus é um protocolo de upload retomável, não um produto de armazenamento de objetos. Nesses fluxos de trabalho, um cliente primeiro faz upload para uma Assembly da Transloadit, Steps opcionais de imagem ou vídeo criam a saída desejada e /tus/store inicia um upload tus de saída separado para o endpoint de destino configurado. Essa distinção é importante para credenciais, novas tentativas, URLs de resultado e reconciliação da aplicação.
O que mais importa
- Armazene os cabeçalhos de autorização do destino em Credenciais de Template do tipo HTTP, e não em Instructions visíveis no navegador.
- Reconcilie a Assembly e a aplicação receptora antes de marcar um ativo como pronto no estado do produto.
Modele o tus como uma fronteira de entrega
Um upload para a Transloadit e uma exportação com /tus/store são duas transferências distintas. A primeira traz os bytes do cliente para uma Assembly. A Assembly pode manter o arquivo inalterado ou criar um derivado de imagem ou vídeo. A segunda transferência envia o resultado selecionado da Transloadit para o seu endpoint tus. Essa arquitetura é útil quando a plataforma receptora já expõe tus, mas você ainda quer um processamento gerenciado antes da entrega.
O destino é responsável por tudo o que acontece após a conclusão do protocolo. A aplicação do destino decide se vai mover o upload para um armazenamento durável, criar um registro de ativo, escaneá-lo, publicá-lo ou rejeitá-lo mais tarde. Registre tanto o Assembly ID quanto a identidade estável do receptor. Não presuma que a URL de upload tus seja um identificador permanente de objeto ou uma URL de entrega legível, a menos que o receptor garanta explicitamente esse contrato.
Transferência de entrada
Cliente → Assembly da Transloadit, usando o método de upload selecionado pelo SDK ou pela integração.
Transferência de saída
Resultado da Assembly → /tus/store → o endpoint de destino configurado e compatível com tus.
Fronteira de durabilidade
A persistência e a publicação no lado do receptor permanecem fora do protocolo tus e do fluxo de trabalho da Transloadit.
Retransmita um arquivo enviado sem transformá-lo
Use o Template somente de upload quando o destino precisar receber o arquivo original aceito pela Assembly. /upload/handle expõe essa entrada como :original, e /tus/store a seleciona por meio de use. O parâmetro obrigatório endpoint deve ser a URL do destino que cria uploads tus, não a URL de um objeto existente nem uma página de download no navegador.
O exemplo faz referência a Credenciais de Template HTTP para cabeçalhos estáticos de destino. Mantenha allow_steps_override como false quando os clientes não puderem substituir o endpoint, remover a autenticação ou redirecionar um arquivo. Se o receptor precisar de contexto de tenant ou de ativo, prefira metadados não secretos com um endpoint autorizado pelo servidor ou uma credencial com escopo definido, e valide esse contexto novamente no lado receptor.
{
"allow_steps_override": false,
"steps": {
":original": { "robot": "/upload/handle" },
"delivered": {
"use": ":original",
"robot": "/tus/store",
"endpoint": "https://uploads.example.com/files/",
"credentials": "my_tus_http_credentials"
}
}
}Otimize uma imagem antes da entrega via tus
Para um contrato somente de imagens, conecte /image/optimize a :original e entregue o Step optimized. O exemplo preserva os metadados e usa otimização de PNG sem perdas (lossy: false); essa flag não afeta a otimização de JPEG, GIF, WebP ou SVG. Avalie se a remoção de metadados ou a otimização de PNG com perdas é adequada antes de alterar essas configurações, pois qualquer uma delas pode alterar informações que a aplicação receptora espera. O priority: "compression-ratio" não padrão do exemplo favorece uma saída menor em detrimento da velocidade de processamento; conversion-speed, o padrão, faz a escolha oposta.
Esta receita não redimensiona a imagem nem altera o formato. Adicione /image/resize antes da otimização quando o receptor exigir dimensões fixas ou um formato específico. Armazene ou entregue o original separadamente quando a recuperação e um futuro reprocessamento forem importantes. Um tipo de imagem não suportado pode passar por /image/optimize sem alterações, então use validação explícita quando o receptor exigir um formato restrito.
{
"allow_steps_override": false,
"steps": {
":original": { "robot": "/upload/handle" },
"optimized": {
"use": ":original",
"robot": "/image/optimize",
"priority": "compression-ratio",
"preserve_meta_data": true,
"lossy": false
},
"delivered": {
"use": "optimized",
"robot": "/tus/store",
"endpoint": "https://uploads.example.com/files/",
"credentials": "my_tus_http_credentials"
}
}
}Codifique um vídeo antes da entrega via tus
Para um contrato somente de vídeo, conecte /video/encode ao upload e forneça a /tus/store o Step codificado. web/mp4/720p é um ponto de partida concreto de MP4 qualificado por resolução, não uma recomendação universal de predefinição. Teste as dimensões de origem, a taxa de quadros, o áudio, as legendas, a compatibilidade de reprodução, o tempo de processamento e o custo em relação aos requisitos reais do receptor.
A codificação de vídeo e a transferência tus de saída podem durar mais que uma requisição da aplicação. Use o Assembly Status ou um callback de conclusão verificado e, em seguida, confira o próprio estado de conclusão da aplicação receptora. Armazene ou repasse a origem separadamente quando ela for necessária para uma recodificação de maior qualidade, auditoria, recuperação ou migração.
{
"allow_steps_override": false,
"steps": {
":original": { "robot": "/upload/handle" },
"encoded": {
"use": ":original",
"robot": "/video/encode",
"preset": "web/mp4/720p"
},
"delivered": {
"use": "encoded",
"robot": "/tus/store",
"endpoint": "https://uploads.example.com/files/",
"credentials": "my_tus_http_credentials"
}
}
}Escolha cabeçalhos, metadados e URLs informadas de forma deliberada
Use Credenciais de Template HTTP para cabeçalhos de autorização estáticos. O Robot também aceita headers dinâmicos, mas assinar as Instructions garante apenas a integridade delas, nunca a confidencialidade: um navegador pode ler tudo o que envia. Portanto, segredos dinâmicos nunca devem aparecer em Instructions visíveis no navegador. Mantenha-os em Credenciais de Template ou envie a Assembly de servidor para servidor, para que os valores nunca cheguem ao navegador. Os metadados de destino são um mapa separado: o Robot substitui os valores de filename, basename e extension fornecidos pelo chamador por informações do arquivo processado, enquanto as demais chaves passam conforme foram escritas. Mantenha os metadados pequenos, não secretos e alinhados aos campos que o receptor de fato valida, em vez de tratá-los como autorização.
Sem um url_template, o Robot informa a URL de upload retornada pelo destino. Um ssl_url_template omitido pode reutilizar essa URL somente quando ela começa com HTTPS. Os modelos alteram a apresentação do resultado; eles não alteram as permissões do receptor, não transformam uma URL de upload em um endpoint de download nem garantem estabilidade de longo prazo. Registre o identificador canônico do ativo no receptor depois que ele processar o upload.
Teste novas tentativas e reconcilie ambos os sistemas
Teste cenários de autorização expirada, rejeição pelo endpoint, transferências interrompidas, novas tentativas, entregas duplicadas, timeouts do receptor e falhas de processamento no lado receptor. Torne o tratamento de conclusão idempotente, pois uma notificação da Assembly ou um evento downstream pode ser entregue mais de uma vez. O sistema receptor deve rejeitar contexto entre tenants mesmo quando um cliente tiver conseguido alterar metadados não secretos.
Registre o Assembly ID, a classe do endpoint de destino e o ID do ativo no receptor sem registrar os cabeçalhos de autorização. A janela de aproximadamente 24 horas se aplica somente à cópia temporária do resultado da Assembly mantida pela Transloadit, portanto reconcilie o sistema receptor antes que essa cópia expire. Considere o ativo do produto pronto somente depois que o resultado esperado da Assembly tiver sido entregue e o receptor confirmar o estado durável ou publicado pretendido. É essa reconciliação explícita que transforma uma transferência bem-sucedida no nível do protocolo em um fluxo de trabalho de aplicação confiável.
Detalhes técnicos que vale a pena conhecer
/tus/storeexporta os arquivos selecionados porusepara a URL obrigatória informada no seu parâmetroendpoint.- O Robot aceita Credenciais de Template HTTP, para que cabeçalhos de autorização estáticos possam ser enviados ao destino sem aparecer nas Instructions.
- Os
headersdinâmicos opcionais são enviados ao destino, mas segredos visíveis no navegador continuariam expostos e devem ser evitados. - O Robot sempre define as chaves de metadados
filename,basenameeextensiona partir do arquivo processado, substituindo os valores fornecidos pelo chamador para essas chaves; as demais chaves demetadatapassam conforme foram escritas. - Quando
url_templateestá ausente, o resultado usa a URL de upload fornecida pelo servidor tus de destino. - Quando
ssl_url_templateestá ausente, a URL de upload do destino preenche o campossl_urldo resultado somente quando essa URL começa com HTTPS. /image/optimizedeixa passar tipos de imagem não suportados sem alterações, então valide as entradas quando o destino exigir um resultado otimizado./video/encodeaceita predefinições comoweb/mp4/720p, e cada predefinição deve ser testada em relação aos requisitos de reprodução do destino.- Os resultados temporários normalmente são mantidos por 24 horas. Selecionar “Não salvar” pode impedir que novos resultados sejam armazenados, mas não exclui imediatamente os objetos existentes no R2. Os arquivos já armazenados no R2 continuam sujeitos ao ciclo de vida mínimo de 24 horas do R2. A retenção durável cabe ao destino tus receptor.
Uma abordagem prática
- 1
Confirme que o destino implementa o protocolo tus e defina o que ele faz após um upload concluído.
- 2
Crie Credenciais de Template do tipo HTTP para os cabeçalhos estáticos do destino e salve Templates separados para upload, imagem e vídeo.
- 3
Teste a autenticação, a recuperação de transferências interrompidas, a entrega duplicada, o comportamento da URL de resultado e a persistência no lado do receptor.
- 4
Registre o Assembly ID junto com a identidade estável do ativo no sistema receptor e reconcilie a conclusão de forma idempotente.
Quando a Transloadit é útil
Use /tus/store quando um destino existente aceitar uploads tus e uma Assembly da Transloadit precisar entregar a ele um resultado original ou processado. Use um Robot de armazenamento específico do provedor quando a Transloadit precisar entender uma API de bucket e configurações de acesso específicas do armazenamento.
Limite da arquitetura
/tus/store repassa um resultado selecionado da Assembly a um endpoint compatível com tus. O tus define a transferência retomável, não a durabilidade do destino, o modelo de autorização, a retenção, o estado de publicação nem a URL final de download; o serviço receptor e a sua aplicação são responsáveis por esses contratos.
Perguntas frequentes
O navegador faz upload diretamente para o meu endpoint tus?
Não. Nestas receitas, o navegador faz upload para uma Assembly da Transloadit. Após o processamento, /tus/store atua como cliente tus e faz upload do resultado selecionado para o endpoint que você configurou. As duas transferências têm URLs, credenciais, progresso e limites de novas tentativas separados.
Um upload tus bem-sucedido garante armazenamento durável?
Não. O tus padroniza a transferência retomável. O servidor receptor decide se o upload concluído é durável, por quanto tempo ele é retido, quem pode acessá-lo e se a URL de upload também é uma URL de download. Reconcilie um registro de ativo no lado do receptor em vez de inferir essas propriedades a partir da conclusão do protocolo.
Como o destino deve autenticar a Transloadit?
Use o tipo de credencial HTTP para cabeçalhos de autorização estáticos e referencie o nome da credencial em /tus/store. O uso dinâmico de headers é suportado nos casos que não podem usar credenciais estáticas, mas nunca coloque cabeçalhos sensíveis em Assembly Instructions visíveis no navegador.
Um único Template pode lidar com arquivos, imagens e vídeos?
Use Templates separados quando as políticas de validação e de falha forem diferentes. Um Template deliberadamente misto pode filtrar e ramificar pelo tipo de mídia observado e, então, entregar a cada Step /tus/store apenas o resultado criado pelo seu ramo.
Qual URL aparece no resultado da Assembly?
Por padrão, o Robot usa a URL de upload retornada pelo servidor tus. url_template e ssl_url_template podem ajustar as URLs informadas, mas não comprovam que a URL é publicamente legível nem que permanece estável. Verifique o contrato de URL do receptor de forma independente.