Développement d’un agent de métadonnées d’Asset compute

Les agents d’Asset compute personnalisés peuvent produire des données XMP (XML) qui sont renvoyées à AEM et stockées en tant que métadonnées sur un fichier.

Les cas d'utilisation courants sont les suivants :

  • Intégrations à des systèmes tiers, tels qu’un PIM (Product Information Management System), dans lequel des métadonnées supplémentaires doivent être récupérées et stockées sur la ressource
  • Intégrations à des services d’Adobe, tels que Content and Commerce AI, afin d’enrichir les métadonnées de ressources par des attributs d’apprentissage automatique supplémentaires.
  • Dériver des métadonnées sur le fichier à partir de son fichier binaire et les stocker en tant que métadonnées de fichier dans AEM en tant que Cloud Service

Ce que vous allez faire

Dans ce didacticiel, nous allons créer un outil de métadonnées d'Asset compute qui dérive les couleurs les plus couramment utilisées dans un fichier d'image et écrit les noms des couleurs dans les métadonnées du fichier dans AEM. Bien que le collaborateur lui-même soit de base, ce didacticiel l’utilise pour explorer comment les collaborateurs d’Asset compute peuvent être utilisés pour écrire des métadonnées sur des ressources en AEM en tant que Cloud Service.

Flux logique d’un appel d’opérateur de métadonnées d’Asset compute

L’appel des opérateurs de métadonnées d’Asset compute est presque identique à celui du rendu binaire générant des opérateurs, la Principale différence étant que le type de retour est un rendu XMP (XML) dont les valeurs sont également écrites dans les métadonnées du fichier.

Les agents d’Asset compute implémentent le contrat Asset compute SDK worker API dans la fonction renditionCallback(...), qui est conceptuellement :

  • Entrée : binaire d’origine d’une ressource AEM et paramètres de Profil de traitement
  • Output : un rendu XMP (XML) conservé dans l’AEM en tant que rendu et dans les métadonnées de l’élément

Flux logique de travail de métadonnées d'Asset compute

  1. Le service Auteur AEM appelle le programme de travail des métadonnées de l’Asset compute, en fournissant le fichier binaire original (1a) et (1b) tous les paramètres définis dans le Profil de traitement.
  2. Le SDK d’Asset compute orchestre l’exécution de la fonction renditionCallback(...) de l’agent de métadonnées d’Asset compute personnalisé, en dérivant un rendu XMP (XML), en fonction du rendu binaire (1a) de l’actif et des paramètres de Profil de traitement (1b).
  3. Le travailleur d’Asset compute enregistre la représentation XMP (XML) dans rendition.path.
  4. Les données XMP (XML) écrites sur rendition.path sont transportées via le SDK Asset compute vers le service d’auteur AEM et les exposent sous la forme (4a) d’un rendu de texte et (4b) conservées sur le noeud de métadonnées de la ressource.

Configuration du fichier manifest.yml

Tous les travailleurs d'Asset compute doivent être enregistrés dans le manifest.yml.

Ouvrez le projet manifest.yml et ajoutez une entrée de collaborateur qui configure le nouveau collaborateur, dans ce cas metadata-colors.

Rappelez-vous .yml est sensible aux espaces blancs.

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 pointe vers l’implémentation du collaborateur créée à l’étape suivante. Nommez les agents de manière sémantique (par exemple, actions/worker/index.js aurait pu être mieux nommé actions/rendition-circle/index.js), comme ils s’affichent dans l’URL du travailleur et déterminez également le nom de dossier de la suite de tests du travailleur.

Les limits et require-adobe-auth sont configurés séparément par travailleur. Dans ce programme de travail, 512 MB de la mémoire est allouée lorsque le code examine (potentiellement) les données d'image binaires volumineuses. Les autres limits sont supprimés pour utiliser les valeurs par défaut.

Développement d’un agent de métadonnées

Créez un nouveau fichier JavaScript de travail de métadonnées dans le projet d’Asset compute à l’emplacement manifest.yml défini pour le nouveau programme de travail, à /actions/metadata-colors/index.js.

Installation des modules npm

