Entwickeln eines Asset compute-Metadaten-Sekundärs

Benutzerdefinierte Asset compute-Sekundäre können XMP (XML) Daten erstellen, die zurück an AEM gesendet und als Metadaten für ein Asset gespeichert werden.

Häufige Anwendungsfälle sind:

  • Integrationen mit Drittanbietersystemen, z. B. einem PIM (Product Information Management System), bei dem zusätzliche Metadaten abgerufen und im Asset gespeichert werden müssen
  • Integrationen mit Adobe-Diensten, z. B. Inhalts- und Commerce-KI, um Asset-Metadaten mit zusätzlichen Attributen für maschinelles Lernen zu ergänzen
  • Ableiten von Metadaten zum Asset aus seiner Binärdatei und Speichern als Asset-Metadaten in AEM als Cloud Service

Was Sie tun werden

In diesem Tutorial erstellen wir einen Asset compute Metadaten-Worker, der die am häufigsten verwendeten Farben in einem Bild-Asset ableitet und die Farbnamen in die Metadaten des Assets in AEM schreibt. Obwohl das Sekundärprogramm selbst einfach ist, wird in diesem Tutorial untersucht, wie Asset compute-Sekundärprogramme zum Zurückschreiben von Metadaten in Assets in AEM als Cloud Service verwendet werden können.

Logischer Ablauf eines Asset compute-Metadaten-Worker-Aufrufs

Der Aufruf von Asset compute-Metadatenarbeitern ist fast identisch mit dem von binäre Ausgabedarstellung, die Sekundäre generiert, wobei der Hauptunterschied der Rückgabetyp ist eine XMP (XML)-Ausgabedarstellung, deren Werte auch in die Metadaten des Assets geschrieben werden.

asset compute-Worker implementieren den Asset compute SDK Worker API-Vertrag in der renditionCallback(...)-Funktion, die konzeptionell lautet:

  • Eingabe: Die ursprünglichen binären Parameter und Verarbeitungsprofil eines AEM Assets
  • Ausgabe: Eine XMP (XML)-Ausgabedarstellung, die als Ausgabedarstellung am AEM Asset und den Metadaten des Assets beibehalten wird

Logischer Ablauf des asset compute-Metadaten-Workflows

  1. Der AEM-Autorendienst ruft den Asset compute-Metadaten-Worker auf und stellt die (1a) ursprüngliche Binärdatei des Assets sowie (1b) alle im Verarbeitungsprofil definierten Parameter bereit.
  2. Das Asset compute SDK orchestriert die Ausführung der renditionCallback(...)-Funktion des benutzerdefinierten Asset compute-Metadatenarbeiters und leitet eine XMP (XML)-Ausgabedarstellung ab, die auf der binären (1a)-Binärdatei des Assets und allen Verarbeitungsprofilparametern (1b) basiert.
  3. Der Asset compute Worker speichert die XMP (XML)-Darstellung in rendition.path.
  4. Die XMP (XML)-Daten, die in rendition.path geschrieben wurden, werden über das Asset compute SDK an den AEM-Autorendienst übertragen und als (4a) Textausgabe und (4b) im Metadatenknoten des Assets gespeichert.

Konfigurieren von manifest.yml

Alle Asset compute-Sekundäre müssen in manifest.yml registriert sein.

Öffnen Sie die manifest.yml des Projekts und fügen Sie einen Worker-Eintrag hinzu, der den neuen Worker konfiguriert, in diesem Fall metadata-colors.

Beachten Sie, dass .yml Whitespace-Einstellungen berücksichtigt werden.

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 verweist auf die Worker-Implementierung, die im nächsten Schritt erstellt wurde. Benennen Sie Sekundäre semantisch (z. B. actions/worker/index.js wurde besser actions/rendition-circle/index.js genannt), wie sie in der Worker-URL angezeigt werden, und bestimmen Sie auch den Ordner-Namen der Worker-Test-Suite.

Die limits und require-adobe-auth werden diskret pro Worker konfiguriert. In diesem Worker wird 512 MB des Speichers zugewiesen, wenn der Code (potenziell) große binäre Bilddaten prüft. Die anderen limits werden entfernt, um Standardwerte zu verwenden.

Entwickeln eines Metadaten-Sekundärs

Erstellen Sie eine neue Metadaten-Worker-JavaScript-Datei im Asset compute-Projekt unter dem Pfad defined manifest.yml für den neuen Worker unter /actions/metadata-colors/index.js

Installieren von npm-Modulen

Installieren Sie die zusätzlichen NPM-Module (@adobe/asset-compute-xmp, get-image-color und color-namer), die in diesem Asset compute Worker verwendet werden.

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

Metadaten-Worker-Code

