Desenvolver um trabalhador de metadados do Asset compute

Os trabalhadores de Assets compute personalizados podem produzir dados XMP (XML) que são enviados de volta para AEM e armazenados como metadados em um ativo.

Casos de uso comuns incluem:

  • Integrações com sistemas de terceiros, como um PIM (Product Information Management System), em que os metadados adicionais devem ser recuperados e armazenados no ativo
  • Integrações com os serviços da Adobe, como IA de conteúdo e Commerce, para aumentar os metadados de ativos com atributos adicionais de aprendizado de máquina
  • Derivar metadados sobre o ativo de seu binário e armazená-lo como metadados de ativos no AEM as a Cloud Service

O que você fará

Neste tutorial, criaremos um trabalhador de metadados do Asset Compute que deriva as cores mais usadas em um ativo de imagem e grava os nomes das cores de volta nos metadados do ativo no AEM. Embora o próprio trabalhador seja básico, este tutorial o usa para explorar como os trabalhadores do Asset Compute podem ser usados para gravar metadados nos ativos no AEM as a Cloud Service.

Fluxo lógico de uma invocação de trabalho de metadados de Asset compute

A invocação de trabalhadores de metadados de Asset compute é quase idêntica à de trabalhadores geradores de representação binária, sendo que a diferença primária é o tipo de retorno de uma representação XMP (XML) cujos valores também são gravados nos metadados do ativo.

Os trabalhadores do Asset Compute implementam o contrato de API do trabalhador do SDK do Asset Compute, na função renditionCallback(...), que é conceitualmente:

  • Entrada: Os parâmetros binário e perfil de processamento originais de um ativo AEM
  • Saída: uma representação XMP (XML) persistiu no ativo AEM como uma representação e nos metadados do ativo

Fluxo lógico do trabalhador de metadados do Asset compute

  1. O serviço de Autor do AEM invoca o trabalhador de metadados do Asset compute, fornecendo o binário original (1a) do ativo e (1b) quaisquer parâmetros definidos no Perfil de Processamento.
  2. O SDK do Asset Compute orquestra a execução da função renditionCallback(...) do trabalhador de metadados de Asset compute personalizado, derivando uma representação XMP (XML), com base no binário (1a) do ativo e em qualquer parâmetro do Perfil de Processamento (1b).
  3. O trabalhador do Asset compute salva a representação XMP (XML) em rendition.path.
  4. Os dados XMP (XML) gravados em rendition.path são transportados por meio do SDK do Asset Compute para o Serviço de Autor do AEM e os expõem como (4a) uma representação de texto e (4b) persistentes para o nó de metadados do ativo.

Configurar o manifest.yml manifest

Todos os trabalhadores do Asset compute devem estar registrados no manifest.yml.

Abra o manifest.yml do projeto e adicione uma entrada de trabalho que configure o novo trabalhador, neste caso metadata-colors.

Lembre-se de que .yml diferencia espaços em branco.

packages:
  __APP_PACKAGE__:
    license: Apache-2.0
    actions:
      worker:
        function: actions/worker/index.js
        web: 'yes'
        runtime: 'nodejs:12'
        limits:
          timeout: 60000 # in ms
          memorySize: 512 # in MB
          concurrency: 10
        annotations:
          require-adobe-auth: true
      metadata-colors:
        function: actions/metadata-colors/index.js
        web: 'yes'
        runtime: 'nodejs:12'
        limits:
          memorySize: 512 # in MB

function aponta para a implementação de trabalho criada na próxima etapa. Nomeie os trabalhadores semanticamente (por exemplo, actions/worker/index.js pode ter sido melhor nomeado como actions/rendition-circle/index.js), como eles mostram na URL do trabalhador e também determinam o nome da pasta do conjunto de testes do trabalhador.

O limits e o require-adobe-auth são configurados discretamente por trabalhador. Neste trabalho, 512 MB de memória está alocado à medida que o código inspeciona (potencialmente) dados de imagem binária grandes. Os outros limits são removidos para usar os padrões.

Desenvolver um trabalhador de metadados metadata-worker

Crie um novo arquivo JavaScript do trabalhador de metadados no projeto do Asset Compute no caminho manifest.yml definido para o novo trabalhador, em /actions/metadata-colors/index.js

Instalar módulos npm

Instale os módulos npm extras (@adobe/asset-compute-xmp, get-image-colors e color-namer) usados neste trabalho do Asset Compute.

$ npm install @adobe/asset-compute-xmp
$ npm install get-image-colors
$ npm install color-namer

Código de trabalhador de metadados

Este trabalhador é muito semelhante ao trabalhador gerador de representação. A principal diferença é que ele grava dados XMP (XML) no rendition.path para ser salvo novamente no AEM.

"use strict";

const { worker, SourceCorruptError } = require("@adobe/asset-compute-sdk");
const fs = require("fs").promises;

// Require the @adobe/asset-compute-xmp module to create XMP
const { serializeXmp } = require("@adobe/asset-compute-xmp");

// Require supporting npm modules to derive image colors from image data
const getColors = require("get-image-colors");
// Require supporting npm modules to convert image colors to color names
const namer = require("color-namer");