Installez les modules npm supplémentaires (@adobe/asset-compute-xmp, get-image-color et color-namer) qui seront utilisés dans ce programme de travail d’Asset compute.

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

Code de travail des métadonnées

Ce programme de travail ressemble beaucoup au programme de travail générant des rendus, la Principale différence est qu'il écrit XMP données (XML) dans rendition.path pour être enregistré à l'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 will be 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; }
}

Exécutez le programme de travail des métadonnées localement

Une fois le code de travail terminé, il peut être exécuté à l’aide de l’outil de développement d’Asset compute local.

Comme notre projet d'Asset compute contient deux travailleurs (le précédent rendu circulaire et ce metadata-colors travailleur), la définition de profil de l'outil de développement d'Asset compute de l'outil liste l'exécution des profils pour les deux travailleurs. La deuxième définition de profil pointe vers le nouveau travailleur metadata-colors.

Rendu de métadonnées XML

  1. A partir de la racine du projet d'Asset compute

  2. Exécuter aio app run pour début de l'outil de développement d'Asset compute

  3. Dans la section Sélectionner un fichier…, choisissez une image exemple à traiter.

  4. Dans la seconde configuration de définition de profil, qui pointe vers le programme de travail metadata-colors, mettez à jour "name": "rendition.xml" car ce programme de travail génère un rendu XMP (XML). Vous pouvez éventuellement ajouter un paramètre colorsFamily (valeurs prises en charge basic, hex, html, ntc, pantone, roygbiv).

    {
    "renditions": [
        {
            "worker": "...",
            "name": "rendition.xml",
            "colorsFamily": "pantone"
        }
    ]
}

  5. Appuyez sur Exécuter et attendez la génération du rendu XML.

    • Les deux travailleurs étant répertoriés dans la définition du profil, les deux rendus sont générés. Si vous le souhaitez, la définition de profil supérieur pointant vers le opérateur de rendu du cercle peut être supprimée, afin d’éviter de l’exécuter à partir de l’outil de développement.

  6. La section Rendus prévisualisation le rendu généré. Appuyez sur rendition.xml pour le télécharger, puis ouvrez-le dans VS Code (ou dans votre éditeur XML/texte favori) pour le consulter.

Testez le collaborateur

Les agents de métadonnées peuvent être testés à l’aide de la même structure de test d’Asset compute que les rendus binaires. La seule différence est que le fichier rendition.xxx dans la casse de test doit être le rendu XMP (XML) attendu.

  1. Créez la structure suivante dans le projet d'Asset compute :

    /test/asset-compute/metadata-colors/success-pantone/

    file.jpg
    params.json
    rendition.xml

  2. Utilisez le fichier d’exemple comme file.jpg du cas de test.

  3. Ajoutez le fichier JSON suivant sur params.json.

    {
    "fmt": "xml",
    "colorsFamily": "pantone"
}

    Notez que "fmt": "xml" est nécessaire pour demander à la suite de tests de générer un rendu texte .xml.

  4. Indiquez le code XML attendu dans le fichier rendition.xml. Pour ce faire, on peut :

    • Exécution du fichier d’entrée de test via l’outil de développement et enregistrement du rendu XML (validé).
    <?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. Exécutez aio app test à partir de la racine du projet d'Asset compute pour exécuter toutes les suites de tests.

Déployer le collaborateur sur Adobe I/O Runtime

Pour appeler ce nouveau programme de travail de métadonnées à partir d’AEM Assets, il doit être déployé sur Adobe I/O Runtime à l’aide de la commande :

$ aio app deploy

déploiement de l’application aio

Notez que cela va déployer tous les travailleurs du projet. Consultez les instructions de déploiement complètes pour savoir comment effectuer le déploiement sur les espaces de travail Stage and Production.

Intégration avec les Profils de traitement AEM

Appelez le collaborateur à partir de AEM en créant un nouveau service de Profil de traitement personnalisé ou en modifiant un service existant qui appelle ce collaborateur déployé.

