Événements AEM Assets pour l’intégration PIM
Découvrez comment recevoir un événement AEM et agir sur celui-ci pour mettre à jour l’état du contenu dans AEM à l’aide de l’API de création Assets basée sur OpenAPI.
Le traitement de l’événement reçu dépend des besoins de l’entreprise. Par exemple, les données d’événement peuvent être utilisées pour mettre à jour le système tiers, AEM, ou les deux.
Cet exemple montre comment un système tiers, tel qu’un système de gestion des informations sur les produits (PIM), peut être intégré à AEM as a Cloud Service Assets. Lors de la réception d’un événement AEM Assets, il est traité pour récupérer des métadonnées supplémentaires à partir du système PIM et mettre à jour les métadonnées de la ressource dans AEM. Les métadonnées de la ressource mises à jour peuvent inclure des informations supplémentaires telles que le SKU, le nom du fournisseur ou d’autres détails du produit.
Pour recevoir et traiter l’événement AEM Assets, on utilise la plateforme sans serveur Adobe I/O Runtime. Cependant, d’autres systèmes de traitement des événements tels que Webhook dans votre système tiers ou Amazon EventBridge peuvent également être utilisés.
Le flux de haut niveau de l’intégration est le suivant :
- Le service de création AEM déclenche un événement Traitement des ressources terminé lorsqu’un chargement de ressource est terminé et que toutes les activités de traitement de ressources sont terminées. Attendre la fin du traitement de la ressource garantit que tout traitement prêt à l’emploi, tel que l’extraction de métadonnées, est terminé.
- L’événement est envoyé au service Événements Adobe I/O.
- Le service Événements Adobe I/O transmet l’événement à l’action Adobe I/O Runtime pour traitement.
- L’action Adobe I/O Runtime appelle l’API du système PIM pour récupérer des métadonnées supplémentaires telles que le SKU, les informations sur le fournisseur ou d’autres détails.
- Les métadonnées supplémentaires extraites du PIM sont ensuite mises à jour dans AEM Assets à l’aide de l’API de création Assets basée sur OpenAPI.
Prérequis
Les éléments suivants sont requis afin de terminer ce tutoriel :
-
Environnement AEM as a Cloud Service avec AEM Eventing activé. L’exemple de projet Sites WKND doit être déployé dessus.
-
Accédez à Adobe Developer Console.
-
Interface de ligne de commande d’Adobe Developer installée sur votre ordinateur local.
Étapes de développement
Les étapes de développement générales sont les suivantes :
-
Configurer le projet dans ADC
-
Configurer le service de création AEM pour activer la communication du projet ADC
-
Développer une action Runtime à orchestrer
- extraction de métadonnées à partir du système PIM
- mise à jour des métadonnées dans AEM Assets à l’aide de l’API de création Assets
-
Créer et appliquer un schéma de métadonnées de ressource
-
Vérification du chargement des ressources et de la mise à jour des métadonnées
Pour plus d’informations sur les étapes 1 et 2, reportez-vous au guide Appeler les API AEM basées sur OpenAPI et pour les étapes 3 et 4, reportez-vous à l’exemple Action Adobe I/O Runtime et événements AEM. Pour les étapes 5 à 9, reportez-vous aux sections suivantes.
Configurer le projet dans Adobe Developer Console (ADC)
Pour recevoir les événements AEM Assets et exécuter l’action Adobe I/O Runtime créée à l’étape précédente, configurez le projet dans ADC.
-
Dans ADC, accédez au projet que vous avez créé à l’étape 3. Dans ce projet, sélectionnez l’espace de travail
Stage
où l’action Runtime est déployée lorsque vous exécutezaio app deploy
dans le cadre des instructions de l’étape 4. -
Cliquez sur le bouton Ajouter un service et sélectionnez l’option Événement. Dans la boîte de dialogue Ajouter des événements, sélectionnez Experience Cloud > AEM Assets et cliquez sur Suivant.
-
À l’étape Configurer l’enregistrement d’événement, sélectionnez l’instance AEMCS souhaitée, puis l’événement Traitement des ressources terminé et le type d’authentification OAuth de serveur à serveur.
-
Enfin, à l’étape Comment recevoir des événements, développez l’option Action Runtime et sélectionnez l’action générique créée à l’étape précédente. Cliquez sur Enregistrer les événements configurés.
-
De même, cliquez sur le bouton Ajouter un service et sélectionnez l’option API. Dans la boîte de dialogue modale Ajouter une API, sélectionnez Experience Cloud > API de création AEM Assets et cliquez sur Suivant.
-
Sélectionnez ensuite OAuth de serveur à serveur comme type d’authentification et cliquez sur Suivant.
-
Sélectionnez ensuite le profil de produit correct qui est associé à l’environnement AEM Assets à partir duquel l’événement est produit et qui dispose d’un accès suffisant pour y mettre à jour les ressources. Enfin, cliquez sur le bouton Enregistrer l’API configurée.
Dans mon cas, le profil de produit Administrateurs et administratrices AEM - Création - Programme XXX - Environnement YYYY est sélectionné, le service Utilisateurs et utilisatrices de l’API AEM Assets est activé.
Configurer l’instance AEM pour activer la communication du projet ADC
Pour permettre à l’ID client des informations d’identification OAuth de serveur à serveur du projet ADC de communiquer avec l’instance AEM, vous devez configurer l’instance AEM.
Pour ce faire, définissez la configuration dans le fichier api.yaml
du projet AEM. Déployez ensuite le fichier api.yaml
à l’aide du pipeline de configuration dans Cloud Manager.
-
Dans le projet AEM, recherchez ou créez le fichier
api.yaml
à partir du dossierconfig
. -
Ajoutez la configuration suivante au fichier
api.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 de serveur à serveur du projet ADC.note caution CAUTION À des fins de démonstration, le même ID client est utilisé pour tous les environnements. Il est recommandé d’utiliser des ID clients distincts par environnement (développement, évaluation, production) pour une meilleure sécurité et un meilleur contrôle. -
Validez les modifications de configuration dans le référentiel Git et transmettez les modifications au référentiel distant.
-
Déployez les modifications ci-dessus à l’aide du pipeline de configuration dans Cloud Manager. Notez que le fichier
api.yaml
peut également être installé dans un RDE à l’aide de l’outil de ligne de commande.
Développer une action Runtime
Pour effectuer la récupération et la mise à jour des métadonnées, commencez par mettre à jour le code d’action générique créé automatiquement dans le dossier src/dx-excshell-1/actions/generic
.
Consultez le fichier WKND-Assets-PIM-Integration.zip ci-joint pour obtenir le code complet. La section ci-dessous met en évidence les fichiers clés.
-
Le fichier
src/dx-excshell-1/actions/generic/mockPIMCommunicator.js
imite l’appel de l’API PIM pour récupérer des métadonnées supplémentaires telles que le SKU et le nom du fournisseur. Ce fichier est utilisé à des fins de démonstration. Une fois que le flux de bout en bout fonctionne, remplacez cette fonction par un appel à votre véritable système PIM pour récupérer les métadonnées de la ressource.code language-javascript /** * Mock PIM API to get the product data such as SKU, Supplier, etc. * * In a real-world scenario, this function would call the PIM API to get the product data. * For this example, we are returning mock data. * * @param {string} assetId - The assetId to get the product data. */ module.exports = { async getPIMData(assetId) { if (!assetId) { throw new Error('Invalid assetId'); } // Mock response data for demo purposes const data = { SKUID: 'MockSKU 123', SupplierName: 'mock-supplier', // ... other product data }; return data; }, };
-
Le fichier
src/dx-excshell-1/actions/generic/aemCommunicator.js
met à jour les métadonnées de la ressource dans AEM à l’aide de l’API de création Assets.code language-javascript const fetch = require('node-fetch'); ... /** * Get IMS Access Token using Client Credentials Flow * * @param {*} clientId - IMS Client ID from ADC project's OAuth Server-to-Server Integration * @param {*} clientSecret - IMS Client Secret from ADC project's OAuth Server-to-Server Integration * @param {*} scopes - IMS Meta Scopes from ADC project's OAuth Server-to-Server Integration as comma separated strings * @returns {string} - Returns the IMS Access Token */ async function getIMSAccessToken(clientId, clientSecret, scopes) { const adobeIMSV3TokenEndpointURL = 'https://ims-na1.adobelogin.com/ims/token/v3'; const options = { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', }, body: `grant_type=client_credentials&client_id=${clientId}&client_secret=${clientSecret}&scope=${scopes}`, }; const response = await fetch(adobeIMSV3TokenEndpointURL, options); const responseJSON = await response.json(); return responseJSON.access_token; } async function updateAEMAssetMetadata(metadataDetails, aemAssetEvent, params) { ... // Transform the metadata details to JSON Patch format, // see https://developer.adobe.com/experience-cloud/experience-manager-apis/api/experimental/assets/author/#operation/patchAssetMetadata const transformedMetadata = Object.keys(metadataDetails).map((key) => ({ op: 'add', path: `wknd-${key.toLowerCase()}`, value: metadataDetails[key], })); ... // Get ADC project's OAuth Server-to-Server Integration credentials const clientId = params.ADC_CECREDENTIALS_CLIENTID; const clientSecret = params.ADC_CECREDENTIALS_CLIENTSECRET; const scopes = params.ADC_CECREDENTIALS_METASCOPES; // Get IMS Access Token using Client Credentials Flow const access_token = await getIMSAccessToken(clientId, clientSecret, scopes); // Call AEM Author service to update the metadata using Assets Author API // See https://developer.adobe.com/experience-cloud/experience-manager-apis/api/experimental/assets/author/ const res = await fetch(`${aemAuthorHost}/adobe/assets/${assetId}/metadata`, { method: 'PATCH', headers: { 'Content-Type': 'application/json-patch+json', 'If-Match': '*', 'X-Adobe-Accept-Experimental': '1', 'X-Api-Key': '12345676', // Use the `ClientID` value from the ADC Project's credentials section Authorization: `Bearer ${access_token}`, }, body: JSON.stringify(transformedMetadata), }); ... } module.exports = { updateAEMAssetMetadata };
Le fichier
.env
stocke les détails des informations d’identification OAuth de serveur à serveur du projet ADC. Ceux-ci sont transmis en tant que paramètres à l’action à l’aide du fichierext.config.yaml
. Consultez également les fichiers de configuration du créateur d’applications pour la gestion des secrets et des paramètres d’action. -
Le dossier
src/dx-excshell-1/actions/model
contient les fichiersaemAssetEvent.js
eterrors.js
, qui sont utilisés par l’action pour analyser l’événement reçu et gérer les erreurs, respectivement. -
Le fichier
src/dx-excshell-1/actions/generic/index.js
utilise les modules mentionnés précédemment pour orchestrer la récupération et la mise à jour des métadonnées.code language-javascript ... let responseMsg; // handle the challenge probe request, they are sent by I/O to verify the action is valid if (params.challenge) { logger.info('Challenge probe request detected'); responseMsg = JSON.stringify({ challenge: params.challenge }); } else { logger.info('AEM Asset Event request received'); // create AEM Asset Event object from request parameters const aemAssetEvent = new AEMAssetEvent(params); // Call mock PIM API to get the product data such as SKU, Supplier, etc. const mockPIMData = await mockPIMAPI.getPIMData( aemAssetEvent.getAssetName(), ); logger.info('Mock PIM API response', mockPIMData); // Update PIM received data in AEM as Asset metadata const aemUpdateStatus = await updateAEMAssetMetadata( mockPIMData, aemAssetEvent, params, ); logger.info('AEM Asset metadata update status', aemUpdateStatus); if (aemUpdateStatus) { // create response message responseMsg = JSON.stringify({ message: 'AEM Asset Event processed successfully, updated the asset metadata with PIM data.', assetdata: { assetName: aemAssetEvent.getAssetName(), assetPath: aemAssetEvent.getAssetPath(), assetId: aemAssetEvent.getAssetId(), aemHost: aemAssetEvent.getAEMHost(), pimdata: mockPIMData, }, }); } // response object const response = { statusCode: 200, body: responseMsg, }; // Return the response to the caller return response; ... }
-
Déployez l’action mise à jour sur Adobe I/O Runtime à l’aide de la commande suivante :
code language-bash $ aio app deploy
Créer et appliquer un schéma de métadonnées de ressource
Par défaut, le projet WKND Sites ne dispose pas du schéma de métadonnées de ressource pour afficher les métadonnées spécifiques à PIM telles que le SKU, le nom du fournisseur, etc. Créons et appliquons le schéma de métadonnées de la ressource à un dossier de ressources dans l’instance AEM.
-
Connectez-vous à l’instance AEM as a Cloud Service Asset et dans la vue Assets.
-
Accédez à l’option Paramètres > Formulaires de métadonnées dans le rail de gauche, puis cliquez sur le bouton Créer. Dans la boîte de dialogue Créer un formulaire de métadonnées, saisissez les détails suivants, puis cliquez sur Créer.
- Nom :
PIM
- Utiliser la structure de formulaire existante comme modèle :
Check
- Choisir dans :
default
- Nom :
-
Cliquez sur l’icône + pour ajouter un nouvel onglet PIM et ajoutez-y des composants à Une seule ligne de texte.
Le tableau suivant répertorie les propriétés de métadonnées et les champs correspondants.
table 0-row-3 1-row-3 2-row-3 Libellé Espace réservé Propriété de métadonnées SKU Renseigné automatiquement via l’intégration AEM Eventing wknd-skuid
Nom du fournisseur Renseigné automatiquement via l’intégration AEM Eventing wknd-suppliername
-
Cliquez sur Enregistrer et Fermer pour enregistrer le formulaire de métadonnées.
-
Enfin, appliquez le schéma de métadonnées PIM au dossier PIM.
Grâce aux étapes ci-dessus, les ressources du dossier Adventures sont prêtes à afficher les métadonnées spécifiques au PIM telles que le SKU, le nom du fournisseur, etc.
Chargement de ressources et vérification des métadonnées
Pour vérifier l’intégration d’AEM Assets et de PIM, chargez une ressource dans le dossier Adventures d’AEM Assets. L’onglet PIM de la page des détails de la ressource doit afficher les métadonnées SKU et Nom du fournisseur.
Concept et principaux points à retenir
La synchronisation des métadonnées des ressources entre AEM et d’autres systèmes comme PIM est souvent requise dans l’entreprise. Grâce à AEM Eventing, ces exigences peuvent être satisfaites.
- Le code de récupération des métadonnées des ressources est exécuté en dehors d’AEM, évitant ainsi la charge sur le service de création AEM, pour une architecture basée sur les événements qui évolue de manière indépendante.
- La nouvelle API de création Assets est utilisée pour mettre à jour les métadonnées des ressources dans AEM.
- L’authentification API utilise OAuth de serveur à serveur (c’est-à-dire le flux d’informations d’identification du client). Consultez le guide de mise en œuvre des informations d’identification OAuth de serveur à serveur.
- Au lieu des actions Adobe I/O Runtime, d’autres webhooks ou Amazon EventBridge peuvent être utilisés pour recevoir l’événement AEM Assets et traiter la mise à jour des métadonnées.
- Les événements de ressources via AEM Eventing permettent aux entreprises d’automatiser et de rationaliser les processus critiques, favorisant ainsi l’efficacité et la cohérence dans l’ensemble de l’écosystème de contenu.