Dieser Worker sieht dem rendition-generate worker sehr ähnlich. Der Hauptunterschied besteht darin, XMP (XML) Daten in rendition.path zu schreiben, um wieder in AEM gespeichert zu werden.

"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; }
}

Lokales Ausführen des Metadaten-Workers

Wenn der Worker-Code abgeschlossen ist, kann er mit dem lokalen Asset compute Development Tool ausgeführt werden.

Da unser Asset compute-Projekt zwei Sekundärprogramme enthält (das vorherige Kreisausgabeformat und dieses metadata-colors -Sekundärprogramm), listet die Profildefinition des Asset compute-Entwicklungstools Ausführungsprofile für beide Sekundäre auf. Die zweite Profildefinition verweist auf den neuen Worker metadata-colors .

XML-Metadaten-Ausgabe

  1. Aus dem Stammverzeichnis des Asset compute-Projekts

  2. Führen Sie aio app run aus, um das Asset compute Development Tool zu starten.

  3. Wählen Sie im Datei auswählen… Dropdown-Liste wählen Sie ein Beispielbild zur Verarbeitung aus

  4. Aktualisieren Sie in der zweiten Profildefinitionskonfiguration, die auf den Worker metadata-colors verweist, "name": "rendition.xml" , da dieser Worker eine XMP (XML)-Ausgabedarstellung generiert. Optional können Sie einen Parameter colorsFamily hinzufügen (unterstützte Werte basic, hex, html, ntc, pantone, roygbiv).

    {
        "renditions": [
            {
                "worker": "...",
                "name": "rendition.xml",
                "colorsFamily": "pantone"
            }
        ]
    }
    
  5. Tippen Sie auf Ausführen und warten Sie, bis die XML-Ausgabe generiert wird.

    • Da beide Sekundäre in der Profildefinition aufgeführt sind, werden beide Ausgabedarstellungen generiert. Optional kann die obere Profildefinition, die auf den Kreis-Ausgabedarstellungs-Worker verweist, gelöscht werden, um die Ausführung nicht über das Entwicklungstool zu vermeiden.
  6. Im Abschnitt Ausgabeformate wird eine Vorschau der generierten Ausgabedarstellung angezeigt. Tippen Sie auf rendition.xml, um es herunterzuladen, und öffnen Sie es in VS Code (oder Ihrem bevorzugten XML/Texteditor), um es zu überprüfen.

Testen Sie den Worker.

Metadaten-Sekundäre können mit dem gleichen Asset compute-Test-Framework wie binäre Ausgabeformate getestet werden. Der einzige Unterschied ist die rendition.xxx-Datei im Testfall muss die erwartete XMP (XML)-Ausgabedarstellung sein.

  1. Erstellen Sie die folgende Struktur im Asset compute-Projekt:

    /test/asset-compute/metadata-colors/success-pantone/
    
        file.jpg
        params.json
        rendition.xml
    
  2. Verwenden Sie die Beispieldatei a1/> als Testfall file.jpg.

  3. Fügen Sie die folgende JSON zum params.json hinzu.

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

    Beachten Sie, dass "fmt": "xml" erforderlich ist, um die Test-Suite anzuweisen, eine textbasierte Ausgabe zu generieren, die .xml.

  4. Geben Sie die erwartete XML in die Datei rendition.xml ein. Dies erhalten Sie durch:

    • Ausführen der Testeingabedatei über das Entwicklungstool und Speichern der (validierten) XML-Ausgabe.
    <?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. Führen Sie aio app test aus dem Stammverzeichnis des Asset compute-Projekts aus, um alle Test-Suites auszuführen.

Bereitstellen des Sekundärs in Adobe I/O Runtime

Um diesen neuen Metadaten-Worker aus AEM Assets aufzurufen, muss er mithilfe des folgenden Befehls in Adobe I/O Runtime bereitgestellt werden:

$ aio app deploy

aio app deploy

Beachten Sie, dass dadurch alle im Projekt enthaltenen Arbeiter bereitgestellt werden. Überprüfen Sie die ungekürzten Bereitstellungsanweisungen, um zu erfahren, wie Sie in Staging- und Produktionsarbeitsbereichen bereitstellen.

Integration mit AEM Verarbeitungsprofilen

Rufen Sie den Worker von AEM auf, indem Sie einen neuen oder einen vorhandenen benutzerdefinierten Verarbeitungsprofildienst erstellen, der diesen bereitgestellten Worker aufruft.

