Documentation AEM Tutoriels AEM Tutoriels d’AEM as a Cloud Service

Comment appeler les API d’AEM OpenAPI invoke-openapi-based-aem-apis

Last update: Wed Nov 20 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Rubriques :
Développement

Créé pour :

Débutant
Développeur
Leader

Découvrez comment configurer et appeler des API d’AEM OpenAPI sur AEM as a Cloud Service à partir d’applications personnalisées.

AVAILABILITY

Les API d’AEM OpenAPI sont disponibles dans le cadre d’un programme d’accès anticipé. Si vous souhaitez y accéder, nous vous encourageons à envoyer un email aem-apis@adobe.com avec une description de votre cas d’utilisation.

Dans ce tutoriel, vous apprenez à :

Activez l’accès aux API d’AEM OpenAPI pour votre environnement AEM as a Cloud Service.
Créez et configurez un projet Adobe Developer Console (ADC) pour accéder aux API AEM à l’aide de l’authentification OAuth serveur à serveur.
Développez un exemple d’application NodeJS qui appelle l’API d’auteur Assets pour récupérer les métadonnées d’une ressource spécifique.

Avant de commencer, veillez à consulter la section Accès aux API d’Adobe et aux concepts associés .

Conditions préalables

Les éléments suivants sont requis afin de terminer ce tutoriel :

Environnement AEM as a Cloud Service modernisé avec les éléments suivants :
- AEM version 2024.10.18459.20241031T210302Z ou ultérieure.
- Nouveau style de profils de produit (si l’environnement a été créé avant novembre 2024)
L’exemple de projet WKND Sites doit être déployé sur celui-ci.
Accès à Adobe Developer Console.
Installez Node.js sur votre ordinateur local pour exécuter l’exemple d’application NodeJS.

Étapes de développement

Les étapes de développement générales sont les suivantes :

Modernisation de l’environnement AEM as a Cloud Service.
Activez l’accès aux API d’AEM.
Créez un projet Adobe Developer Console (ADC).
Configuration du projet ADC
1. Ajout des API d’AEM souhaitées
2. Configurer son authentification
3. Association du profil de produit à la configuration de l’authentification
Configuration de l’instance AEM pour activer la communication du projet ADC
Développement d’un exemple d’application NodeJS
Vérification du flux de bout en bout

Modernisation de l’environnement AEM as a Cloud Service

Commençons par moderniser l’environnement AEM as a Cloud Service. Cette étape n’est nécessaire que si l’environnement n’est pas modernisé.

La modernisation de l'environnement AEM as a Cloud Service est un processus en deux étapes,

Mise à jour vers la dernière version AEM
Ajoutez-y de nouveaux profils de produit.

Mise à jour de l’instance AEM

Pour mettre à jour l’instance AEM, dans la section Environments de l’Adobe Cloud Manager, sélectionnez l’icône ellipsis en regard du nom de l’environnement et sélectionnez l’option Mettre à jour .

Mettre à jour l’instance AEM

Cliquez ensuite sur le bouton Submit et exécutez le pipeline Fullstack suggéré.

Sélectionner la dernière version AEM version

Dans mon cas, le nom du pipeline Fullstack est Dev :: Fullstack-Deploy et le nom de l’environnement d’AEM est wknd-program-dev, il peut varier dans votre cas.

Ajouter de nouveaux profils de produit

Pour ajouter de nouveaux profils de produit à l’instance AEM, dans la section Environments de l’Adobe Cloud Manager, sélectionnez l’icône ellipsis en regard du nom de l’environnement et sélectionnez l’option Ajouter des profils de produit.

Ajouter de nouveaux profils de produit

Vous pouvez passer en revue les profils de produit nouvellement ajoutés en cliquant sur l’icône ellipsis en regard du nom de l’environnement et en sélectionnant Gérer l’accès > Profils d’auteur.

La fenêtre Admin Console affiche les profils de produit nouvellement ajoutés.

Vérification de nouveaux profils de produit

Les étapes ci-dessus terminent la modernisation de l’environnement AEM as a Cloud Service.

Activation de l’accès aux API d’AEM

Les nouveaux profils de produit permettent l’accès aux API d’AEM OpenAPI dans Adobe Developer Console (ADC).