Profil de traitement

  1. Connectez-vous à AEM en tant que service d’auteur Cloud Service en tant qu’AEM Administrator
  2. Accédez à Outils > Ressources > Profils de traitement
  3. ____ Créer un nouveau Profil de traitement, ou ____ modifier et existant
  4. Appuyez sur l’onglet Personnalisé, puis sur Ajouter nouveau.
  5. Définir le nouveau service
    • Créer un rendu de métadonnées : Basculer vers principal
    • Point de terminaison : https://...adobeioruntime.net/api/v1/web/wkndAemAssetCompute-0.0.1/metadata-colors
      • Il s’agit de l’URL du collaborateur obtenu lors du déploiement deploy ou à l’aide de la commande aio app get-url. Assurez-vous que l’URL pointe vers l’espace de travail approprié en fonction de l’AEM en tant qu’environnement Cloud Service.
    • Paramètres de service
      • Appuyez sur Paramètre d'Ajoute.
        • Clé: colorFamily
        • Valeur : pantone
          • Valeurs prises en charge : basic, hex, html, ntc, pantone, roygbiv
    • Types MIME
      • Inclut: image/jpeg, image/png, image/gif, image/svg
        • Il s'agit des seuls types MIME pris en charge par les modules npm tiers utilisés pour dériver les couleurs.
      • Exclure : Leave blank
  6. Appuyez sur Enregistrer en haut à droite.
  7. Appliquer le Profil de traitement à un dossier AEM Assets si ce n’est pas déjà fait

Mettre à jour le Schéma de métadonnées

Pour consulter les métadonnées des couleurs, associez deux nouveaux champs du schéma de métadonnées de l’image aux nouvelles propriétés de données de métadonnées que le programme de travail remplit.

Schéma de métadonnées

  1. Dans le service AEM Author, accédez à Outils > Actifs > Schémas de métadonnées
  2. Accédez à default, sélectionnez et modifiez image et ajoutez des champs de formulaire en lecture seule pour exposer les métadonnées de couleur générées.
  3. Ajouter un texte d’une seule ligne
    • Libellé du champ: Colors Family
    • Associer à la propriété: ./jcr:content/metadata/wknd:colorsFamily
    • Règles > Champ > Désactiver la modification : Coché
  4. Ajouter un texte à plusieurs valeurs
    • Libellé du champ: Colors
    • Associer à la propriété: ./jcr:content/metadata/wknd:colors
  5. Appuyez sur Enregistrer en haut à droite.

Traitement des fichiers

Détails de la ressource

  1. Dans le service Auteur AEM, accédez à Ressources > Fichiers
  2. Accédez au dossier, ou sous-dossier, auquel le Profil de traitement est appliqué
  3. Téléchargez une nouvelle image (JPEG, PNG, GIF ou SVG) dans le dossier ou retraitez les images existantes à l’aide du Profil de traitement mis à jour.
  4. Une fois le traitement terminé, sélectionnez le fichier, puis appuyez sur propriétés dans la barre d’actions supérieure pour afficher ses métadonnées.
  5. Examinez les champs de métadonnées Colors Family et Colors pour connaître les métadonnées écrites à partir du programme de travail de métadonnées d'Asset compute personnalisé.

Avec les métadonnées en couleur écrites sur les métadonnées de la ressource, sur la ressource [dam:Asset]/jcr:content/metadata, ces métadonnées sont indexées, ce qui augmente la capacité de découverte de la ressource à l’aide de ces termes par le biais de la recherche, et elles peuvent même être réécrites au binaire de la ressource si le flux de travail de récupération des métadonnées DAM est appelé dessus.

Rendu des métadonnées en AEM Assets

Fichier de rendu de métadonnées AEM Assets

Le fichier XMP réel généré par le programme de travail des métadonnées de l’Asset compute est également stocké en tant que rendu distinct sur la ressource. Ce fichier n’est généralement pas utilisé, mais les valeurs appliquées au noeud de métadonnées du fichier sont utilisées, mais la sortie XML brute du programme de travail est disponible dans AEM.

code de travail de métadonnées-couleurs sur Github

Le metadata-colors/index.js final est disponible sur Github à l'adresse suivante :

La dernière suite de tests test/asset-compute/metadata-colors est disponible sur Github à l'adresse suivante :

Sur cette page

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free