Boas práticas

Aproveite ao máximo a Transloadit em termos de segurança, confiabilidade e desempenho.

Segurança

Use Templates

Templates permitem armazenar as Assembly Instructions do nosso lado, criptografadas em repouso. Depois, você referencia um Template por template_id na sua requisição à API. Isso é mais seguro do que enviar as instruções completas em cada requisição, especialmente se as suas instruções contiverem credenciais de terceiros.

Usar Templates também melhora a operabilidade:

Você pode alterar o comportamento do processamento sem reimplantar o seu app.
Você pode combinar Templates com Assembly Notifications e Assembly Replays.
Você ainda pode sobrescrever valores específicos em tempo de execução quando precisar.

Saiba mais:

Assine as requisições expostas ao navegador

Se as requisições puderem ser geradas no lado do cliente, presuma que a sua Auth Key pode ficar visível. Use Signature Authentication (English) e endpoints HTTPS (https://api2.transloadit.com).

Isso protege a integridade das requisições e ajuda a evitar o uso não autorizado.

Use credenciais com privilégio mínimo

Ao conceder acesso ao armazenamento (por exemplo, S3), limite as credenciais às ações e aos caminhos mínimos necessários. Por exemplo, credenciais de exportação somente para escrita costumam ser suficientes para o 🤖/s3/store (English).

Confiabilidade

Prefira o processamento assíncrono

Se os usuários precisam esperar o processamento completo antes de continuar, o tempo de fila afeta diretamente a UX.

Um padrão melhor:

Faça primeiro o upload ou a importação.
Deixe o processamento continuar de forma assíncrona.
Use Assembly Notifications para atualizar o seu backend quando a Assembly for concluída.

Isso mantém a sua UI responsiva e evita que os usuários fiquem esperando por conversões.

Saiba mais: Webhooks e notificações

Não dependa da ordem dos resultados

Não há garantia de que os arrays de resultados fiquem alinhados por posição entre os Steps. Se você precisa mapear os arquivos processados de volta aos originais, faça a correspondência pelos IDs:

uploads[*].id
results[*].original_id

Limite os arquivos de entrada por Assembly

Conjuntos de entrada muito grandes em uma única Assembly podem ter o efeito contrário:

Você pode exceder as suas vagas prioritárias de jobs disponíveis.
Você aumenta o risco de atingir o tempo máximo de execução de 8 horas da Assembly.

Como orientação prática, mantenha os arquivos de entrada enviados por upload e importados em torno de 500 a 1000 arquivos por Assembly, dependendo da quantidade de trabalho pela qual cada arquivo passa.

Use `ignore_errors` de forma intencional

O parâmetro de Step ignore_errors mantém uma Assembly em andamento quando certos erros por arquivo são aceitáveis, o que é útil para jobs em lote ou para a extração opcional de metadados. Ele também torna as falhas menos visíveis, então use-o deliberadamente:

Prefira arrays específicos como ["meta"] em vez de true, para que apenas as fases que você espera tolerar sejam ignoradas.
Monitore ignored_errors e ignored_error_count no Assembly Status, para que falhas silenciosas ainda sejam expostas à sua equipe.

Saiba mais: O parâmetro ignore_errors

Leia a documentação de cada Robot

As demos são um ótimo ponto de partida, mas o comportamento em produção muitas vezes depende de opções, casos extremos e limites documentados para cada Robot.

Antes de colocar em produção, valide o seu fluxo exato com a documentação dos Robots (English) correspondente.

Desempenho e custo

Entregue pelo Smart CDN

Se você entrega assets processados aos usuários finais, use o Transloadit Smart CDN.

Principais vantagens:

Menor latência com entrega pelos nós de borda.
Maior confiabilidade sob carga.
Menos reprocessamento e menos tráfego de origem graças ao cache.

Boas práticas:

Configure o comportamento de cache no 🤖/file/serve (English).
Prefira transformações baseadas em URL quando fizer sentido.
Mantenha as chaves de cache estáveis e explícitas.

Saiba mais: Entrega de conteúdo

Agrupe arquivos em menos Assemblies

Assemblies são mais pesadas do que operações individuais de arquivo. Agrupar arquivos em menos Assemblies pode melhorar o throughput e reduzir a sobrecarga, especialmente em importações grandes.

Para importações, mantenha o tamanho total do lote prático para retentativas e segurança operacional.

Mantenha os stacks de codificação atualizados

Nós mantemos stacks mais antigos disponíveis para preservar a compatibilidade retroativa, mas você deve atualizar periodicamente para stacks mais recentes a fim de obter correções, melhorias de desempenho e atualizações de codecs e ferramentas.

Revise as configurações de stack pelo menos uma vez por ano e faça testes antes de migrar o tráfego de produção.

Defina um limite de cobrança

Durante a integração, loops acidentais podem acontecer e gerar picos inesperados de uso. Um limite de cobrança é uma proteção útil.

Defina-o alto o suficiente para permitir o crescimento normal, mas baixo o suficiente para conter um comportamento descontrolado inesperado.