Les profils de produit nouvellement ajoutés sont associés aux Services qui représentent AEM groupes d’utilisateurs avec des listes de contrôle d’accès prédéfinies (ACL). Les Services sont utilisés pour contrôler le niveau d’accès aux API AEM.

Vous pouvez également sélectionner ou désélectionner les Services associés au profil de produit pour réduire ou augmenter le niveau d’accès.

Vérifiez l’association en cliquant sur l’icône Afficher les détails en regard du nom du profil du produit.

Services de révision associés au profil de produit

Par défaut, le service Utilisateurs de l’API AEM Assets n’est associé à aucun profil de produit. Associons-le au tout nouveau AEM Administrateurs - Auteur - Programme XXX - Environnement XXX Profil produit. Après cette association, l’ API d’auteur de ressources du projet ADC peut configurer l’authentification OAuth serveur à serveur et associer le compte d’authentification au profil de produit.

Associer le service utilisateurs de l’API AEM Assets au profil de produit

Il est important de noter qu’avant la modernisation, dans l’instance d’auteur AEM, deux profils de produit étaient disponibles, AEM Administrateurs-XXX et Utilisateurs-XXX. Il est également possible d’associer ces profils de produit existants aux nouveaux services.

Créer un projet Adobe Developer Console (ADC)

Créez ensuite un projet ADC pour accéder aux API AEM.

Connectez-vous à Adobe Developer Console à l’aide de votre Adobe ID.
Dans la section Démarrage rapide , cliquez sur le bouton Créer un projet .
Il crée un projet portant le nom par défaut.
Modifiez le nom du projet en cliquant sur le bouton Modifier le projet dans le coin supérieur droit. Attribuez un nom significatif et cliquez sur Enregistrer.

Configuration du projet ADC

Ensuite, configurez le projet ADC pour ajouter AEM API, configurer son authentification et associer le profil de produit.

Pour ajouter des API AEM, cliquez sur le bouton Ajouter une API.
Dans la boîte de dialogue Ajouter une API, filtrez par Experience Cloud et sélectionnez la carte AEM Assets Author API et cliquez sur Suivant.
Ensuite, dans la boîte de dialogue Configurer l'API, sélectionnez l'option d'authentification Serveur à serveur et cliquez sur Suivant. L’authentification serveur à serveur est idéale pour les services principaux nécessitant un accès à l’API sans interaction de l’utilisateur.
Renommez les informations d’identification pour une identification plus facile (si nécessaire) et cliquez sur Suivant. À des fins de démonstration, le nom par défaut est utilisé.
Sélectionnez le profil de produit AEM Administrateurs - Auteur - Programme XXX - Environnement XXX et cliquez sur Enregistrer. Comme vous pouvez le constater, seul le profil de produit associé au service Utilisateurs de l’API AEM Assets peut être sélectionné.
Passez en revue l’API AEM et la configuration de l’authentification.

Configuration de l’instance AEM pour activer la communication du projet ADC

Pour activer l’ID d’identification client OAuth du projet ADC pour communiquer avec l’instance AEM, vous devez configurer l’instance AEM.

Pour ce faire, définissez la configuration dans le fichier config.yaml du projet AEM. Déployez ensuite le fichier config.yaml à l’aide du pipeline de configuration dans Cloud Manager.

Dans AEM Projet, recherchez ou créez le fichier config.yaml à partir du dossier config.

Ajoutez la configuration suivante au fichier config.yaml.

code language-yaml
`kind: "API" version: "1.0" metadata: envTypes: ["dev", "stage", "prod"] data: allowedClientIDs: author: - "<ADC Project's OAuth Server-to-Server credential ClientID>"`

Remplacez <ADC Project's OAuth Server-to-Server credential ClientID> par l’ID client réel des informations d’identification OAuth Server-to-Server du projet ADC. Le point de terminaison d’API utilisé dans ce tutoriel est disponible uniquement sur le niveau auteur, mais pour les autres API, la configuration yaml peut également avoir un noeud publish ou preview .

Validez les modifications de configuration dans le référentiel Git et poussez les modifications dans le référentiel distant.
Déployez les modifications ci-dessus à l’aide du pipeline de configuration dans Cloud Manager. Notez que le fichier config.yaml peut également être installé dans un RDE, à l’aide de l’outil de ligne de commande.

