使用OAuth伺服器對伺服器驗證叫用OpenAPI型AEM API
瞭解如何使用 OAuth伺服器對伺服器 驗證,從自訂應用程式叫用AEM as a Cloud Service上的OpenAPI型AEM API。
OAuth伺服器對伺服器驗證適用於需要API存取而不需使用者互動的後端服務。 它使用OAuth 2.0 client_credentials 授權型別來驗證使用者端應用程式。
學習內容 what-you-learn
在本教學課程中,您將學習如何:
-
設定Adobe Developer Console (ADC)專案,以使用 OAuth伺服器對伺服器驗證 存取Assets Author API。
-
開發範例NodeJS應用程式,呼叫Assets Author API以擷取特定資產的中繼資料。
開始之前,請務必檢閱下列內容:
先決條件
若要完成本教學課程,您需要:
-
更新的AEM as a Cloud Service環境,其中包含:
- AEM版本
2024.10.18459.20241031T210302Z
或更新版本。 - 新樣式的產品設定檔(如果環境是在2024年11月之前建立的)
如需詳細資訊,請參閱設定OpenAPI型AEM API文章。
- AEM版本
-
必須在其上部署範例WKND Sites專案。
-
在本機電腦上安裝Node.js,以執行範例NodeJS應用程式。
開發步驟
高階開發步驟為:
-
設定ADC專案
- 新增Assets Author API
- 將其驗證方法設定為OAuth伺服器對伺服器
- 將產品設定檔與驗證設定建立關聯
-
設定AEM執行個體以啟用ADC專案通訊
-
開發範例NodeJS應用程式
-
驗證端對端流程
設定ADC專案
設定ADC專案步驟是 設定OpenAPI型AEM API 中的重複。 您需重複新增Assets Author API,並將其驗證方法設定為OAuth伺服器對伺服器。
-
從Adobe Developer Console,開啟所需的專案。
-
若要新增AEM API,請按一下 新增API 按鈕。
-
在 新增API 對話方塊中,依 Experience Cloud 篩選,並選取 AEM Assets作者API 卡片,然後按一下 下一步。
如果您需要其他OpenAPI型AEM API,請參閱Adobe Developer檔案以尋找符合您使用案例的API。下列範例會逐步說明如何新增 AEM Assets Author API。
note tip TIP 如果所需的 AEM API卡 已停用,且_為什麼此卡已停用?_資訊顯示 需要授權 訊息,其中一個原因可能是您尚未更新AEM as a Cloud Service環境,如需詳細資訊,請參閱更新AEM as a Cloud Service環境。 -
接著,在 設定API 對話方塊中,選取 伺服器對伺服器 驗證選項,然後按一下 下一步。 伺服器對伺服器驗證適用於需要API存取而不需使用者互動的後端服務。
note tip TIP 如果您沒有看到「伺服器對伺服器」驗證選項,這表示設定整合的使用者不會新增為開發人員至與服務相關聯的產品設定檔。 如需詳細資訊,請參閱啟用伺服器對伺服器驗證。 -
重新命名認證以方便識別(如有需要),然後按一下 下一步。 為了示範目的,會使用預設名稱。
-
選取 AEM Assets Collaborator使用者 — 作者 — 方案XXX — 環境XXX 產品設定檔,然後按一下 儲存。 如您所見,僅與AEM Assets API Users Service相關聯的產品設定檔可供選取。
-
檢閱AEM API和驗證設定。
設定AEM執行個體以啟用ADC專案通訊
遵循設定OpenAPI型AEM API文章中的指示,設定AEM執行個體以啟用ADC專案通訊。
開發範例NodeJS應用程式
讓我們開發一個呼叫Assets Author API的範例NodeJS應用程式。
您可以使用其他程式語言(如Java、Python等)來開發應用程式。
為了測試目的,您可以使用Postman、curl或任何其他REST使用者端來叫用AEM API。
檢閱API
在開發應用程式之前,請先檢閱Assets作者API中的 傳遞指定資產的中繼資料 端點。 API語法為:
GET https://{bucket}.adobeaemcloud.com/adobe/../assets/{assetId}/metadata
若要擷取特定資產的中繼資料,您需要bucket
和assetId
值。 bucket
是不含AEM網域名稱(.adobeaemcloud.com)的Adobe執行個體名稱,例如author-p63947-e1420428
。
assetId
是首碼為urn:aaid:aem:
之資產的JCR UUID,例如urn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da
。 有多種方式可取得assetId
:
-
附加AEM資產路徑
.json
擴充功能以取得資產中繼資料。 例如,https://author-p63947-e1420429.adobeaemcloud.com/content/dam/wknd-shared/en/adventures/cycling-southern-utah/adobestock-221043703.jpg.json
並尋找jcr:uuid
屬性。 -
或者,您可以在瀏覽器的元素檢查器中檢查資產,以取得
assetId
。 尋找data-id="urn:aaid:aem:..."
屬性。
使用瀏覽器叫用API
在開發應用程式之前,請先使用 API檔案 中的嘗試它功能叫用API。
-
在瀏覽器中開啟Assets作者API檔案。
-
展開 中繼資料 區段,然後按一下 傳遞指定資產的中繼資料 選項。
-
在右窗格中,按一下 嘗試它 按鈕。
-
輸入下列值:
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 區段 參數 值 貯體 不含AEM網域名稱(.adobeaemcloud.com)的Adobe執行個體名稱,例如 author-p63947-e1420428
。安全性 持有人權杖 使用ADC專案的OAuth伺服器對伺服器認證中的存取權杖。 安全性 X-Api-Key 使用ADC專案的OAuth伺服器對伺服器認證中的 ClientID
值。引數 assetId AEM中資產的唯一識別碼,例如 urn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da
引數 X-Adobe-Accept-Experimental 1 -
按一下 傳送 以叫用API,並在 回應 索引標籤中檢閱回應。
上述步驟確認AEM as a Cloud Service環境的現代化,啟用AEM API存取權。 這也會確認ADC專案的成功設定,以及與AEM Author例項的OAuth伺服器對伺服器認證ClientID通訊。
NodeJS應用程式範例
讓我們開發一個範例NodeJS應用程式。
若要開發應用程式,您可以使用 Run-the-sample-application 或 逐步開發 指示。
-
下載範例demo-nodejs-app-to-invoke-aem-openapi應用程式zip檔案並解壓縮。
-
導覽至解壓縮的資料夾並安裝相依性。
code language-bash $ npm install
-
以ADC專案的OAuth伺服器對伺服器認證中的實際值取代
.env
檔案中的預留位置。 -
將
<BUCKETNAME>
檔案中的<ASSETID>
和src/index.js
取代為實際值。 -
執行NodeJS應用程式。
code language-bash $ node src/index.js
-
建立新的NodeJS專案。
code language-bash $ mkdir demo-nodejs-app-to-invoke-aem-openapi $ cd demo-nodejs-app-to-invoke-aem-openapi $ npm init -y
-
安裝 擷取 和 dotenv 程式庫,分別發出HTTP要求並讀取環境變數。
code language-bash $ npm install node-fetch $ npm install dotenv
-
在您最愛的程式碼編輯器中開啟專案,並更新
package.json
檔案以將type
新增至module
。code language-json { ... "version": "1.0.0", "type": "module", "main": "index.js", ... }
-
建立
.env
檔案並新增下列組態。 將預留位置取代為ADC專案的OAuth伺服器對伺服器認證中的實際值。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>
-
建立
src/index.js
檔案並新增下列程式碼,並以實際值取代<BUCKETNAME>
和<ASSETID>
。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();
-
執行NodeJS應用程式。
code language-bash $ node src/index.js
API回應
成功執行後,主控台中會顯示API回應。 回應包含指定資產的中繼資料。
{
"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",
...
}
}
恭喜!您已成功使用OAuth伺服器對伺服器驗證,從自訂應用程式叫用以OpenAPI為基礎的AEM API。
檢閱應用程式程式碼
範例NodeJS應用程式程式碼中的關鍵圖說文字為:
-
IMS驗證:已在ADC專案中使用OAuth伺服器對伺服器認證設定擷取存取權杖。
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; }; ...
-
API引動:叫用Assets Author API,以提供授權的存取權杖來擷取特定資產的中繼資料。
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 }; ...
隱藏在機殼下
成功引發API後,會在AEM Author服務中建立代表ADC專案的OAuth伺服器對伺服器認證的使用者,以及符合產品設定檔和服務設定的使用者群組。 技術帳戶使用者 與產品設定檔和 服務 使用者群組相關聯,該使用者群組具有 讀取 資產中繼資料的必要許可權。
若要驗證技術帳戶使用者和使用者群組的建立,請遵循下列步驟:
-
在ADC專案中,瀏覽至 OAuth伺服器對伺服器 認證組態。 記下 技術帳戶電子郵件 值。
-
在AEM作者服務中,導覽至 工具 > 安全性 > 使用者,並搜尋 技術帳戶電子郵件 值。
-
按一下技術帳戶使用者即可檢視使用者詳細資訊,例如 群組 成員資格。 如下所示,技術帳戶使用者與 AEM Assets Collaborator使用者 — 作者 — 方案XXX — 環境XXX 和 AEM Assets Collaborator使用者 — 服務 使用者群組相關聯。
-
請注意,技術帳戶使用者與 AEM Assets Collaborator使用者 — 作者 — 方案XXX — 環境XXX 產品設定檔相關聯。 產品設定檔與 AEM Assets API使用者 和 AEM Assets Collaborator使用者 服務相關聯。
-
您可以在 產品設定檔 的 API認證 索引標籤中驗證產品設定檔與技術帳戶使用者關聯。
非GET請求的403錯誤
若要 讀取 資產中繼資料,為OAuth伺服器對伺服器認證建立的技術帳戶使用者必須透過Services使用者群組(例如AEM Assets Collaborator Users - Service)擁有必要許可權。
不過,若要 建立、更新、刪除 (CLOUD)資產中繼資料,技術帳戶使用者需要其他許可權。 您可以使用非GET請求(例如,PATCH、DELETE)叫用API來驗證它,並觀察403錯誤回應。
讓我們叫用 PATCH 要求來更新資產中繼資料,並觀察403錯誤回應。
-
在瀏覽器中開啟Assets作者API檔案。
-
輸入下列值:
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 區段 參數 值 貯體 不含AEM網域名稱(.adobeaemcloud.com)的Adobe執行個體名稱,例如 author-p63947-e1420428
。安全性 持有人權杖 使用ADC專案的OAuth伺服器對伺服器認證中的存取權杖。 安全性 X-Api-Key 使用ADC專案的OAuth伺服器對伺服器認證中的 ClientID
值。內文 [{ "op": "add", "path": "foo","value": "bar"}]
引數 assetId AEM中資產的唯一識別碼,例如 urn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da
引數 X-Adobe-Accept-Experimental * 引數 X-Adobe-Accept-Experimental 1 -
按一下 傳送 以叫用 PATCH 要求,並觀察403錯誤回應。
若要修正403錯誤,您有兩個選項:
-
在ADC Project中,以適當的產品設定檔更新OAuth伺服器對伺服器認證的相關產品設定檔,該產品設定檔具有 建立、更新、刪除 (CUD)資產中繼資料的必要許可權,例如,AEM管理員 — 作者 — 方案XXX — 環境XXX。 如需詳細資訊,請參閱如何 — API的連線認證和產品設定檔管理文章。
-
使用AEM專案,在AEM Author中更新關聯的AEM Service使用者群組(例如,AEM Assets Collaborator Users - Service)許可權,以允許建立、更新、刪除 (CLOUD)資產中繼資料。 如需詳細資訊,請參閱如何進行 — AEM Service使用者群組許可權管理文章。
摘要
在本教學課程中,您已瞭解如何從自訂應用程式叫用OpenAPI型AEM API。 您已啟用AEM API存取,並建立和設定Adobe Developer Console (ADC)專案。
在ADC專案中,您已新增AEM API、設定其驗證型別,並與產品設定檔建立關聯。 您也將AEM例項設定為啟用ADC專案通訊,並開發呼叫Assets Author API的範例NodeJS應用程式。