Templates

Um Template é uma receita que define como processar os arquivos recebidos.

Você pode nos enviar suas Assembly Instructions diretamente em cada requisição, ou pode salvá-las em um Template e referenciar o template_id dele nas suas requisições.

Builtin Templates

A Transloadit também oferece Templates que são mantidos e versionados por nós. Esses Builtin Templates são úteis como pontos de partida estáveis e prontos para uso em transformações comuns.

Veja Builtin Templates para conhecer os builtins disponíveis e como listá-los pela API.

Enviar as Instructions diretamente permite prototipar rapidamente, mas salvá-las em um Template traz algumas vantagens:

1. Você evita transmitir dados sensíveis e detalhes de implementação a cada requisição de codificação. Isso é especialmente interessante quando você faz a integração com navegadores.
2. Em conjunto com "allow_steps_override": false, as Instructions não podem ser adulteradas.
3. Em conjunto com Assembly Notifications, você pode habilitar Assembly Replays.
4. Se você integrou a Transloadit a um aplicativo, pode alterar as configurações de codificação sem fazer deploy ou esperar que uma App Store publique uma nova versão.

Como criar um Template

1. Crie um Template na sua conta.
2. Dê um nome ao seu Template para referência (humana) futura.
3. Forneça o JSON das Assembly Instructions do seu Template. Você pode selecionar exemplos de uma lista, deixar nosso Wizard gerar as Instructions, duplicar um Template existente ou começar do zero.
4. Clique em salvar.

Depois que o Template for salvo, uma página é exibida mostrando o Template que você criou. No topo da página, o ID do Template é exibido, por exemplo, 4b62ee4dbb38455d96fe13d972ec3211. Você pode então copiar e colar esse ID no template_id do código da sua integração, ou olhar mais abaixo no Template Editor, onde já mostramos exemplos incluindo esse ID.

Sobrescrevendo Templates em tempo de execução

Você pensaria que são mutuamente exclusivos, mas é possível fornecer tanto template_id quanto steps dentro de params, já que isso permite alterar o comportamento do Template em tempo de execução. Na verdade, qualquer outra propriedade dentro de params, com exceção de allow_steps_override, será mesclada recursivamente sobre o Template carregado via template_id.

Por exemplo, vamos dar uma olhada no Template a seguir, que trata um upload, codifica um vídeo para rodar bem em iPads e salva o resultado no S3:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "encoded": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "ipad-high"
    },
    "exported": {
      "use": "encoded",
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS",
      "bucket": "main-bucket"
    }
  }
}

Quando você cria uma Assembly, podemos ajustar o comportamento do Template em tempo de execução, por exemplo, adicionando uma propriedade steps:

{
  "template_id": "4b62ee4dbb38455d96fe13d972ec3211",
  "steps": {
    "exported": {
      "bucket": "another-bucket"
    }
  }
}

Isso então é mesclado pela Transloadit para criar as seguintes Assembly Instructions:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "encoded": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "ipad-high"
    },
    "exported": {
      "use": "encoded",
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS",
      "bucket": "another-bucket"
    }
  }
}

Como você pode ver, o valor de bucket mudou de "main-bucket" para "another-bucket". Isso pode ser conveniente e poderoso em ambientes confiáveis.

Em outros ambientes, você pode querer proibir a sobrescrita de Steps para que um navegador não consiga modificar o comportamento. Para isso, você definiria allow_steps_override como false dentro do Template salvo, assim:

{
  "allow_steps_override": false,
  "steps": {
    // …
  },
}

Agora, somente main-bucket será usado, tendo sido fornecidos steps adicionais ou não.

Opções do Template

Além de steps e allow_steps_override, há mais opções para controlar o comportamento de uma Assembly.

Como a maioria delas também pode ser definida sem usar Templates, elas estão documentadas na documentação da API para criar uma nova Assembly EN (English). No entanto, se você integrar a Transloadit em ambientes não confiáveis, como navegadores, um usuário mal-intencionado poderia alterá-las com facilidade. Portanto, para permitir a alteração dinâmica dos parâmetros de um Template em ambientes não confiáveis, considere usar a Signature Authentication EN (English).