Développement d’un exemple d’application NodeJS

Développons un exemple d’application NodeJS qui appelle l’API d’auteur Assets.

Vous pouvez utiliser d’autres langages de programmation tels que Java, Python, etc., pour développer l’application.

À des fins de test, vous pouvez utiliser Postman, curl ou tout autre client REST pour appeler les API AEM.

Vérification de l’API

Avant de développer l’application, examinons la diffusion du point de terminaison de métadonnées de la ressource spécifiée à partir de l’ API d’auteur Assets. La syntaxe de l’API est la suivante :

GET https://{bucket}.adobeaemcloud.com/adobe/assets/{assetId}/metadata

Pour récupérer les métadonnées d’une ressource spécifique, vous avez besoin des valeurs bucket et assetId . bucket est le nom de l’instance AEM sans le nom de domaine de l’Adobe (.adobeaemcloud.com), par exemple, author-p63947-e1420428.

assetId est l’UUID JCR de la ressource avec le préfixe urn:aaid:aem:, par exemple urn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da. Il existe plusieurs méthodes pour obtenir le assetId :

Ajoutez l’extension AEM chemin d’accès aux ressources .json pour obtenir les métadonnées des ressources. Par exemple, https://author-p63947-e1420429.adobeaemcloud.com/content/dam/wknd-shared/en/adventures/cycling-southern-utah/adobestock-221043703.jpg.json et recherchez la propriété jcr:uuid.
Vous pouvez également obtenir le assetId en examinant la ressource dans l’Inspecteur d’éléments du navigateur. Recherchez l’attribut data-id="urn:aaid:aem:..." .

Appel de l’API à l’aide du navigateur

Avant de développer l’application, appelez l’API à l’aide de la fonction Essayer de la documentation de l’API.

Ouvrez la documentation de l’API d’auteur Assets dans le navigateur.
Développez la section Métadonnées et cliquez sur l’option Diffuse les métadonnées de la ressource spécifiée .
Dans le volet de droite, cliquez sur le bouton Essayer .
Saisissez les valeurs suivantes :
1. La valeur bucket est le nom de l’instance AEM sans le nom de domaine de l’Adobe (.adobeaemcloud.com), par exemple, author-p63947-e1420428.
2. Les valeurs Security associées Bearer Token et X-Api-Key sont obtenues à partir des informations d’identification OAuth Server-to-Server du projet ADC. Cliquez sur Générer le jeton d’accès pour obtenir la valeur Bearer Token et utiliser la valeur ClientID comme X-Api-Key.
3. La valeur Parameters associée assetId est l’identifiant unique de la ressource dans AEM. X-Adobe-Accept-Experimental est défini sur 1.
Cliquez sur Send pour appeler l’API.
Passez en revue l’onglet Réponse pour voir la réponse de l’API.

Les étapes ci-dessus confirment la modernisation de l’environnement AEM as a Cloud Service, ce qui permet l’accès aux API d’AEM. Cela confirme également la configuration réussie du projet ADC et la communication d’identifiant client ID OAuth serveur à serveur avec l’instance d’auteur AEM.

Exemple d’application NodeJS

Développons un exemple d’application NodeJS.

Pour développer l’application, vous pouvez utiliser les instructions Run-the-sample-application ou Step-by-step-development.

Run-the-sample-application

Téléchargez l’exemple de fichier zip d’application demo-nodejs-app-to-invoke-aem-openapi et extrayez-le.

Accédez au dossier extrait et installez les dépendances.

code language-bash
`$ npm install`

Remplacez les espaces réservés dans le fichier .env par les valeurs réelles des informations d’identification OAuth Server-to-Server du projet ADC.
Remplacez <BUCKETNAME> et <ASSETID> dans le fichier src/index.js par les valeurs réelles.

Exécutez l’application NodeJS.

code language-bash
`$ node src/index.js`

Développement pas à pas

Créez un projet NodeJS.

code language-bash
`$ mkdir demo-nodejs-app-to-invoke-aem-openapi $ cd demo-nodejs-app-to-invoke-aem-openapi $ npm init -y`

