O que são Assembly Instructions?
As Assembly Instructions da Transloadit definem os Steps nomeados em um fluxo de trabalho de processamento de arquivos. Cada Step seleciona um Robot e seus parâmetros; o parâmetro use determina como os arquivos enviados, importados ou gerados fluem entre os Steps.
Como funcionam as Assembly Instructions
As Instructions formam um grafo de processamento direcionado e acíclico, expresso por configurações de Steps nomeados e suas relações de entrada. Cada Step seleciona um Robot e parâmetros, enquanto use determina quais uploads ou resultados anteriores entram nele. Os Steps que importam ou geram arquivos podem omitir use quando não dependem de um Step anterior. Os demais Steps que omitem use são conectados implicitamente à saída do Step anterior; o primeiro Step declarado usa :original por padrão. Declare use explicitamente quando a ordem dos Steps não deva determinar o grafo. O nome reservado de Step :original se refere aos arquivos enviados por upload. Um Step declarado com esse nome só pode executar o Robot /upload/handle, e nenhum outro Step pode executar esse Robot; um valor de use pode fazer referência a :original sem declará-lo como um Step. O documento de Instructions é distinto de uma Assembly, que é uma execução do grafo, e de um Template, que armazena Instructions de forma persistente para reutilização. Antes de iniciar o processamento de mídia, a Transloadit valida se cada Step é um objeto bem formado que nomeia um Robot existente, se todas as referências declaradas em use são resolvidas e se o grafo não contém ciclos.
Informações essenciais
- 1Os nomes dos Steps são identificadores do grafo. Se
usenomear um Step que não existe, a Transloadit rejeitará a Assembly com ASSEMBLY_STEP_UNKNOWN_USE (HTTP 400) antes do início do processamento. - 2Os resultados de um Step podem alimentar vários Steps posteriores, então cada arquivo derivado não precisa de seu próprio upload ou importação. Esses Steps são executados em paralelo assim que o Step de entrada emite arquivos, portanto, com valores explícitos de
use, a ordem em que os Steps são declarados não define a ordem em que os resultados são produzidos ou exportados. A ordem de declaração só importa quando um Step omiteusee é conectado implicitamente ao Step anterior. - 3Um Template mantém a lógica reutilizável do fluxo de trabalho fora das requisições dos clientes. Por padrão, os clientes podem sobrescrever Steps; defina
allow_steps_overridecomo false no Template, e as requisições que ainda fornecerem Steps serão rejeitadas com TEMPLATE_DENIES_STEPS_OVERRIDE (HTTP 400). A configuração abrange apenas Steps: os demais parâmetros da requisição continuam sendo mesclados sobre o Template. Para impedir que chamadores não confiáveis os alterem, exija Signature Authentication (a configuração do Workspace ourequire_signature_authno Template) e faça com que um back-end confiável assine apenas os parâmetros que ele aprovar. A exigência se aplica a requisições autenticadas com uma Auth Key; tokens bearer válidos a dispensam. Uma assinatura cobre apenas o conteúdo serializado deparams. Os campos do formulário de upload enviados junto com esse conteúdo não são assinados, preenchem${fields.*}e têm precedência sobre valores de mesmo nome na chave assinadafields, de modo que um Template bloqueado que construa um caminho de armazenamento ou outra configuração a partir de${fields.*}ainda permite que o chamador escolha esse valor. - 4Um Step que não produz nada não necessariamente falhou. Por padrão, um Robot ignora tipos de arquivo que não processa (o exemplo da documentação é
/video/encodeignorando imagens), de modo que uma ramificação pode simplesmente não produzir nada para esses arquivos. Use/file/filterpara direcionar deliberadamente uploads de tipos variados; a documentação reservaforce_acceptpara depuração e casos extremos.
Quando as Assembly Instructions são importantes
Salve Instructions em um Template quando os chamadores precisarem reutilizar um fluxo de trabalho gerenciado pelo servidor. Se os chamadores não puderem alterar os Steps desse Template, defina allow_steps_override como false; para impedir que também alterem outros parâmetros da requisição, exija Signature Authentication para requisições feitas com sua Auth Key. Nenhum dos dois controles abrange os campos do formulário de upload, portanto não use ${fields.*} para derivar uma configuração cujo valor os chamadores não devam escolher. Ao gerar Instructions ou renomear Steps, verifique se cada valor de use faz referência ao nome de um Step declarado ou a :original para que a Assembly passe na validação.
Como a Transloadit ajuda com Assembly Instructions
A Transloadit valida e executa Assembly Instructions como o fluxo de trabalho de uma Assembly. Cada Step nomeado invoca um Robot para fazer upload, importar, processar, analisar, armazenar ou servir arquivos, e o parâmetro use direciona os resultados entre Steps. Um Template armazena Instructions para reutilização, uma Assembly é uma execução dessas Instructions, e o Assembly Status e as Notifications informam o resultado.
Fontes
- Documentação da Transloadit: Assembly Instructions (parâmetros dos Steps, ordem de execução)
- Documentação da Transloadit: uso avançado do parâmetro use
- Documentação da Transloadit: Templates (sobrescrever Templates em tempo de execução)
- API da Transloadit: códigos de resposta (erros de validação de Steps e Templates)
- Robot da Transloadit: /upload/handle (restrições do Step :original)
- API da Transloadit: criar um novo Template (allow_steps_override, require_signature_auth)
- API da Transloadit: autenticação (Signature Authentication, tokens bearer)
- Robot da Transloadit: /file/filter (Steps condicionais)
- Documentação da Transloadit: Assembly Variables (campos de formulário e a chave fields)
- Perguntas frequentes da Transloadit: como posso garantir que uma imagem realmente veio do usuário correto da minha aplicação? (o que uma assinatura cobre)