Parâmetro use avançado

Empacotamento de Steps

Alguns Robots conseguem reunir resultados de vários Steps em uma única invocação. Por exemplo, o 🤖/file/compress normalmente criaria um arquivo compactado para cada arquivo passado a ele. No entanto, se você definir bundle_steps como true, ele criará um único arquivo compactado contendo todos os arquivos de resultado de cada Step que você passar a ele.

Para habilitar o empacotamento, forneça ao parâmetro use um objeto como o abaixo:

"use": {
  "steps": [
    ":original",
    "encoded",
    "resized"
  ],
  "bundle_steps": true
}

Agrupar por original

O parâmetro group_by_original organiza os arquivos de saída pelo arquivo de entrada que os originou, o que o torna essencial em fluxos de trabalho nos quais você quer garantir que as saídas fiquem agrupadas com o arquivo de entrada que as produziu, por exemplo ao usar o Robot 🤖/file/compress. Nesse caso, você pode querer criar um arquivo compactado separado para cada arquivo enviado por upload ou importado, em vez de criar um que contenha todos os uploads originais (ou um por arquivo resultante).

Exemplo:

"compress": {
  "use": {
    "steps": ["thumbnails"],
    "bundle_steps": true,
    "group_by_original": true
  },
  "robot": "/file/compress"
}

Essa configuração indica que o Step compress deve considerar a saída do Step thumbnails, agregar essas saídas por arquivo original e, então, compactá-las de acordo.

Campos

Você pode filtrar e selecionar arquivos específicos com base nos nomes dos campos usando a configuração fields. Quando esse array é especificado, o Step correspondente será executado apenas para arquivos enviados por meio de um dos nomes de campo informados.

Os nomes dos campos devem corresponder aos nomes dados aos campos de entrada de arquivo no seu formulário HTML, conforme definido no atributo name da tag de input de arquivo. Ao usar um SDK de backend, ele corresponde a myFieldName1 em, por exemplo: $transloadit->addFile('myFieldName1', './chameleon.jpg').

Exemplo:

"use": {
  "steps": [":original"],
  "fields": ["myFieldName1"]
}

Esse parâmetro é definido como true por padrão, o que significa que todos os campos são aceitos.

Usar as

Às vezes, Robots recebem várias entradas. Por exemplo, o 🤖/video/merge pode criar uma apresentação de slides a partir de áudio e imagens. Você pode mapear diferentes Steps para as entradas adequadas especificando o tipo de arquivo como o qual o Step deve ser tratado.

"use": {
  "steps": [
    { "name": "audio_encoded", "as": "audio" },
    { "name": "images_resized", "as": "image" }
  ]
}

Ordenação de Steps

Às vezes, a ordem é importante. Por exemplo, com nossa família de Robots de concatenação, você pode querer especificar a ordem exata em que sua mídia será concatenada. Nesses casos, você pode adicionar um índice ao final do tipo de arquivo, começando em 1. Você também pode, opcionalmente, filtrar pelo nome do campo multipart. Como neste exemplo, em que todos os arquivos vêm da mesma origem (uploads de usuários finais), mas com nomes de <input> diferentes:

"use": {
  "steps": [
    { "name": ":original", "fields": "myFirstVideo", "as": "video_1" },
    { "name": ":original", "fields": "mySecondVideo", "as": "video_2" },
    { "name": ":original", "fields": "myThirdVideo", "as": "video_3" }
  ]
}

Quando não fica evidente onde colocar o arquivo, você pode usar Assembly Variables para ser específico. Por exemplo, você pode querer passar um arquivo de texto para o 🤖/image/resize para gravar o texto em uma imagem. Mas o que acontece se você estiver gravando várias marcas-d’água na imagem? Como apontar para o arquivo de texto que você quer usar? Você pode especificá-lo via ${use.text_1} para indicar o primeiro arquivo de texto que foi passado.

Exemplo:

"watermarked": {
  "robot": "/image/resize",
  "use": {
    "steps": [
      { "name": "resized", "as": "base" },
      { "name": "transcribed", "as": "text" }
    ]
  },
  "text": [
    {
      "text": "Hi there",
      "valign": "top",
      "align": "left"
    },
    {
      "text": "From the 'transcribed' Step: ${use.text_1}",
      "valign": "bottom",
      "align": "right",
      "x_offset": 16,
      "y_offset": -10
    }
  ]
}

Fornecendo a marca-d’água por meio de um Assembly Step

Você também pode passar tanto o arquivo de imagem base quanto a imagem da marca-d’água para um Assembly Step por meio do parâmetro use, permitindo que ambos façam parte do upload ou que você use os resultados de outros Assembly Steps como entrada para o seu Step 🤖/image/resize.

Para que isso funcione, basta usar a sintaxe as:

"my_image_step": {
  "robot": "/image/resize",
  "use": {
    "steps": [
      { "name": ":original", "as": "base" },
      { "name": "watermark_step", "as": "watermark" }
    ]
  }
}

Aqui, a saída de um Step watermark_step é usada como marca-d’água, enquanto a imagem base é obtida dos arquivos enviados por upload.

Se você usar vários campos de entrada de arquivo, poderá informar à Transloadit qual campo fornece a imagem base e qual fornece a marca-d’água. Suponha que você tenha dois campos de entrada de arquivo chamados the_image e the_watermark. Estas Assembly Instructions farão isso funcionar usando a condição fields:

"my_image_step": {
  "robot": "/image/resize",
  "use": {
    "steps": [
      { "name": ":original", "fields": "the_image", "as": "base" },
      { "name": ":original", "fields": "the_watermark", "as": "watermark" }
    ]
  }
}

Observe que o parâmetro watermark_url do Robot continuará funcionando.