Installez la bibliothèque fetch et dotenv pour effectuer des requêtes HTTP et lire respectivement les variables d’environnement.

code language-bash
`$ npm install node-fetch $ npm install dotenv`

Ouvrez le projet dans votre éditeur de code préféré et mettez à jour le fichier package.json pour ajouter type à module.

code language-json
`{ ... "version": "1.0.0", "type": "module", "main": "index.js", ... }`

Créez le fichier .env et ajoutez la configuration suivante. Remplacez les espaces réservés par les valeurs réelles des informations d’identification OAuth Server-to-Server du projet ADC.

code language-properties

code language-properties
`CLIENT_ID=<ADC Project OAuth Server-to-Server credential ClientID> CLIENT_SECRET=<ADC Project OAuth Server-to-Server credential Client Secret> SCOPES=<ADC Project OAuth Server-to-Server credential Scopes>`

CLIENT_ID=<ADC Project OAuth Server-to-Server credential ClientID>
CLIENT_SECRET=<ADC Project OAuth Server-to-Server credential Client Secret>
SCOPES=<ADC Project OAuth Server-to-Server credential Scopes>

Créez le fichier src/index.js et ajoutez le code suivant, puis remplacez <BUCKETNAME> et <ASSETID> par les valeurs réelles.

code language-javascript

code language-javascript
// Import the dotenv configuration to load environment variables from the .env file import "dotenv/config"; // Import the fetch function to make HTTP requests import fetch from "node-fetch"; // REPLACE THE FOLLOWING VALUES WITH YOUR OWN const bucket = "<BUCKETNAME>"; // Bucket name is the AEM instance name (e.g. author-p63947-e1420428) const assetId = "<ASSETID>"; // Asset ID is the unique identifier for the asset in AEM (e.g. urn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da). You can get it by inspecting the asset in browser's element inspector, look for data-id="urn:aaid:aem:..." // Load environment variables for authentication const clientId = process.env.CLIENT_ID; // Adobe IMS client ID const clientSecret = process.env.CLIENT_SECRET; // Adobe IMS client secret const scopes = process.env.SCOPES; // Scope for the API access // Adobe IMS endpoint for obtaining an access token const adobeIMSV3TokenEndpointURL = "https://ims-na1.adobelogin.com/ims/token/v3"; // Function to obtain an access token from Adobe IMS const getAccessToken = async () => { console.log("Getting access token from IMS"); // Log process initiation //console.log("Client ID: " + clientId); // Display client ID for debugging purposes // Configure the HTTP POST request to fetch the access token const options = { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded", // Specify form data content type }, // Send client ID, client secret, and scopes as the request body body: `grant_type=client_credentials&client_id=${clientId}&client_secret=${clientSecret}&scope=${scopes}`, }; // Make the HTTP request to fetch the access token const response = await fetch(adobeIMSV3TokenEndpointURL, options); //console.log("Response status: " + response.status); // Log the HTTP status for debugging const responseJSON = await response.json(); // Parse the JSON response console.log("Access token received"); // Log success message // Return the access token return responseJSON.access_token; }; // Function to retrieve metadata for a specific asset from AEM const getAssetMetadat = async () => { // Fetch the access token using the getAccessToken function const accessToken = await getAccessToken(); console.log("Getting asset metadata from AEM"); // Invoke the Assets Author API to retrieve metadata for a specific asset const resp = await fetch( `https://${bucket}.adobeaemcloud.com/adobe/assets/${assetId}/metadata`, // Construct the URL with bucket and asset ID { method: "GET", headers: { "If-None-Match": "string", // Header to handle caching (not critical for this tutorial) "X-Adobe-Accept-Experimental": "1", // Header to enable experimental Adobe API features Authorization: "Bearer " + accessToken, // Provide the access token for authorization "X-Api-Key": clientId, // Include the OAuth S2S ClientId for identification }, } ); const data = await resp.json(); // Parse the JSON response console.log("Asset metadata received"); // Log success message console.log(data); // Display the retrieved metadata }; // Call the getAssets function to start the process getAssetMetadat();

// Import the dotenv configuration to load environment variables from the .env file
import "dotenv/config";

// Import the fetch function to make HTTP requests
import fetch from "node-fetch";

