Fluxos de trabalho personalizáveis de processamento de mídia com a Transloadit

Um fluxo de trabalho personalizável deve expor os poucos valores que legitimamente mudam a cada tarefa, mantendo o grafo de processamento sob controle. As Assembly Instructions da Transloadit expressam esse grafo como Steps nomeados, e um Template salvo permite que uma aplicação o execute repetidamente sem reenviar credenciais de armazenamento nem a política de transformação.

O que mais importa

• Referencie credenciais de Template armazenadas em vez de colocar segredos de nuvem nas Assembly Instructions.
• Registre o Template ID, o rótulo do fluxo de trabalho da aplicação, o Assembly ID, as entradas e o resultado final de cada execução.

{
  "allow_steps_override": false,
  "auth": {
    "max_number_of_files": 1,
    "max_size": 52428800
  },
  "notify_url": "https://app.example.com/webhooks/transloadit",
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "accepted_images": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        ["${file.mime}", "regex", "^(image/jpeg|image/png|image/webp|image/avif)$"]
      ],
      "error_on_decline": true,
      "error_msg": "Upload a JPEG, PNG, WebP, or AVIF image."
    },
    "web_image": {
      "use": "accepted_images",
      "robot": "/image/resize",
      "width": 1600,
      "height": 1200,
      "resize_strategy": "fit",
      "format": "webp"
    },
    "thumbnail": {
      "use": "accepted_images",
      "robot": "/image/resize",
      "width": 320,
      "height": 320,
      "resize_strategy": "fillcrop",
      "format": "webp"
    },
    "export_web": {
      "use": "web_image",
      "robot": "/s3/store",
      "acl": "private",
      "credentials": "media-output",
      "path": "${fields.tenant_id}/${assembly.id}/web/${unique_prefix}/${file.url_name}"
    },
    "export_thumb": {
      "use": "thumbnail",
      "robot": "/s3/store",
      "acl": "private",
      "credentials": "media-output",
      "path": "${fields.tenant_id}/${assembly.id}/thumb/${unique_prefix}/${file.url_name}"
    }
  }
}

// Illustrative fragment: these objects come from your application, not the SDK.
const assembly = await transloadit.createAssembly({
  files: { image: inputPath },
  params: {
    template_id: process.env.TRANSLOADIT_TEMPLATE_ID,
    fields: {
      tenant_id: tenant.id,
    },
  },
})

await jobs.attachAssembly({
  jobId: job.id,
  assemblyId: assembly.assembly_id,
})

Detalhes técnicos que vale a pena conhecer

• Um Step por arquivo começa assim que um Step anterior indicado no seu valor use emite um arquivo; apenas Robots de mesclagem ou agrupamento esperam por um conjunto completo de entradas indicadas. A posição de um Step no objeto JSON não determina a ordem de execução.
• Assembly Variables como ${fields.tenant_id}, ${assembly.id} e ${file.url_name} (uma versão segura para URL, em formato slug, do nome do arquivo do Step atual, incluindo a extensão) são resolvidas em tempo de execução e podem parametrizar dimensões, caminhos e outros valores de Robots. Nos caminhos de exportação de exemplo, ${assembly.id} garante unicidade por execução, e ${unique_prefix}, que contém barras, mantém distintos os arquivos dentro de uma mesma execução.
• Definir allow_steps_override como false em um Template salvo impede que os chamadores mesclem Steps substitutos nesse Template. Os campos de tempo de execução ainda precisam de validação e autorização no lado da aplicação.
• /file/filter pode comparar propriedades de arquivo detectadas pelo servidor com condições em array. Uma lista de permissões específica de tipos MIME é mais segura do que confiar na extensão do nome do arquivo ou no tipo informado pelo cliente.
• As credenciais de Template mantêm os segredos de destino separados do JSON do Template e podem ser atualizadas sem que seja preciso copiar chaves para cada integração.
• As Assembly Notifications são reenviadas quando o receptor não retorna um código de status HTTP 2xx. Os consumidores devem verificar a assinatura e tolerar entregas duplicadas, atrasadas ou fora de ordem.

Uma abordagem prática

Quando a Transloadit é útil

Use um Template salvo para conectar /upload/handle, /file/filter, Steps /image/resize paralelos e /s3/store. Bloqueie o grafo de processamento definindo allow_steps_override como false, passe campos delimitados em tempo de execução e reconcilie a conclusão por meio do Assembly Status e de webhooks verificados.

Limite da arquitetura

Os Assembly Templates descrevem o processamento e a movimentação de arquivos. Eles não são responsáveis por aprovações de produto, autorização de tenants, estado de negócio ou histórico de configuração de uma aplicação; mantenha essas decisões no sistema que inicia e registra cada tarefa.