exports.main = worker(async (source, rendition, params) => {
  // Perform any necessary source (input) checks
  const stats = await fs.stat(source.path);
  if (stats.size === 0) {
    // Throw appropriate errors whenever an erring condition is met
    throw new SourceCorruptError("source file is empty");
  }
  const MAX_COLORS = 10;
  const DEFAULT_COLORS_FAMILY = 'basic';

  // Read the color family parameter to use to derive the color names
  let colorsFamily = rendition.instructions.colorsFamily || DEFAULT_COLORS_FAMILY;

  if (['basic', 'hex', 'html', 'ntc', 'pantone', 'roygbiv'].indexOf(colorsFamily) === -1) {
      colorsFamily = DEFAULT_COLORS_FAMILY;
  }

  // Use the `get-image-colors` module to derive the most common colors from the image
  let colors = await getColors(source.path, { options: MAX_COLORS });

  // Convert the color Chroma objects to their closest names
  let colorNames = colors.map((color) => getColorName(colorsFamily, color));

  // Serialize the data to XMP metadata
  // These properties are written to the [dam:Asset]/jcr:content/metadata resource
  // This stores
  // - The list of color names is stored in a JCR property named `wknd:colors`
  // - The colors family used to derive the color names is stored in a JCR property named `wknd:colorsFamily`
  const xmp = serializeXmp({
      // Use a Set to de-duplicate color names
      "wknd:colors": [...new Set(colorNames)],
      "wknd:colorsFamily": colorsFamily
    }, {
      // Define any property namespaces used in the above property/value definition
      // These namespaces are automatically registered in AEM if they do not yet exist
      namespaces: {
        wknd: "https://wknd.site/assets/1.0/",
      },
    }
  );

  // Save the XMP metadata to be written back to the asset's metadata node
  await fs.writeFile(rendition.path, xmp, "utf-8");
});

/**
 * Helper function that derives the closest color name for the color, based on the colors family
 *
 * @param {*} colorsFamily the colors name family to use
 * @param {*} color the color to convert to a name
 */
function getColorName(colorsFamily, color) {
    if ('hex' === colorsFamily) {  return color; }

    let names = namer(color.rgb())[colorsFamily];

    if (names.length >= 1) { return names[0].name; }
}

Executar o trabalho de metadados localmente development-tool

Com o código do trabalhador concluído, ele pode ser executado usando a Ferramenta de desenvolvimento de Assets compute local.

Como nosso projeto do Asset Compute contém dois workers (a representação de círculo anterior e este metadata-colors worker), a 🔗 definição de perfil da Ferramenta de Desenvolvimento do Asset Compute lista perfis de execução para ambos os workers. A segunda definição de perfil aponta para o novo trabalhador metadata-colors.

Representação de metadados XML

  1. Na raiz do projeto do Asset Compute

  2. Executar aio app run para iniciar a Ferramenta de Desenvolvimento do Asset Compute

  3. Na lista suspensa Selecionar um arquivo…, escolha uma imagem de exemplo para processar

  4. Na segunda configuração de definição de perfil, que aponta para o trabalhador metadata-colors, atualize "name": "rendition.xml", pois esse trabalhador gera uma representação XMP (XML). Opcionalmente, adicione um parâmetro colorsFamily (valores com suporte basic, hex, html, ntc, pantone, roygbiv).

    code language-json
    {
        "renditions": [
            {
                "worker": "...",
                "name": "rendition.xml",
                "colorsFamily": "pantone"
            }
        ]
    }
    
  5. Toque em Executar e aguarde a geração da representação XML

    • Como ambos os trabalhadores estão listados na definição do perfil, ambas as representações serão geradas. Como opção, a definição do perfil superior apontando para o trabalhador de representação de círculo pode ser excluída, para evitar sua execução a partir da Ferramenta de desenvolvimento.
  6. A seção Representações pré-visualiza a representação gerada. Toque em rendition.xml para baixá-lo e abri-lo no Código VS (ou no seu editor de texto/XML favorito) para examinar.

Testar o trabalhador test

Os trabalhadores de metadados podem ser testados usando a mesma estrutura de teste de Asset compute que as representações binárias. A única diferença é que o arquivo rendition.xxx no caso de teste deve ser a representação XMP (XML) esperada.

  1. Crie a seguinte estrutura no projeto do Asset Compute:

    code language-none
    /test/asset-compute/metadata-colors/success-pantone/
    
        file.jpg
        params.json
        rendition.xml
    
  2. Use o arquivo de amostra como o file.jpg do caso de teste.

  3. Adicione o seguinte JSON ao params.json.

    code language-none
    {
        "fmt": "xml",
        "colorsFamily": "pantone"
    }
    

    Observe que "fmt": "xml" é necessário para instruir o conjunto de testes a gerar uma representação baseada em texto .xml.

  4. Forneça o XML esperado no arquivo rendition.xml. Isso pode ser obtido por:

    • Executar o arquivo de entrada de teste por meio da Ferramenta de desenvolvimento e salvar a representação XML (validada).
    code language-none
    <?xml version="1.0" encoding="UTF-8"?><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:wknd="https://wknd.site/assets/1.0/"><rdf:Description><wknd:colors><rdf:Seq><rdf:li>Silver</rdf:li><rdf:li>Black</rdf:li><rdf:li>Outer Space</rdf:li></rdf:Seq></wknd:colors><wknd:colorsFamily>pantone</wknd:colorsFamily></rdf:Description></rdf:RDF>
    
  5. Execute aio app test a partir da raiz do projeto do Asset Compute para executar todos os conjuntos de testes.

