Transloadit

Assembly Variables

A Transloadit oferece suporte a variáveis dentro das suas Assemblies para que você possa criar fluxos de trabalho mais poderosos. Você pode, por exemplo, filtrar arquivos com base em width, influenciar o local de armazenamento com base em type e muito mais. Incluímos uma lista completa de variáveis de substituição disponíveis para Assembly Variables. Elas podem ser usadas em qualquer valor de parâmetro em qualquer Robot.

  • ${assembly.id} — O ID da Assembly que representa o upload atual, que é um UUIDv4 sem hífens.

  • ${assembly.region} — A região da AWS onde a Assembly está sendo processada. Você poderia usar isso para importar arquivos de um bucket na mesma região, reduzindo custos de transferência de dados e latências.

  • ${assembly.parent_id} — O ID da Assembly pai ao reexecutar essa Assembly pai.

  • ${unique_prefix} — Um prefixo único de 33 caracteres usado para evitar colisões de nomes de arquivo, como "f2/d3eeeb67479f11f8b091b04f6181ad".

    Observe o / no prefixo. Se você usar ${unique_prefix} no parâmetro path do 🤖/s3/store  (English), por exemplo, isso criará subdiretórios no seu bucket do S3. Isso pode ou não ser desejado. Use ${file.id} se você precisar de um prefixo único sem barras.

  • ${unique_original_prefix} — Isso é semelhante a ${unique_prefix}, com a exceção de que dois resultados de codificação diferentes do mesmo arquivo enviado (o arquivo original) terão o mesmo valor de prefixo aqui.

  • ${previous_step.name} — O nome do Step anterior que produziu o arquivo atual.

  • ${file.id} — O ID do arquivo sendo processado, que é um UUIDv4 sem hífens.

  • ${file.original_id} — O ID do arquivo original do qual um determinado arquivo deriva. Por exemplo, se você usar um Robot de importação para importar arquivos e depois codificá-los de alguma forma, os arquivos resultantes da codificação terão um ${file.original_id} que corresponde ao ${file.id} do arquivo importado.

  • ${file.original_name} — O nome do arquivo original (incluindo a extensão do arquivo) do qual um determinado arquivo deriva. Por exemplo, se você usar um Robot de importação para importar arquivos e depois codificá-los de alguma forma, os arquivos resultantes da codificação terão um ${file.original_name} que corresponde ao ${file.name} do arquivo importado.

  • ${file.original_basename} — O nome base do arquivo original do qual um determinado arquivo deriva. Por exemplo, se você usar um Robot de importação para importar arquivos e depois codificá-los de alguma forma, os arquivos resultantes da codificação terão um ${file.original_basename} que corresponde ao ${file.basename} do arquivo importado.

  • ${file.original_path} — O caminho de importação do arquivo original do qual um determinado arquivo deriva. Todos os nossos Robots de importação definem ${file.original_path} de acordo.

    Por exemplo, se você usar o 🤖/s3/import  (English) para importar arquivos do Amazon S3, os arquivos importados, assim como todos os arquivos derivados deles, terão um file.original_path igual ao caminho do arquivo no S3, mas sem o nome do arquivo. Então, se o caminho no S3 era "path/to/file.txt", file.original_path será "/path/to/". Se o caminho era "/a.txt", ${file.original_path} será "/".

    file.original_path sempre terá barras suficientes para que você possa usá-lo com segurança no parâmetro path do seu Step de exportação, assim: "path": "${file.original_path}${file.name}". Isso é útil se você quiser importar arquivos de, por exemplo, S3, convertê-los de alguma forma e armazená-los novamente no S3 na mesma estrutura de arquivos (ou em uma semelhante).

  • ${file.name} — O nome do arquivo sendo processado, incluindo a extensão do arquivo.

  • ${file.url_name} — O nome do arquivo em formato slug.

    Os nomes de arquivo são transliterados e sanitizados para produzir uma versão segura para URL. Caracteres não latinos são convertidos em equivalentes latinos (por exemplo, café.jpg → cafe.jpg, бубу.mov → bubu.mov), e espaços em branco ou pontuação são substituídos por hífens. Caracteres consecutivos não distintos podem ser reduzidos a um único hífen.

  • ${file.basename} — O nome do arquivo sendo processado, sem a extensão do arquivo. Isso permite que você faça coisas dinamicamente por arquivo em vez de por Assembly com fields.

  • ${file.url_basename} — O nome base do arquivo em formato slug (o nome do arquivo sem a extensão do arquivo).

    Os nomes de arquivo são transliterados e sanitizados para produzir uma versão segura para URL. Caracteres não latinos são convertidos em equivalentes latinos (por exemplo, café.jpg → cafe.jpg, бубу.mov → bubu.mov), e espaços em branco ou pontuação são substituídos por hífens. Caracteres consecutivos não distintos podem ser reduzidos a um único hífen.

  • ${file.user_meta} — Os uploads tus, que você usa para enviar arquivos para a Transloadit, podem carregar valores de metadados. Todos os valores extras enviados junto acabam em user_meta. Esses são metadados personalizados que você mesmo fornece, não o tipo de arquivo ou o tipo MIME detectado pela Transloadit.

  • ${file.stepvars.*} — Valores escalares com escopo de arquivo definidos por um Step anterior. Consulte Variáveis de Step para ver as regras de herança e um exemplo.

  • ${file.ext} — A extensão do arquivo.

  • ${file.size} — O tamanho do arquivo em bytes.

  • ${file.type} — Uma categoria ampla de arquivo detectada pela Transloadit e exposta no Assembly Status JSON, como image, video, audio, pdf, office, xls, swf ou document. Use isso quando você precisar de uma categoria genérica ou de compatibilidade com fluxos de trabalho existentes. Para verificações de conteúdo robustas, prefira ${file.mime}.

  • ${file.mime} — O tipo MIME do arquivo conforme detectado pela Transloadit, normalmente durante a extração de metadados no lado do servidor no fluxo de upload normal. Isso pode diferir do tipo MIME originalmente informado pelo cliente ou pelo navegador. Prefira isso para ramificações por tipo de conteúdo, usando correspondências de família MIME como image/*, video/* ou audio/* sempre que possível.

  • ${file.md5hash} — O hash MD5 do arquivo. Esse é um hash sobre o conteúdo do arquivo, não apenas sobre o nome do arquivo.

  • ${file.*} — Qualquer propriedade de arquivo disponível no array de resultados finais, como ${file.meta.width}. Nem todas as chaves de meta estão disponíveis para todos os tipos de arquivo.

  • ${fields.*} — Os campos enviados junto com o upload.

    Por exemplo, no caso de um envio de formulário em que o Uppy estava configurado para permitir fields: ['myvar'], e o formulário tinha uma tag como <input type="hidden" name="myvar" value="1" />, ${fields.myvar} conteria um valor de 1.

    Como alternativa, os campos também poderiam ser preenchidos programaticamente assim:

    {
  "steps": {
    "store": {
      "use": "encoded",
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS_NAME",
      "path": "${assembly.id}/${fields.subdir}/356"
    }
  },
  "fields": {
    "subdir": "bar"
  }
}

    Em caso de conflito, as variáveis derivadas de campos de formulário têm precedência sobre aquelas derivadas da chave fields.

    As requisições ao Smart CDN, por sua vez, preenchem o mesmo namespace a partir da URL. Os parâmetros de consulta se tornam valores ${fields.*}, e o caminho após o nome do Template se torna o valor implícito de ${fields.input} sem barra inicial. Por exemplo, https://my-app.tlcdn.com/image-template/images/canoe.jpg?w=640 fornece ${fields.input} como images/canoe.jpg e ${fields.w} como 640. Portanto, usar ${fields.input} como path para o 🤖/s3/import lê a chave de objeto images/canoe.jpg. Esse caminho de preenchimento derivado da URL é separado dos campos de formulário no momento do upload e da chave fields da Assembly descrita acima.

  • ${browser.wanted_image_format} — O formato de imagem preferido pelo cabeçalho Accept do cliente solicitante. Ele é resolvido para aquele entre "avif", "webp" ou "jpg" que tiver o maior peso positivo de qualidade (q), preferindo essa ordem quando os pesos empatam. Faixas de mídia curinga como */* e image/* não fazem um cliente optar por AVIF ou WebP. Um cabeçalho ausente, vazio ou apenas com curinga é resolvido para "jpg". O JPEG também é um candidato pleno, então image/avif;q=0.2,image/jpeg;q=1 é resolvido para "jpg".

    A variável também está disponível para Assemblies comuns. Requisições de SDK e de API sem um cabeçalho Accept significativo costumam usar o fallback "jpg". Um nó de borda do Smart CDN pode, em vez disso, definir um cabeçalho x-tl-image-format confiável e pré-normalizado, que é resolvido para o mesmo valor "avif", "webp" ou "jpg" sem reanalisar Accept.

    O fallback "jpg" descreve o suporte do cliente, e não o arquivo de entrada. Ao usar o 🤖/image/resize  (English), mapeie esse fallback para null para manter o formato de entrada para clientes sem uma preferência explícita por formatos modernos. Isso preserva a transparência e a animação em vez de recodificar desnecessariamente a entrada como JPEG.

  • ${Date.now()} — A data e a hora atuais representadas como o número de milissegundos decorridos desde a época UNIX, que é definida como a meia-noite do início de 1º de janeiro de 1970, UTC. Tecnicamente, isso não é uma variável, mas usa avaliação dinâmica de código.

Variáveis de Step com escopo de arquivo

Use o parâmetro opcional stepvars para preservar um valor de um Step anterior e lê-lo depois como ${file.stepvars.key}, onde key é o nome que você atribuiu. O mapa é anexado aos arquivos, não é compartilhado por toda a Assembly e não modifica o conteúdo do arquivo.

Cada valor deve ser resolvido como uma string, um número finito, um booleano ou null. Arrays e objetos aninhados não são suportados. Você pode usar valores literais ou Assembly Variables.

A menos que a interpolação de variáveis esteja desativada para este campo, um valor composto por uma única variável mantém seu tipo numérico ou booleano; uma string mista continua sendo uma string. Um null armazenado e uma chave não definida são ambos lidos como uma string vazia através de ${file.stepvars.key}, mesmo que o status JSON possa manter null.

Em :original (🤖/upload/handle  (English)), os valores são resolvidos separadamente para cada arquivo enviado após a extração de metadados, tanto para uploads multipart quanto para uploads tus.

Um Step de processamento pode executar Jobs separados para diferentes arquivos de entrada. Para cada Job, os valores de stepvars são resolvidos antes de o Robot rodar, usando as variáveis do primeiro arquivo de entrada. Todo arquivo emitido por esse Job recebe os mesmos valores resolvidos. O stepvars de um Step de processamento não pode ler ${result.*}: uma referência simples como ${result.md5hash} é resolvida como uma string vazia. Use user_meta para valores que dependem de cada saída emitida.

Os parâmetros resolvidos antes de o Robot rodar podem ler chaves herdadas, mas não os valores que o próprio Step atribui. Coloque os consumidores de valores recém-atribuídos em um Step posterior.

A herança depende do Robot. Por exemplo, o 🤖/image/resize  (English) preserva o mapa do primeiro arquivo de entrada. Os mapas de entrada não são mesclados, e ramificações derivadas separadas carregam mapas independentes. Alguns Robots criam novos arquivos de saída sem herdar o mapa: o 🤖/html/convert  (English) faz isso mesmo ao converter um arquivo HTML de entrada. Atribua explicitamente todas as chaves necessárias no stepvars desse Step, usando as variáveis do arquivo de entrada. As chaves atribuídas pelo Step atual substituem as chaves correspondentes que já estão em seus arquivos de saída; as demais chaves existentes permanecem.

Em um Step de processamento, um valor que é resolvido como um array ou objeto aciona ROBOT_VALIDATION_BASE_ERROR quando o Robot emite um arquivo de resultado, e não durante a interpolação de pré-execução. A mesma validação de escalares se aplica em :original: escolha variáveis comprovadamente escalares, como ${file.md5hash}, e não atribua o objeto ${file.meta} inteiro.

Se um Step não tiver arquivo de entrada, referências a ${file.*} como ${file.md5hash} são resolvidas como uma string vazia. Para capturar metadados de arquivos importados, atribua stepvars em um Step posterior que use esses arquivos.

Preserve o hash de uma imagem enviada

Este fragmento de Assembly Instructions captura o MD5 de cada imagem enviada antes do redimensionamento. Configure a credencial de Template nomeada do S3 antes de usar o Step de exportação.

{
  "steps": {
    ":original": {
      "robot": "/upload/handle",
      "stepvars": {
        "source_md5": "${file.md5hash}",
        "stage": "uploaded"
      }
    },
    "resized": {
      "use": ":original",
      "robot": "/image/resize",
      "width": 640,
      "height": 640,
      "resize_strategy": "fit",
      "result": true,
      "stepvars": {
        "stage": "resized"
      }
    },
    "exported": {
      "use": "resized",
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS_NAME",
      "path": "${file.stepvars.source_md5}/${unique_prefix}/${file.url_name}"
    }
  }
}

O arquivo resized mantém source_md5 do upload e altera stage para "resized". O caminho de exportação lê esse hash armazenado, e não o hash do arquivo redimensionado. ${unique_prefix} mantém o caminho único mesmo quando os uploads têm conteúdo idêntico.

Os objetos de arquivo em uploads e results expõem o mapa como stepvars na resposta do Assembly Status  (English). O mapa pode estar vazio ({}); trate o campo como opcional ao analisar as respostas. Neste exemplo, result: true torna os arquivos redimensionados disponíveis em results. Esses metadados são visíveis para a aplicação, portanto não coloque segredos neles.

Escolha o escopo de metadados correto

  • fields fornece valores de requisição no nível da Assembly através de ${fields.*}; não é um mapa por arquivo.
  • stepvars armazena valores escalares junto a cada arquivo para Steps posteriores através de ${file.stepvars.*}.
  • user_meta é um mapa de metadados personalizados separado, também usado por uploads tus. Use-o para dados JSON aninhados ou para valores de Steps de processamento baseados em cada saída emitida através de ${result.*}. Use stepvars para levar adiante valores escalares de entrada sem misturá-los aos metadados personalizados da sua aplicação.

Exemplo de Assembly Variables

Digamos que você não goste do local onde os arquivos são armazenados. Por padrão, a Transloadit toma cuidado para não sobrescrever nada. Todos os Robots de exportação  (English) têm um parâmetro path com o padrão "${unique_prefix}/${file.url_name}", resultando em locais como: "f2/d3eeeb67479f11f8b091b04f6181ad/my-file-name.png".

Poderíamos, por exemplo, alterar o valor do parâmetro para "${previous_step.name}/${file.id}.${file.ext}", o que faria os caminhos ficarem parecidos com "video-step-name/a8d3eeeb67479f11f8b091b04f6181ad.png".

Nem todas as Assembly Variables são iguais, e algumas são mais únicas (e, portanto, adequadas para basear o local de armazenamento apenas nelas). Aqui estão alguns exemplos, ordenados de menos único para mais único:

  • ${file.ext} é o mesmo para muitos arquivos
  • ${file.url_name} tem, especialmente entre usuários e ao longo do tempo, uma alta probabilidade de colisões, por exemplo: avatar.jpg
  • ${previous_step.name} é o mesmo para todos os arquivos que são resultados do mesmo Step
  • ${assembly.id} é o mesmo para todos os arquivos dentro de uma única Assembly
  • ${file.id} e ${unique_prefix} são únicos para cada arquivo

Se as Assembly Variables não oferecerem flexibilidade suficiente para o seu caso de uso, também oferecemos execução dinâmica de código, usando o Robot /script/run  (English), que permite avaliar JavaScript a partir das suas Assembly Instructions.