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, 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 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.*} — Metadados personalizados por arquivo fornecidos por uploads tus ou instruções de Robots. Consulte Metadados personalizados para ver as regras de herança e um exemplo completo.

  • ${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, 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.

Metadados personalizados com user_meta

Use o parâmetro opcional user_meta para anexar valores JSON a cada arquivo emitido por um Step. Os Steps seguintes leem esses valores como ${file.user_meta.key}. Os valores podem incluir objetos aninhados e arrays. Eles não modificam o conteúdo do arquivo nem substituem propriedades confiáveis, como file.id ou file.meta.

Nos Steps de processamento, os valores são avaliados separadamente para cada arquivo emitido, depois que o Robot roda. Dentro de user_meta, ${file.*} se refere ao primeiro arquivo de entrada e ${result.*} ao arquivo emitido. Por exemplo, /file/hash pode armazenar ${result.meta.hash}. Só é possível usar propriedades de saída já disponíveis nesse momento: isso ocorre antes da extração posterior de metadados e do armazenamento temporário. ${result.*} não está disponível nos parâmetros comuns dos Robots.

Em :original (/upload/handle), os valores são avaliados separadamente para cada upload antes da extração de metadados. Não dependa de hashes ou dimensões extraídos nesse ponto. Para preservar o hash do arquivo enviado, atribua ${file.md5hash} no primeiro Step de processamento, como mostrado abaixo.

A herança depende do Robot. /image/resize carrega os metadados do primeiro arquivo de entrada; ele não combina mapas de várias entradas. Robots que criam novos arquivos de saída, como /html/convert, podem não herdar o mapa. Atribua explicitamente as chaves necessárias usando ${file.user_meta.key} nesses Steps. Os valores do Step atual substituem as chaves correspondentes de primeiro nível que já estão no arquivo de saída; objetos aninhados são substituídos, não mesclados recursivamente.

Preservar o hash da imagem enviada

Configure a credencial de Template do S3 indicada e forneça o campo de requisição customer antes de usar este exemplo. O Step de redimensionamento captura o hash da imagem de entrada; o Step de exportação lê esse valor armazenado em vez do hash do arquivo redimensionado.

{
  "steps": {
    ":original": {
      "robot": "/upload/handle",
      "user_meta": {
        "stage": "uploaded"
      }
    },
    "resized": {
      "use": ":original",
      "robot": "/image/resize",
      "width": 640,
      "height": 640,
      "resize_strategy": "fit",
      "result": true,
      "user_meta": {
        "source_md5": "${file.md5hash}",
        "stage": "resized",
        "source": {
          "name": "${file.name}"
        },
        "tags": [
          "profile",
          "${fields.customer}"
        ]
      }
    },
    "exported": {
      "use": "resized",
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS_NAME",
      "path": "${file.user_meta.source_md5}/${unique_prefix}/${file.url_name}"
    }
  }
}

O resultado resized inclui user_meta com source_md5, o stage atualizado, um objeto aninhado source e um array tags. ${unique_prefix} mantém os caminhos de exportação únicos mesmo para uploads idênticos. Os objetos de arquivo expõem esses metadados na Resposta de Assembly Status. Não armazene segredos neles.

Escolher o escopo certo de metadados

fields contém valores de requisição no nível da Assembly. meta contém metadados detectados do arquivo. user_meta contém valores personalizados por arquivo, incluindo metadados adicionais enviados por tus. Um valor ausente ou null é lido como uma string vazia por uma Assembly Variable simples; uma variável numérica ou booleana isolada mantém seu tipo.

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 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, que permite avaliar JavaScript a partir das suas Assembly Instructions.