O que é uma Assembly?

Uma Assembly da Transloadit é uma execução de Assembly Instructions em arquivos que são enviados, importados ou gerados pelo próprio fluxo de trabalho. Cada execução tem um assembly_id único que a identifica em solicitações posteriores à API.

Como as Assemblies funcionam

Uma Assembly é o fluxo de trabalho em tempo de execução criado quando uma requisição combina Assembly Instructions com fontes de entrada: arquivos enviados por upload, arquivos obtidos por Steps de importação ou arquivos que um Robot cria por conta própria, como uma captura de tela de um site ou uma imagem gerada a partir de um prompt de texto. As Instructions chegam diretamente como steps ou por referência a um Template salvo por meio de template_id; o Template armazena a configuração, enquanto a Assembly é uma execução específica dessa configuração. Os Steps começam assim que os Steps dos quais dependem emitem arquivos, então um arquivo de origem pode alimentar várias ramificações que são executadas em paralelo. A Transloadit informa o andamento da execução por meio de um único documento de Assembly Status, que é retornado quando a Assembly é criada, disponibilizado na URL de status e enviado para notify_url, se estiver definido. Esse documento muda enquanto a Assembly recebe uploads ou está em execução; quando a execução atinge um estado terminal, ele contém ok com o estado final ou error com um código de erro.

Informações essenciais

Uma resposta HTTP de sucesso à requisição de criação significa que a Assembly foi aceita, não que o processamento foi bem-sucedido. A Assembly ainda está em execução enquanto ok é ASSEMBLY_UPLOADING, ASSEMBLY_EXECUTING ou ASSEMBLY_REPLAYING; somente ASSEMBLY_COMPLETED significa sucesso. ASSEMBLY_CANCELED e REQUEST_ABORTED também aparecem em ok sem indicar sucesso, e uma requisição de status pode retornar HTTP 200 enquanto o corpo contém error, então baseie a lógica no corpo, não no status HTTP.
O assembly_id funciona como uma autorização de acesso: qualquer pessoa que o conheça pode solicitar o Assembly Status, incluindo os campos enviados e os resultados, sem autenticação adicional. Mantenha o ID e as URLs de status fora de páginas públicas e de qualquer conteúdo compartilhado com partes não confiáveis. A opção quiet apenas reduz a resposta de criação; ela não restringe quem pode ler o status depois.
Criar uma Assembly não é uma operação idempotente. Repetir a requisição de criação, por exemplo após um tempo limite ser excedido, pode iniciar uma segunda Assembly com seu próprio assembly_id, e adicionar um nonce de assinatura não impede isso. Elimine novas tentativas duplicadas na sua aplicação.
Os arquivos de resultado são agrupados pelo nome do Step que os produziu, não pela ordem dos uploads, e um upload pode gerar vários resultados; associe-os aos uploads por meio de original_id. Os Steps que apenas armazenam arquivos não adicionam nenhuma entrada, e os resultados podem estar parciais após um erro. As URLs dos resultados no armazenamento temporário da Transloadit expiram, então adicione um Step de exportação quando os arquivos precisarem ser mantidos.

Quando as Assemblies são importantes

Armazene o assembly_id no seu servidor quando um fluxo de trabalho precisar consultar o status periodicamente, coletar resultados ou associar uma Notification recebida à requisição que a originou, e trate-o como um segredo, pois o ID por si só é suficiente para ler o Assembly Status. Decida antes de colocar a aplicação em produção como ela saberá o resultado, consultando periodicamente a URL de status ou definindo notify_url, pois a resposta à requisição de criação apenas confirma que a Assembly foi aceita.

O que é uma Assembly?

Como as Assemblies funcionam

Informações essenciais

Quando as Assemblies são importantes

Fontes

Transforme conhecimento sobre mídia em um pipeline funcional