PIM整合的AEM Assets事件

IMPORTANT
本教學課程使用OpenAPI型AEM API。 如果您有興趣存取,建議您將使用案例說明以電子郵件寄至aem-apis@adobe.com,作為搶先使用方案的一部分。

瞭解如何使用OpenAPI型AEM製作API接收Assets事件並據以更新AEM中的內容狀態。

如何處理收到的事件取決於業務需求。 例如,事件資料可用來更新協力廠商系統或AEM,或兩者皆更新。

此範例示範如何將協力廠商系統(例如產品資訊管理(PIM)系統)與AEM as a Cloud Service Assets整合。 在收到AEM Assets事件時,系統會對其進行處理,以從PIM系統擷取其他中繼資料,並更新AEM中的資產中繼資料。 更新的資產中繼資料可包含SKU、供應商名稱或其他產品詳細資料等額外資訊。

為了接收及處理AEM Assets事件Adobe I/O Runtime,使用無伺服器平台。 不過,您也可以在協力廠商系統或Amazon EventBridge中使用其他事件處理系統,例如Webhook。

整合的高層級流程如下:

用於PIM整合的 AEM Assets事件

  1. 當資產上傳完成且所有資產處理活動也完成時,AEM作者服務會觸發​ 資產處理完成 ​事件。 等候資產處理完成可確保任何現成可用的處理(例如中繼資料擷取)已完成。
  2. 事件已傳送至Adobe I/O Events服務。
  3. Adobe I/O Events服務將事件傳遞至Adobe I/O Runtime動作以進行處理。
  4. 「Adobe I/O Runtime動作」會呼叫PIM系統的API來擷取其他中繼資料,例如SKU、供應商資訊或其他詳細資訊。
  5. 從PIM擷取的其他中繼資料會在AEM Assets中使用以OpenAPI為基礎的Assets作者API更新。

先決條件

若要完成本教學課程,您需要:

開發步驟

高階開發步驟為:

  1. 更新AEM as a Cloud Service環境

  2. 啟用AEM API存取權

  3. 在Adobe Developer Console (ADC)中建立專案

  4. 初始化專案以進行本機開發

  5. 在ADC中設定專案

  6. 設定AEM作者服務以啟用ADC專案通訊

  7. 開發執行階段動作以進行協調

    1. 從PIM系統擷取中繼資料
    2. 使用Assets作者API在AEM Assets中更新中繼資料
  8. 建立和套用資產中繼資料結構

  9. 驗證資產上傳和中繼資料更新

如需步驟1-2的詳細資訊,請參閱叫用OpenAPI型AEM API指南,如需步驟3-4,請參閱Adobe I/O Runtime動作和AEM事件範例。 如需步驟5-9,請參閱下列章節。

在Adobe Developer Console (ADC)中設定專案

若要接收AEM Assets事件並執行上一步建立的Adobe I/O Runtime動作,請在ADC中設定專案。

  • 在ADC中,導覽至您在步驟3中建立的專案。 從該專案中,選取Stage工作區,執行階段動作會在您執行aio app deploy時部署為步驟4指示的一部分。

  • 按一下​ 新增服務 ​按鈕,然後選取​ 事件 ​選項。 在​ 新增事件 ​對話方塊中,選取​ Experience Cloud > AEM Assets,然後按一下​ 下一步
    AEM Assets活動 — 新增活動

  • 在​ 設定事件註冊 ​步驟中,選取所需的AEMCS執行個體,然後選取​ 已完成資產處理 ​事件,以及OAuth伺服器對伺服器驗證型別。

    AEM Assets事件 — 設定事件

  • 最後,在​ 如何接收事件 ​步驟中,展開​ 執行階段動作 ​選項,並選取在上一步建立的​ 一般 ​動作。 按一下​ 儲存已設定的事件

    AEM Assets事件 — 接收事件

  • 同樣地,按一下​ 新增服務 ​按鈕並選取​ API ​選項。 在​ 新增API ​強制回應視窗中,選取​ Experience Cloud > AEM Assets作者API ​並按一下​ 下一步

    新增AEM Assets作者API — 設定專案

  • 然後選取​ OAuth伺服器對伺服器 ​做為驗證型別,並按一下​ 下一步

  • 然後選取與正在產生事件的AEM Assets環境相關聯的正確​ 產品設定檔,並擁有在該處更新資產的足夠存取許可權。 最後,按一下​ 儲存已設定的API ​按鈕。

    新增AEM Assets作者API — 設定專案

    在我看來,AEM管理員 — 作者 — 方案XXX — 環境YYYY ​產品設定檔已選取,它已啟用​ AEM Assets API使用者 ​服務。

    新增AEM Assets作者API — 範例產品設定檔

設定AEM執行個體以啟用ADC專案通訊

若要啟用ADC Project的OAuth伺服器對伺服器認證ClientID來與AEM執行個體通訊,您必須設定AEM執行個體。