// REPLACE THE FOLLOWING VALUES WITH YOUR OWN
const bucket = "<BUCKETNAME>"; // Bucket name is the AEM instance name (e.g. author-p63947-e1420428)
const assetId = "<ASSETID>"; // Asset ID is the unique identifier for the asset in AEM (e.g. urn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da). You can get it by inspecting the asset in browser's element inspector, look for data-id="urn:aaid:aem:..."

// Load environment variables for authentication
const clientId = process.env.CLIENT_ID; // Adobe IMS client ID
const clientSecret = process.env.CLIENT_SECRET; // Adobe IMS client secret
const scopes = process.env.SCOPES; // Scope for the API access

// Adobe IMS endpoint for obtaining an access token
const adobeIMSV3TokenEndpointURL =
"https://ims-na1.adobelogin.com/ims/token/v3";

// Function to obtain an access token from Adobe IMS
const getAccessToken = async () => {
    console.log("Getting access token from IMS"); // Log process initiation
    //console.log("Client ID: " + clientId); // Display client ID for debugging purposes

    // Configure the HTTP POST request to fetch the access token
    const options = {
        method: "POST",
        headers: {
        "Content-Type": "application/x-www-form-urlencoded", // Specify form data content type
        },
        // Send client ID, client secret, and scopes as the request body
        body: `grant_type=client_credentials&client_id=${clientId}&client_secret=${clientSecret}&scope=${scopes}`,
    };

    // Make the HTTP request to fetch the access token
    const response = await fetch(adobeIMSV3TokenEndpointURL, options);

    //console.log("Response status: " + response.status); // Log the HTTP status for debugging

    const responseJSON = await response.json(); // Parse the JSON response

    console.log("Access token received"); // Log success message

    // Return the access token
    return responseJSON.access_token;
};

// Function to retrieve metadata for a specific asset from AEM
const getAssetMetadat = async () => {
    // Fetch the access token using the getAccessToken function
    const accessToken = await getAccessToken();

    console.log("Getting asset metadata from AEM");

    // Invoke the Assets Author API to retrieve metadata for a specific asset
    const resp = await fetch(
        `https://${bucket}.adobeaemcloud.com/adobe/assets/${assetId}/metadata`, // Construct the URL with bucket and asset ID
        {
        method: "GET",
        headers: {
            "If-None-Match": "string", // Header to handle caching (not critical for this tutorial)
            "X-Adobe-Accept-Experimental": "1", // Header to enable experimental Adobe API features
            Authorization: "Bearer " + accessToken, // Provide the access token for authorization
            "X-Api-Key": clientId, // Include the OAuth S2S ClientId for identification
        },
        }
    );

    const data = await resp.json(); // Parse the JSON response

    console.log("Asset metadata received"); // Log success message
    console.log(data); // Display the retrieved metadata
};

// Call the getAssets function to start the process
getAssetMetadat();

Exécutez l’application NodeJS.

code language-bash
`$ node src/index.js`

Réponse de l’API

Une fois l’exécution terminée, la réponse de l’API s’affiche dans la console. La réponse contient les métadonnées de la ressource spécifiée.

{
  "assetId": "urn:aaid:aem:9c09ff70-9ee8-4b14-a5fa-ec37baa0d1b3",
  "assetMetadata": {
    ...
    "dc:title": "A Young Mountain Biking Couple Takes A Minute To Take In The Scenery",
    "xmp:CreatorTool": "Adobe Photoshop Lightroom Classic 7.5 (Macintosh)",
    ...
  },
  "repositoryMetadata": {
    ...
    "repo:name": "adobestock-221043703.jpg",
    "repo:path": "/content/dam/wknd-shared/en/adventures/cycling-southern-utah/adobestock-221043703.jpg",
    "repo:state": "ACTIVE",
    ...
  }
}

Félicitations. Vous avez correctement appelé les API AEM OpenAPI de votre application personnalisée à l’aide de l’authentification OAuth serveur à serveur.

Vérification du code de l’application

Les légendes clés de l’exemple de code d’application NodeJS sont les suivantes :

Authentification IMS : récupère un jeton d’accès à l’aide des informations d’identification OAuth Server-to-Server configurées dans le projet ADC.

code language-javascript

