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

Les objets Worker 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 une ressource.

Cas d’utilisation courants :

• 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 Adobe, tels que Content and Commerce AI pour ajouter des métadonnées de ressources à des attributs d’apprentissage automatique supplémentaires
• Dérivation de métadonnées sur la ressource à partir de son binaire et stockage en tant que métadonnées de ressource dans AEM en tant que Cloud Service

Ce que vous allez faire

Dans ce tutoriel, nous allons créer un objet Worker de métadonnées d’Asset compute qui fournit les couleurs les plus couramment utilisées dans une ressource d’image et qui réécrit les noms des couleurs aux métadonnées de la ressource dans AEM. Bien que le programme de travail lui-même soit élémentaire, ce tutoriel l’utilise pour explorer la manière dont les programmes de travail Asset compute peuvent être utilisés pour écrire des métadonnées sur des ressources dans AEM en tant que Cloud Service.

Flux logique de l’appel d’un objet Worker de métadonnées d’Asset compute

L’appel des objets Worker de métadonnées d’Asset compute est presque identique à celui du rendu binaire générant des objets Worker, 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 de la ressource.

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

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

1. Le service AEM Author appelle le programme de travail des métadonnées d’Asset compute, en fournissant le (1a) binaire d’origine de la ressource, ainsi que (1b) les paramètres définis dans le profil de traitement.
2. Le SDK Asset compute orchestre l’exécution de la fonction renditionCallback(...) du programme de travail des métadonnées d’Asset compute personnalisée, en dérivant un rendu XMP (XML), en fonction du binaire (1a) de la ressource et des paramètres de profil de traitement (1b).
3. Le programme de travail 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 d’Asset compute vers le service d’auteur AEM et l’exposent sous la forme (4a) d’un rendu texte et (4b) conservées dans le noeud de métadonnées de la ressource.

Configuration du fichier manifest.yml

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

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

N’oubliez pas .yml que est sensible aux espaces.

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 programme de travail créée à l’étape suivante. Nommez sémantiquement les programmes de travail (par exemple, actions/worker/index.js aurait pu être mieux nommé actions/rendition-circle/index.js), comme ils s’affichent dans l’URL du programme de travail et déterminez également le nom de dossier de la suite de tests du programme de travail.

limits et require-adobe-auth sont configurés discrètement par programme de travail. Dans ce programme de travail, 512 MB de la mémoire est allouée lorsque le code inspecte (potentiellement) de grandes données d’image binaire. Les autres limits sont supprimés pour utiliser les valeurs par défaut.

Développement d’un objet Worker de métadonnées

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

Installation des modules npm

Installez les modules npm supplémentaires (@adobe/asset-compute-xmp, get-image-couleurs et color-namer) qui seront utilisés dans ce programme de travail des Assets 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é dans 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écution locale du traitement des métadonnées

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 programmes de travail (l’ancien rendu cercle et ce programme de travail metadata-colors), la définition de profil de l’outil de développement des Assets compute 🔗 répertorie les profils d’exécution pour les deux programmes de travail. La seconde définition de profil pointe vers le nouveau programme de travail metadata-colors.

1. À partir de la racine du projet Asset compute

2. Exécutez aio app run pour démarrer l’outil de développement d’Asset compute.

3. Dans la section Sélectionner un fichier… dans la liste déroulante, sélectionnez un exemple d’image à 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 basic, hex, html, ntc, pantone, roygbiv).

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

5. Appuyez sur Exécuter et attendez que le rendu XML soit généré.

   • Les deux programmes de travail é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érieure pointant vers le objet de rendu cercle peut être supprimée, afin d’éviter de l’exécuter à partir de l’outil de développement.

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

Test du programme de travail

Les objets Worker 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 le cas du test doit être le rendu XMP (XML) attendu.

1. Créez la structure suivante dans le projet 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 à la balise 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 textuel .xml.

4. Fournissez le code XML attendu dans le fichier rendition.xml. Pour ce faire, vous pouvez :

   • 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 Asset compute pour exécuter toutes les suites de test.

Déploiement du programme de travail sur Adobe I/O Runtime

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

$ aio app deploy

Notez que tous les programmes de travail seront déployés dans le projet. Consultez les instructions de déploiement complètes pour savoir comment déployer vers les espaces de travail d’évaluation et de production.

Intégration aux profils de traitement AEM

Appelez le programme de travail à partir d’AEM en créant ou en modifiant un service de profil de traitement personnalisé existant qui appelle ce programme de travail déployé.

1. Connectez-vous à AEM en tant que service de création de Cloud Service en tant qu’ AEM administrateur
2. Accédez à Outils > Ressources > Profils de traitement
3. ____ Créez un profil de traitement, ou ____ modifiez-le 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 d’entrée : https://...adobeioruntime.net/api/v1/web/wkndAemAssetCompute-0.0.1/metadata-colors
     • Il s’agit de l’URL du programme de travail obtenue pendant le déploiement ou à l’aide de la commande aio app get-url. Assurez-vous que l’URL pointe vers l’espace de travail correct en fonction de l’environnement AEM as a Cloud Service.
   • Paramètres de service
     • Appuyez sur Ajouter un paramètre.
       • 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.
     • Exclut : Leave blank
6. Appuyez sur Enregistrer en haut à droite.
7. Application du profil de traitement à un dossier AEM Assets si ce n’est pas déjà fait

Mise à jour du schéma de métadonnées

Pour passer en revue les métadonnées des couleurs, mappez deux nouveaux champs du schéma de métadonnées de l’image avec les nouvelles propriétés de données de métadonnées renseignées par le programme de travail.

1. Dans le service AEM Author, accédez à Outils > Ressources > 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ée
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 ressources

1. Dans le service AEM Author, accédez à Ressources > Fichiers
2. Accédez au dossier, ou sous-dossier, auquel le profil de traitement est appliqué.
3. 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 la ressource et appuyez sur properties dans la barre d’actions supérieure pour afficher ses métadonnées.
5. Vérifiez les Colors Family et Colors champs de métadonnées pour 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 dans 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 ressources à l’aide de ces termes par le biais de la recherche. Elles peuvent même être réécrites dans le binaire de la ressource si le workflow Écriture différée des métadonnées de gestion des actifs numériques est appelé dessus.

Rendu des métadonnées dans AEM Assets

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

code de traitement des couleurs de métadonnées sur Github

Le dernier metadata-colors/index.js est disponible sur Github à l’adresse :

• aem-guides-wknd-asset-compute/actions/metadata-colors/index.js

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

• aem-guides-wknd-asset-compute/test/asset-compute/metadata-couleurs