若要完成設定,請在AEM專案的api.yaml檔案中定義設定。 然後,使用Cloud Manager中的設定管道來部署api.yaml檔案。

  • 在AEM專案中,從config資料夾中找到或建立api.yaml檔案。

    找出API YAML

  • 將下列設定新增至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>"
    

    以ADC專案的OAuth伺服器對伺服器認證的實際ClientID取代<ADC Project's OAuth Server-to-Server credential ClientID>

    note caution
    CAUTION
    為了示範,所有環境都會使用相同的ClientID。 建議您針對每個環境(開發、階段、生產)使用個別的ClientID,以提升安全性和控制能力。
  • 將設定變更提交至Git存放庫並將變更推送至遠端存放庫。

  • 使用Cloud Manager中的設定管道來部署上述變更。 請注意,也可以使用命令列工具將api.yaml檔案安裝在RDE中。

    部署API YAML

開發執行階段動作

若要執行中繼資料擷取和更新,請先更新src/dx-excshell-1/actions/generic資料夾中自動建立的​ 通用 ​動作代碼。

如需完整程式碼,請參閱附加的WKND-Assets-PIM-Integration.zip檔案,以下區段將重點說明重要檔案。

  • src/dx-excshell-1/actions/generic/mockPIMCommunicator.js檔案會模擬PIM API呼叫,以擷取其他中繼資料,例如SKU和供應商名稱。 此檔案用於示範用途。 一旦您讓端對端流程正常運作,請以呼叫您真正的PIM系統來取代此函式,以擷取資產的中繼資料。

    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;
        },
    };
    
  • src/dx-excshell-1/actions/generic/aemCommunicator.js檔案會使用Assets作者API更新AEM中的資產中繼資料。

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

    .env檔案儲存ADC Project的OAuth伺服器對伺服器認證詳細資料,並使用ext.config.yaml檔案將這些資料作為引數傳遞給動作。 如需管理密碼和動作引數,請參閱App Builder組態檔

  • src/dx-excshell-1/actions/model資料夾包含aemAssetEvent.jserrors.js檔案,動作會使用這些檔案分別剖析收到的事件和處理錯誤。

  • src/dx-excshell-1/actions/generic/index.js檔案使用上述模組來協調中繼資料的擷取和更新。

    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;
      ...
    }
    
  • 使用以下命令,將更新的動作部署到Adobe I/O Runtime:

    code language-bash
    $ aio app deploy
    

建立和套用資產中繼資料結構

依預設,WKND Sites專案沒有資產中繼資料結構可顯示PIM特定中繼資料,例如SKU、供應商名稱等。 讓我們建立資產中繼資料結構,並將其套用至AEM例項中的資產資料夾。

  1. 登入AEM as a Cloud Service Asset執行個體並出現在資產檢視中。

    AEM Assets檢視

  2. 從左側邊欄瀏覽至​ 設定 > 中繼資料Forms ​選項,然後按一下​ 建立 ​按鈕。 在​ 建立中繼資料表單 ​對話方塊中,輸入下列詳細資料,然後按一下​ 建立

    • 名稱:PIM
    • 使用現有的表單結構作為範本: Check
    • 選擇來源: default

    建立中繼資料表單

  3. 按一下​ + ​圖示以新增新的​ PIM ​索引標籤,並新增​ 單行文字 ​元件。

    新增PIM標籤

    下表列出中繼資料屬性及其對應欄位。

    table 0-row-3 1-row-3 2-row-3
    標籤 預留位置 中繼資料屬性
    SKU 透過AEM Eventing整合自動填入 wknd-skuid
    供應商名稱 透過AEM Eventing整合自動填入 wknd-suppliername
  4. 按一下​ 儲存 ​和​ 關閉 ​以儲存中繼資料表單。

  5. 最後,將​ PIM ​中繼資料結構描述套用至​ PIM ​資料夾。

    套用中繼資料結構描述

透過上述步驟,Adventures ​資料夾中的資產已準備好顯示PIM特定的中繼資料,例如SKU、供應商名稱等。

資產上傳和中繼資料驗證

若要驗證AEM Assets和PIM整合,請將資產上傳至AEM Assets中的​ Adventures ​資料夾。 資產明細頁面中的PIM頁標應顯示SKU與「供應商名稱」中繼資料。

AEM Assets上傳

概念與主要要領

企業通常需要在AEM和其他系統(例如PIM)之間同步資產中繼資料。 使用AEM Eventing即可達到這類要求。

  • 資產中繼資料擷取程式碼會在AEM外部執行,避免AEM Author服務上的負載,因此是一種獨立擴展的事件導向架構。
  • 新推出的Assets Author API可用於更新AEM中的資產中繼資料。
  • API驗證使用OAuth伺服器對伺服器(亦稱為使用者端認證流程),請參閱OAuth伺服器對伺服器認證實作指南
  • 與其使用Adobe I/O Runtime動作,其他Webhook或Amazon EventBridge可以用來接收AEM Assets事件和處理中繼資料更新。
  • 透過AEM舉辦資產活動可讓企業自動化及簡化關鍵程式,進而促進內容生態系統的效率及一致性。
recommendation-more-help
4859a77c-7971-4ac9-8f5c-4260823c6f69