Explorando o parâmetro ‘output_meta’ na Transloadit

Samuel Ogundipe

Redator técnico · Lagos, Nigéria · Mostrar biografia

Se você já consultou a documentação dos Robots /upload/handle e /image/resize, talvez tenha visto o parâmetro output_meta. Talvez também tenha se perguntado o que exatamente ele faz. Afinal, ao contrário da maioria dos outros parâmetros, o uso dele pode não ficar imediatamente claro só pelo nome :)

Então, vamos aproveitar para explicar como esse parâmetro funciona e por que ele foi criado!

O parâmetro output_meta

A ideia por trás do parâmetro output_meta é dar aos nossos clientes a possibilidade de coletar certos metadados sobre os arquivos deles. Parece algo bom de ter ativado o tempo todo, certo? Bem, calcular esses dados também exige muito mais da CPU. Então, para manter essas Assemblies rodando rápido o tempo todo, criamos um parâmetro para a coleta de alguns metadados e o mantivemos desativado por padrão.

Você pode definir o parâmetro output_meta nos Steps dos nossos Robots para escolher se quer metadados extras para cada resultado de codificação. Embora isso dê aos nossos usuários o luxo de um controle refinado e granular, também gerou um problema: como ativá-lo para arquivos enviados por upload? Oferecemos suporte a uploads de arquivos desde 2008, mas eles sempre foram um caso meio à parte, porque os uploads eram os únicos arquivos que não resultavam dos nossos Robots.

Assim, depois da introdução do controle granular por meio do parâmetro output_meta, o próximo passo lógico foi encapsular o tratamento de uploads em um Robot próprio e lançar o Robot /upload/handle junto com o novo parâmetro. Agora não há mais exceções, e o comportamento pode ser modificado em cada Step para cada arquivo.

Como funciona?

O parâmetro output_meta pode selecionar metadados opcionais usando um objeto de propriedades booleanas, um array de nomes de propriedades ou um booleano. Este exemplo usa has_transparency; outras propriedades compatíveis incluem dominant_colors e blurhash. Se has_transparency estiver definido como true, ele analisa a imagem e informa se ela tem partes transparentes. Como o cálculo de has_transparency pode demorar bastante para certos arquivos, ele fica excluído do conjunto de resultados por padrão. Afinal, não queremos que nossos clientes paguem um preço alto em tempo de execução se, para começo de conversa, nem se importam com essa propriedade.

Se você quiser saber, por exemplo, se os seus arquivos enviados têm áreas transparentes, pode definir "output_meta": { "has_transparency": true } no Robot /upload/handle; depois disso, você encontrará meta.has_transparency definido nos arquivos resultantes.

Vamos ver como montar uma Assembly que usa esse parâmetro. Fique à vontade para acompanhar!

Criando a Assembly

Nesta seção, vamos criar dois conjuntos separados de Assembly Instructions, que vão mostrar como o parâmetro é usado tanto no Robot /upload/handle quanto no Robot /image/resize.

{
  "steps": {
    ":original": {
      "robot": "/upload/handle",
      "output_meta": {
        "has_transparency": true
      }
    }
  }
}

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "resized": {
      "use": [":original"],
      "robot": "/image/resize",
      "result": true,
      "background": "white",
      "flatten": false,
      "height": 500,
      "imagemagick_stack": "v2.0.3",
      "resize_strategy": "pad",
      "rotation": false,
      "strip": true,
      "trim_whitespace": true,
      "width": 250,
      "output_meta": {
        "has_transparency": true
      }
    }
  }
}

Aqui, temos dois conjuntos diferentes de Assembly Instructions. Um usa apenas o Robot /upload/handle e o outro usa o Robot /image/resize.

Observe que, nas Assembly Instructions que incluem o Robot /image/resize, a propriedade output_meta não aparece no Step :original, mas no Step resized. Isso porque, nessas Assembly Instructions, estamos testando a transparência quando o arquivo está sendo redimensionado, e não quando ele é enviado.

Os resultados

Depois de executar qualquer um dos conjuntos de Assembly Instructions acima, podemos ver no resultado JSON do Robot /upload/handle que a propriedade meta da chave uploads tem um campo chamado has_transparency, definido como true. Essa propriedade só retorna true se a imagem tiver partes transparentes.

Da mesma forma, no resultado JSON retornado pelo Robot /image/resize, a propriedade meta da chave resized na seção results tem um campo chamado has_transparency, definido como true.

Como você pode ver, o parâmetro output_meta pode ser bem útil! Também estamos considerando permitir que você desative outras chaves de metadados existentes para acelerar as Assemblies. Por exemplo, atualmente calculamos hashes MD5 para todos os arquivos por padrão, embora muitos casos de uso talvez não precisem disso. Então, assim que tivermos mais propriedades que possam ser especificadas com esse parâmetro, com certeza vamos avisar você! 💖