OAuth サーバー間認証を使用した OpenAPI ベースの AEM API の呼び出し
- 適用対象:
- Experience Manager as a Cloud Service
- トピック:
- 開発
作成対象:
- 初心者
- 開発者
- リーダー
OAuth サーバー間 認証を使用してカスタムアプリケーションから AEM as a Cloud Service で OpenAPI ベースの AEM API を呼び出す方法を説明します。
OAuth サーバー間認証は、ユーザーインタラクションなしで API アクセスが必要なバックエンドサービスに最適です。クライアントアプリケーションの認証には、OAuth 2.0 client_credentials 付与タイプを使用します。
学習内容
このチュートリアルでは、以下の方法について説明します。
-
Adobe Developer Console(ADC)プロジェクトを設定し、OAuth サーバー間認証 を使用して Assets Author API にアクセスする。
-
Assets Author API を呼び出して特定のアセットのメタデータを取得するサンプル NodeJS アプリケーションを開発する。
開始する前に、次を必ず確認します。
- 「Adobe API へのアクセスと関連概念」セクション。
- OpenAPI ベースの AEM API の設定記事。
前提条件
このチュートリアルを完了するには、次が必要になります。
-
次を備えた AEM as a Cloud Service 環境の最新化
- AEM リリース
2024.10.18459.20241031T210302Z
以降。 - 新しいスタイルの製品プロファイル(2024年11月より前に環境が作成された場合)
詳しくは、OpenAPI ベースの AEM API の設定を参照してください。
- AEM リリース
-
サンプル WKND Sites プロジェクトをそこにデプロイする必要があります。
-
Adobe Developer Console にアクセスします。
-
Node.js をローカルマシンにインストールして、サンプルの NodeJS アプリケーションを実行します。
開発手順
大まかな開発手順は次のとおりです。
-
ADC プロジェクトの設定
- Assets Author API の追加
- OAuth サーバー間としての認証方法の設定
- 製品プロファイルと認証設定の関連付け
-
ADC プロジェクト通信を有効にする AEM インスタンスの設定
-
サンプル NodeJS アプリケーションの開発
-
エンドツーエンドフローの検証
ADC プロジェクトの設定
ADC プロジェクトの設定手順は、OpenAPI ベースの AEM API の設定から 反復 されます。Assets Author API を追加し、その認証方法を OAuth サーバー間として設定するためにそれが反復されます。
-
Adobe Developer Console から目的のプロジェクトを開きます。
-
AEM API を追加するには、「API を追加」ボタンをクリックします。
-
API を追加 ダイアログで、Experience Cloud でフィルタリングし「AEM Assets Author API」カードを選択して、「次へ」をクリックします。
TIP
目的の AEM API カード が無効になっていて、無効になっている理由 ライセンスが必要です というメッセージが表示されます。理由の 1 つ、AEM as a Cloud Service環境を最新化していないことが考えられます。詳しくは、AEM as a Cloud Service環境の最新化を参照してください。 -
次に、API を設定 ダイアログで「サーバー間」認証オプションを選択し、「次へ」をクリックします。サーバー間認証は、ユーザーインタラクションなしで API アクセスが必要なバックエンドサービスに最適です。
TIP
サーバー間認証オプションが表示されない場合は、統合を設定するユーザーが、サービスが関連付けられている製品プロファイルに開発者として追加されていないということを意味します。詳しくは、サーバー間認証を有効にするを参照してください。 -
(必要に応じて)識別を容易にするために資格情報の名前を変更し、「次へ」をクリックします。デモ用には、デフォルト名が使用されます。
-
AEM Assets 共同作業者ユーザー - オーサー - プログラム XXX - 環境 XXX 製品プロファイルを選択し、「保存」をクリックします。ご覧のように、AEM Assets API ユーザーサービスに関連付けられた製品プロファイルのみを選択できます。
-
AEM API と認証設定を確認します。
ADC プロジェクト通信を有効にする AEM インスタンスの設定
OpenAPI ベースの AEM API の設定記事の手順に従って、AEM インスタンスを設定し、ADC プロジェクト通信を有効にします。
サンプル NodeJS アプリケーションの開発
Assets Author API を呼び出すサンプル NodeJS アプリケーションを開発しましょう。
Java や Python などの他のプログラミング言語を使用して、アプリケーションを開発できます。
テスト目的で、Postman、curl またはその他の REST クライアントを使用して AEM API を呼び出すことができます。
API の確認
アプリケーションを開発する前に、Assets Author API から指定したアセットのメタデータを配信するエンドポイントを確認してみましょう。API 構文は以下のようになります。
GET https://{bucket}.adobeaemcloud.com/adobe/../assets/{assetId}/metadata
特定のアセットのメタデータを取得するには、bucket
と assetId
の値が必要です。bucket
は、例えば author-p63947-e1420428
のように、AEM インスタンス名からアドビドメイン名(.adobeaemcloud.com)を除いたものです。
assetId
は、例えば urn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da
のように、urn:aaid:aem:
の接頭辞が付いたアセットの JCR UUID です。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 Author API ドキュメントを開きます。
-
「メタデータ」セクションを展開し、「指定したアセットのメタデータを配信」オプションをクリックします。
-
右側のペインで、「試す」ボタンをクリックします。
-
以下の値を入力します。
セクションパラメーター値バケット例えばauthor-p63947-e1420428
のような、アドビドメイン名を含まない AEM インスタンス名(.adobeaemcloud.com)セキュリティベアラートークンADC プロジェクトの OAuth サーバー間資格情報のアクセストークンを使用します。セキュリティX-Api-KeyADC プロジェクトの OAuth サーバー間資格情報のClientID
値を使用します。パラメーターassetId例えばurn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da
のような、AEM 内のアセットの一意の IDパラメーターX-Adobe-Accept-Experimental1 -
「送信」をクリックして API を呼び出し、「応答」タブで応答を確認します。
上記の手順は、AEM as a Cloud Service 環境の最新化を確認し、AEM API へのアクセスを可能にします。また、ADC プロジェクトの設定が成功したことや、AEM オーサーインスタンスとの OAuth サーバー間資格情報の ClientID 通信が成功したことも確認します。
サンプル NodeJS アプリケーション
サンプル NodeJS アプリケーションを開発しましょう。
アプリケーションを開発するには、Run-the-sample-application または Step-by-step-development 手順を使用します。
-
サンプルの demo-nodejs-app-to-invoke-aem-openapi アプリケーションの zip ファイルをダウンロードして抽出します。
-
抽出フォルダーに移動して依存関係をインストールします。
$ npm install
-
.env
ファイルのプレースホルダーを ADC プロジェクトの OAuth サーバー間資格情報の実際の値に置き換えます。 -
src/index.js
ファイルの<BUCKETNAME>
と<ASSETID>
を実際の値に書き換えます。 -
NodeJS アプリケーションを実行します。
$ node src/index.js
-
新しい NodeJS プロジェクトを作成します。
$ mkdir demo-nodejs-app-to-invoke-aem-openapi $ cd demo-nodejs-app-to-invoke-aem-openapi $ npm init -y
-
fetch ライブラリと dotenv ライブラリをインストールして、HTTP リクエストを行い、それぞれの環境変数を読み取ります。
$ npm install node-fetch $ npm install dotenv
-
お気に入りのコードエディターでプロジェクトを開き、
package.json
ファイルを更新してtype
をmodule
に追加します。{ ... "version": "1.0.0", "type": "module", "main": "index.js", ... }
-
.env
ファイルを作成し、次の設定を追加します。プレースホルダーを ADC プロジェクトの OAuth サーバー間資格情報の実際の値に置き換えます。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>
を実際の値に置き換えます。// 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 アプリケーションを実行します。
$ 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 サーバー間資格情報を使用して、アクセストークンを取得します。
// 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 を呼び出し、認証用のアクセストークンを提供して、特定のアセットのメタデータを取得します。
// 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 が正常に呼び出されると、製品プロファイルおよびサービス設定に一致するユーザーグループと共に、ADC プロジェクトの OAuth サーバー間資格情報を表すユーザーが AEM オーサーサービスに作成されます。テクニカルアカウントユーザー は、アセットメタデータの 読み取り に必要な権限を持つ製品プロファイルおよび サービス ユーザーグループに関連付けられています。
テクニカルアカウントユーザーとユーザーグループの作成を確認するには、次の手順に従います。
-
ADC プロジェクトで、OAuth サーバー間 資格情報設定に移動します。テクニカルアカウントメール の値をメモします。
-
AEM オーサーサービスで、ツール/セキュリティ/ユーザー に移動し、テクニカルアカウントメール の値を検索します。
-
テクニカルアカウントユーザーをクリックして、グループ メンバーシップなどのユーザーの詳細を表示します。次に示すように、テクニカルアカウントユーザーは、AEM Assets 共同作業者ユーザー - オーサー - プログラム XXX - 環境 XXX および AEM Assets 共同作業者ユーザー - サービス ユーザーグループに関連付けられています。
-
テクニカルアカウントユーザーは、AEM Assets 共同作業者ユーザー - オーサー - プログラム XXX - 環境 XXX 製品プロファイルに関連付けられています。製品プロファイルは、AEM Assets API ユーザー および AEM Assets 共同作業者ユーザー サービスに関連付けられています。
-
製品プロファイルとテクニカルアカウントのユーザーの関連付けは、製品プロファイル の「API 資格情報」タブで確認できます。
GET 以外のリクエストの 403 エラー
アセットメタデータを 読み取る には、OAuth サーバー間資格情報用に作成されたテクニカルアカウントユーザーに、サービスユーザーグループ(例:AEM Assets 共同作業者ユーザー - サービス)を介して必要な権限が付与されている必要があります。
ただし、アセットメタデータを 作成、更新、削除(CUD)するには、テクニカルアカウントユーザーに追加の権限が必要です。GET 以外のリクエスト(PATCH、DELETE など)で API を呼び出してそれを検証し、403 エラー応答を確認することができます。
PATCH リクエストを呼び出して、アセットメタデータを更新し、403 エラー応答を確認しましょう。
-
ブラウザーで Assets Author API ドキュメントを開きます。
-
以下の値を入力します。
セクションパラメーター値バケット例えばauthor-p63947-e1420428
のような、アドビドメイン名を含まない AEM インスタンス名(.adobeaemcloud.com)セキュリティベアラートークンADC プロジェクトの OAuth サーバー間資格情報のアクセストークンを使用します。セキュリティX-Api-KeyADC プロジェクトの OAuth サーバー間資格情報のClientID
値を使用します。本文[{ "op": "add", "path": "foo","value": "bar"}]
パラメーターassetId例えばurn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da
のような、AEM 内のアセットの一意の IDパラメーターX-Adobe-Accept-Experimental*パラメーターX-Adobe-Accept-Experimental1 -
「送信」をクリックして PATCH リクエストを呼び出し、403 エラー応答を確認します。
403 エラーを修正するには、次の 2 つのオプションがあります。
-
ADC プロジェクトで、OAuth サーバー間資格情報に関連付けられている製品プロファイルを、アセットメタデータの 作成、更新、削除(CUD)に必要な権限を持つ適切な製品プロファイル(例:AEM 管理者 - オーサー - プログラム XXX - 環境 XXX)で更新します。詳しくは、方法 - API の接続資格情報と製品プロファイル管理の記事を参照してください。
-
AEM プロジェクトを使用して、AEM オーサーで関連する AEM サービスユーザーグループ(例:AEM Assets 共同作業者ユーザー - サービス)の権限を更新し、アセットメタデータの 作成、更新、削除(CUD)を許可します。詳しくは、方法 - AEM サービスユーザーグループの権限管理の記事を参照してください。
概要
このチュートリアルでは、カスタムアプリケーションから OpenAPI ベースの AEM API を呼び出す方法を学びました。AEM API へのアクセスを有効にし、Adobe Developer Console(ADC)プロジェクトを作成して設定しました。
ADC プロジェクトで、AEM API を追加し、その認証タイプを設定して、製品プロファイルを関連付けました。また、ADC プロジェクト通信を有効にするように AEM インスタンスを設定し、Assets Author API を呼び出すサンプル NodeJS アプリケーションを開発しました。