code language-javascript
// Function to obtain an access token from Adobe IMS const getAccessToken = async () => { // Configure the HTTP POST request to fetch the access token const options = { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded", // Specify form data content type }, // Send client ID, client secret, and scopes as the request body body: `grant_type=client_credentials&client_id=${clientId}&client_secret=${clientSecret}&scope=${scopes}`, }; // Make the HTTP request to fetch the access token from Adobe IMS token endpoint https://ims-na1.adobelogin.com/ims/token/v3 const response = await fetch(adobeIMSV3TokenEndpointURL, options); const responseJSON = await response.json(); // Parse the JSON response // Return the access token return responseJSON.access_token; }; ...

// Function to obtain an access token from Adobe IMS
const getAccessToken = async () => {

    // Configure the HTTP POST request to fetch the access token
    const options = {
        method: "POST",
        headers: {
        "Content-Type": "application/x-www-form-urlencoded", // Specify form data content type
        },
        // Send client ID, client secret, and scopes as the request body
        body: `grant_type=client_credentials&client_id=${clientId}&client_secret=${clientSecret}&scope=${scopes}`,
    };

    // Make the HTTP request to fetch the access token from Adobe IMS token endpoint https://ims-na1.adobelogin.com/ims/token/v3
    const response = await fetch(adobeIMSV3TokenEndpointURL, options);

    const responseJSON = await response.json(); // Parse the JSON response

    // Return the access token
    return responseJSON.access_token;
};
...

Appel d’API : appelle l’API d’auteur Assets pour récupérer les métadonnées d’une ressource spécifique en fournissant le jeton d’accès pour autorisation.

code language-javascript

code language-javascript
// Function to retrieve metadata for a specific asset from AEM const getAssetMetadat = async () => { // Fetch the access token using the getAccessToken function const accessToken = await getAccessToken(); console.log("Getting asset metadata from AEM"); // Invoke the Assets Author API to retrieve metadata for a specific asset const resp = await fetch( `https://${bucket}.adobeaemcloud.com/adobe/assets/${assetId}/metadata`, // Construct the URL with bucket and asset ID { method: "GET", headers: { "If-None-Match": "string", // Header to handle caching (not critical for this tutorial) "X-Adobe-Accept-Experimental": "1", // Header to enable experimental Adobe API features Authorization: "Bearer " + accessToken, // Provide the access token for authorization "X-Api-Key": clientId, // Include the OAuth S2S ClientId for identification }, } ); const data = await resp.json(); // Parse the JSON response console.log("Asset metadata received"); // Log success message console.log(data); // Display the retrieved metadata }; ...

// Function to retrieve metadata for a specific asset from AEM
const getAssetMetadat = async () => {
    // Fetch the access token using the getAccessToken function
    const accessToken = await getAccessToken();

    console.log("Getting asset metadata from AEM");

    // Invoke the Assets Author API to retrieve metadata for a specific asset
    const resp = await fetch(
        `https://${bucket}.adobeaemcloud.com/adobe/assets/${assetId}/metadata`, // Construct the URL with bucket and asset ID
        {
        method: "GET",
        headers: {
            "If-None-Match": "string", // Header to handle caching (not critical for this tutorial)
            "X-Adobe-Accept-Experimental": "1", // Header to enable experimental Adobe API features
            Authorization: "Bearer " + accessToken, // Provide the access token for authorization
            "X-Api-Key": clientId, // Include the OAuth S2S ClientId for identification
        },
        }
    );

    const data = await resp.json(); // Parse the JSON response

    console.log("Asset metadata received"); // Log success message
    console.log(data); // Display the retrieved metadata
};
...

Résumé

Dans ce tutoriel, vous avez appris à appeler des API AEM OpenAPI à partir d’applications personnalisées. Vous avez activé AEM accès aux API, créé et configuré un projet Adobe Developer Console (ADC).
Dans le projet ADC, vous avez ajouté les API AEM, configuré son type d’authentification et associé le profil de produit. Vous avez également configuré l’instance AEM pour activer la communication du projet ADC et développé un exemple d’application NodeJS qui appelle l’API d’auteur Assets.

recommendation-more-help

4859a77c-7971-4ac9-8f5c-4260823c6f69