Verarbeitungsprofil

  1. Melden Sie sich bei AEM als Cloud Service-Autorendienst als AEM Administrator an.
  2. Navigieren Sie zu Tools > Assets > Verarbeitungsprofile .
  3. ____ Erstellen Sie ein neues oder ____ bearbeiten Sie vorhandenes Verarbeitungsprofil.
  4. Tippen Sie auf die Registerkarte Benutzerdefiniert und dann auf Neu hinzufügen
  5. Definieren des neuen Dienstes
    • Erstellen von Metadaten-Ausgabeformaten: Aktivieren
    • Endpunkt: https://...adobeioruntime.net/api/v1/web/wkndAemAssetCompute-0.0.1/metadata-colors
      • Dies ist die URL für den Worker, der während des deploy oder mithilfe des Befehls aio app get-url abgerufen wurde. Stellen Sie sicher, dass die URL auf den richtigen Arbeitsbereich verweist, basierend auf der AEM als Cloud Service-Umgebung.
    • Dienstparameter
      • Tippen Sie auf Parameter hinzufügen
        • Schlüssel: colorFamily
        • Wert: pantone
          • Unterstützte Werte: basic, hex, html, ntc, pantone, roygbiv
    • MIME-Typen
      • Umfasst: image/jpeg, image/png, image/gif, image/svg
        • Dies sind die einzigen MIME-Typen, die von npm-Modulen von Drittanbietern unterstützt werden, die zum Ableiten der Farben verwendet werden.
      • Schließt Folgendes aus: Leave blank
  6. Tippen Sie oben rechts auf Speichern .
  7. Wenden Sie das Verarbeitungsprofil auf einen Ordner "AEM Assets"an, falls nicht bereits geschehen.

Aktualisieren des Metadatenschemas

Um die Farbmetadaten zu überprüfen, ordnen Sie zwei neue Felder im Metadatenschema des Bildes den neuen Metadaten-Eigenschaften zu, die der Worker füllt.

Metadatenschema

  1. Navigieren Sie im AEM-Autorendienst zu Tools > Assets > Metadatenschemata
  2. Navigieren Sie zu default, wählen Sie image aus und bearbeiten Sie sie und fügen Sie schreibgeschützte Formularfelder hinzu, um die generierten Farbmetadaten anzuzeigen.
  3. Fügen Sie einen einzeiligen Text hinzu.
    • Feldbezeichnung: Colors Family
    • Zu Eigenschaft zuordnen: ./jcr:content/metadata/wknd:colorsFamily
    • Regeln > Feld > Bearbeitung deaktivieren: Aktiviert
  4. Fügen Sie einen Mehrwerttext hinzu.
    • Feldbezeichnung: Colors
    • Zu Eigenschaft zuordnen: ./jcr:content/metadata/wknd:colors
  5. Tippen Sie oben rechts auf Speichern .

Verarbeiten von Assets

Asset-Details

  1. Navigieren Sie im AEM-Autorendienst zu Assets > Dateien
  2. Navigieren Sie zum Ordner oder Unterordner, auf den das Verarbeitungsprofil angewendet wird.
  3. Laden Sie ein neues Bild (JPEG, PNG, GIF oder SVG) in den Ordner hoch oder verarbeiten Sie vorhandene Bilder mit dem aktualisierten Verarbeitungsprofil erneut.
  4. Wenn die Verarbeitung abgeschlossen ist, wählen Sie das Asset aus und tippen Sie in der oberen Aktionsleiste auf properties , um dessen Metadaten anzuzeigen
  5. Überprüfen Sie die Felder Colors Family und Colors Metadaten für die Metadaten, die vom benutzerdefinierten Asset compute-Metadaten-Worker zurückgeschrieben wurden.

Nachdem die Farbmetadaten in die Metadaten des Assets geschrieben wurden, werden diese Metadaten in der Ressource [dam:Asset]/jcr:content/metadata indiziert und können mithilfe dieser Begriffe über die Suche besser erkannt werden. Sie können sogar zurück in die Binärdatei des Assets geschrieben werden, wenn dann der Workflow DAM Metadata Writeback aufgerufen wird.

Metadaten-Ausgabedarstellung in AEM Assets

AEM Assets-Metadaten-Ausgabedarstellungsdatei

Die tatsächliche XMP-Datei, die vom Asset compute-Metadaten-Worker generiert wurde, wird ebenfalls als eigenständiges Ausgabeformat für das Asset gespeichert. Diese Datei wird im Allgemeinen nicht verwendet. Stattdessen werden die auf den Metadatenknoten des Assets angewendeten Werte verwendet, aber die XML-Rohausgabe des Workers ist in AEM verfügbar.

Metadaten-Farben-Workercode auf Github

Das endgültige metadata-colors/index.js ist auf Github verfügbar unter:

Die endgültige test/asset-compute/metadata-colors Test-Suite ist auf Github verfügbar unter:

Auf dieser Seite