Transloadit

Assembly Instructions

Para conhecer as Assembly Instructions, vamos ver este exemplo:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "imported_watermark": {
      "robot": "/http/import",
      "url": "https://transloadit.com/assets/images/face.jpg"
    },
    "resized": {
      "robot": "/image/resize",
      "use": {
        "steps": [
          { "name": ":original", "as": "base" },
          { "name": "imported_watermark", "as": "watermark" }
        ]
      },
      "width": 400,
      "height": 400,
      "watermark_position": "center",
      "watermark_size": "30%"
    },
    "exported": {
      "robot": "/s3/store",
      "use": [":original", "resized"],
      "credentials": "my_cloud_storage_credentials",
      "path": "/my_images/${file.id}/${file.url_name}"
    }
  }
}

O exemplo mostra quatro Steps: :original, imported_watermark, resized e exported. Você pode dar aos seus Steps o nome que quiser, com exceção de :original, que se refere aos arquivos enviados por upload e precisa usar o Robot 🤖/upload/handle.

Note como os Steps :original e imported_watermark são usados como entrada do Step resized por meio do parâmetro use. Usamos aqui o agrupamento de Steps por meio da sintaxe “as” para passar vários arquivos ao Step resized ao mesmo tempo: uma entrada serve como imagem base e a outra como marca-d’água a ser impressa sobre a imagem base. Robots diferentes oferecem possibilidades diferentes para a sintaxe “as”, o que torna tudo muito poderoso!

O Step exported então apenas usa a maior parte dos outros Steps como entrada e os armazena no S3, um por um, sem agrupamento de Steps. As variáveis usadas, ${file.id} e ${file.url_name}, estão disponíveis para todos os Steps e podem ser usadas para criar nomes de arquivo únicos para cada arquivo.

Dessa forma, conseguiremos lidar com os arquivos enviados por upload, aplicar uma marca-d’água neles e exportar para o S3 tanto a imagem enviada quanto a versão redimensionada e com marca-d’água.

Nem todos os Steps exigem entradas. Nosso Step imported_watermark, por exemplo, fornece a primeira entrada baixando-a, e é por isso que ali omitimos use. Outros exemplos de Robots que não exigem arquivos de entrada são o 🤖/html/convert, que pode tirar uma captura de tela de um site e criar o primeiro arquivo dessa forma, ou o 🤖/upload/handle, que obtém seus arquivos dos visitantes do seu app, em vez de obtê-los de outro Step.

Com uma única mudança simples, poderíamos tornar este app realmente dinâmico. Imagine substituir a URL estática no Step imported_watermark por uma dinâmica, vinda de um campo do seu app. Basta alterar o parâmetro "url" para "${fields.watermark_url}" no nosso Template e depois fornecer esse campo de entrada no nosso formulário web HTML (ou por meio de um campo POST adicional na nossa requisição) para tornar a aplicação da marca-d’água realmente dinâmica!

Parâmetros de Step

Como você pode ver, cada Step é definido como um objeto com algumas propriedades, ou parâmetros. A maioria delas é, na verdade, parâmetros de Robot, pois determinam, por exemplo, o width de uma imagem após um redimensionamento. Todos eles estão documentados na respectiva documentação dos Robots. Existem, porém, também 5 parâmetros que instruem o próprio motor de Assembly, definindo quais Robots são invocados e como eles se interconectam:

  • use

    string | Array<string> | Array<object> | object

    Especifica quais Steps usar como entrada.

    • Você pode escolher qualquer nome para os Steps, exceto ":original" (reservado para uploads de usuários tratados pela Transloadit)
    • Você pode fornecer vários Steps como entrada usando arrays: 
      {
  "use": [
    ":original",
    "encoded",
    "resized"
  ]
}
    • Você também pode marcar os Steps de entrada com as para transmitir intenção semântica aos Robots: 
      {
  "use": [
    {
      "name": ":original",
      "as": "image"
    },
    {
      "name": ":original",
      "as": "mask"
    }
  ]
}

  • robot — obrigatório

    string

    Especifica qual Robot deve processar os arquivos passados para este Step.

    Veja todos os Robots, cada um com seus próprios parâmetros, como width para controlar como uma imagem é redimensionada. A lista completa de parâmetros de cada Robot pode ser consultada na documentação do Robot.

  • result

    boolean(padrão: false)

    Se os resultados deste Step devem estar presentes no Assembly Status JSON

  • force_accept

    boolean(padrão: false)

    Forçar um Robot a aceitar um tipo de arquivo que ele teria ignorado.

    Por padrão, os Robots ignoram arquivos que não conhecem. O 🤖/video/encode, por exemplo, ignora tranquilamente imagens de entrada.

    Com o parâmetro force_accept definido como true, você pode forçar os Robots a aceitar todos os arquivos enviados a eles. Isso normalmente leva a erros e só deve ser usado para depuração ou para lidar com casos extremos.

  • ignore_errors

    boolean | Array<meta | execute>(padrão: [])

    Ignorar erros durante fases específicas do processamento.

    Definir isso como ["meta"] fará com que o Robot ignore erros durante a extração de metadados.

    Definir isso como ["execute"] fará com que o Robot ignore erros durante a fase principal de execução.

    Definir isso como true equivale a ["meta", "execute"] e fará com que erros sejam ignorados nas duas fases.

Para orientações práticas e combinações de valores (incluindo o comportamento específico de importação), consulte O parâmetro ignore_errors.

Ordem de execução

Para acelerar as Assemblies, os Steps são executados assim que os Steps de entrada deles emitem arquivos. Em outras palavras, muitas coisas são processadas em paralelo. Por exemplo, digamos que você queira codificar um vídeo enviado por upload e também extrair miniaturas dele:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "encoded": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "web/mp4/1080p"
    },
    "thumbed": {
      "use": ":original",
      "robot": "/video/thumbs",
      "count": 4
    },
    "exported": {
      "use": ["encoded", "thumbed"],
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS"
    }
  }
}

Ambos os Steps, encoded e thumbed, serão executados em paralelo assim que o primeiro upload de arquivo for concluído. O Step exported é acionado para cada um dos arquivos vindos de encoded e thumbed. É provável que as miniaturas cheguem ao seu bucket S3 antes do vídeo codificado, mesmo que as miniaturas tenham sido definidas depois. Portanto, a ordem dos Steps não importa muito. O parâmetro use define a entrada de cada Step e é isso que, em última instância, determina como nossos Steps são encadeados.

Filtragem para tornar os Steps condicionais

Com o 🤖/file/filter, você pode executar Steps com base nas propriedades de um arquivo. Isso permite criar Assembly Instructions que: atendem tanto a uploads de vídeo quanto de áudio, rejeitam arquivos pequenos demais, aplicam um efeito apenas em imagens que têm áreas transparentes, etc. Essas e outras possibilidades também são abordadas na documentação do Robot.

Assembly Variables

Para informações sobre Assembly Variables como ${file.id}, ${assembly.id}, ${fields.*} e outras, consulte a página dedicada Assembly Variables.