Implantar o trabalhador no Adobe I/O Runtime deploy

Para chamar esse novo trabalhador de metadados do AEM Assets, ele deve ser implantado no Adobe I/O Runtime, usando o comando:

$ aio app deploy

implantação do aplicativo aio

Observe que isso implantará todos os trabalhadores no projeto. Revise as instruções de implantação não abreviada para saber como implantar em espaços de trabalho de Preparo e Produção.

Integrar a perfis de processamento AEM processing-profile

Chame o trabalhador do AEM criando um novo serviço de perfil de processamento personalizado ou modificando um já existente que chame esse trabalhador implantado.

Processando perfil

  1. Faça login no serviço de Autor do AEM as a Cloud Service como um Administrador do AEM

  2. Navegue até Ferramentas > Assets > Processando Perfis

  3. Criar um novo, ou editar e um perfil de processamento existente

  4. Toque na guia Personalizado e em Adicionar novo

  5. Definir o novo serviço

    • Criar representação de metadados: alternar para ativo

    • Ponto de extremidade: https://...adobeioruntime.net/api/v1/web/wkndAemAssetCompute-0.0.1/metadata-colors

      • Esta é a URL para o trabalhador obtida durante a implantação ou usando o comando aio app get-url. Verifique se o URL aponta para o espaço de trabalho correto com base no ambiente do AEM as a Cloud Service.
    • Parâmetros de serviço

      • Toque em Adicionar parâmetro

        • Chave: colorFamily
        • Valor: pantone
          • Valores com suporte: basic, hex, html, ntc, pantone, roygbiv
    • Tipos MIME

      • Inclui: image/jpeg, image/png, image/gif, image/svg
        • Esses são os únicos tipos MIME aceitos pelos módulos npm de terceiros usados para derivar as cores.
      • Exclusões: Leave blank
  6. Toque em Salvar na parte superior direita

  7. Aplicar o perfil de processamento a uma pasta do AEM Assets se ainda não tiver sido feito

Atualizar o esquema de metadados metadata-schema

Para revisar os metadados de cores, mapeie dois novos campos no esquema de metadados da imagem para as novas propriedades de dados de metadados que o trabalhador preenche.

Esquema de metadados

  1. No serviço de Autor do AEM, navegue até Ferramentas > Assets > Esquemas de metadados

  2. Navegue até padrão, selecione e edite a imagem e adicione campos de formulário somente leitura para expor os metadados de cor gerados

  3. Adicionar um Texto de uma Linha

    • Rótulo do campo: Colors Family
    • Mapear para a propriedade: ./jcr:content/metadata/wknd:colorsFamily
    • Regras > Campo > Desabilitar edição: marcado
  4. Adicionar um Texto de Vários Valores

    • Rótulo do campo: Colors
    • Mapear para a propriedade: ./jcr:content/metadata/wknd:colors
  5. Toque em Salvar na parte superior direita

Processamento de ativos

Detalhes do ativo

  1. No serviço de Autor do AEM, navegue até Assets > Arquivos
  2. Navegue até a pasta ou subpasta à qual o Perfil de Processamento é aplicado
  3. Carregue uma nova imagem (JPEG, PNG, GIF ou SVG) para a pasta ou processe novamente as imagens existentes usando o Perfil de Processamento atualizado
  4. Quando o processamento estiver concluído, selecione o ativo e toque em propriedades na barra de ação superior para exibir seus metadados
  5. Revise os Colors Family e Colors campos de metadados para obter os metadados gravados do trabalho de metadados de Asset compute personalizado.

Com os metadados de cores gravados nos metadados do ativo, no recurso [dam:Asset]/jcr:content/metadata, esses metadados são indexados por uma maior capacidade de descoberta de ativos usando esses termos por meio de pesquisa, e eles podem até ser gravados no binário do ativo se o fluxo de trabalho Writeback de metadados DAM for chamado nele.

Representação de metadados no AEM Assets

Arquivo de representação de metadados do AEM Assets

O arquivo XMP real gerado pelo trabalhador de metadados do Asset Compute também é armazenado como uma representação discreta no ativo. Esse arquivo geralmente não é usado, em vez disso, os valores aplicados ao nó de metadados do ativo são usados, mas a saída XML bruta do trabalhador está disponível no AEM.

código de trabalho de cores de metadados no Github

O metadata-colors/index.js final está disponível no Github em:

O conjunto de testes test/asset-compute/metadata-colors final está disponível no Github em:

recommendation-more-help
4859a77c-7971-4ac9-8f5c-4260823c6f69