ドキュメントAEMAEM チュートリアルAEM as a Cloud Service のチュートリアル

OAuth サーバー間認証を使用した OpenAPI ベースの AEM API の呼び出し

最終更新日: 2025年6月18日
  • 適用対象:
  • 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 の設定を参照してください。

  • サンプル WKND Sites プロジェクトをそこにデプロイする必要があります。

  • Adobe Developer Console にアクセスします。

  • Node.js をローカルマシンにインストールして、サンプルの NodeJS アプリケーションを実行します。

開発手順

大まかな開発手順は次のとおりです。

  1. ADC プロジェクトの設定

    1. Assets Author API の追加
    2. OAuth サーバー間としての認証方法の設定
    3. 製品プロファイルと認証設定の関連付け
  2. ADC プロジェクト通信を有効にする AEM インスタンスの設定

  3. サンプル NodeJS アプリケーションの開発

  4. エンドツーエンドフローの検証

ADC プロジェクトの設定

ADC プロジェクトの設定手順は、OpenAPI ベースの AEM API の設定から​ 反復 ​されます。Assets Author API を追加し、その認証方法を OAuth サーバー間として設定するためにそれが反復されます。

TIP
OpenAPI ベースの AEM API の設定​ 記事から AEM API アクセスの有効化手順が完了していることを確認します。これがないと、サーバー間認証オプションは使用できません。
  1. Adobe Developer Console から目的のプロジェクトを開きます。

  2. AEM API を追加するには、「API を追加」ボタンをクリックします。

    API を追加

  3. API を追加 ​ダイアログで、Experience Cloud でフィルタリングし「AEM Assets Author API」カードを選択して、「次へ」をクリックします。

    AEM API を追加

    TIP
    目的の AEM API カード が無効になっていて、無効になっている理由​ ライセンスが必要です ​というメッセージが表示されます。理由の 1 つ、AEM as a Cloud Service環境を最新化していないことが考えられます。詳しくは、AEM as a Cloud Service環境の最新化を参照してください。
  4. 次に、API を設定 ​ダイアログで「サーバー間」認証オプションを選択し、「次へ」をクリックします。サーバー間認証は、ユーザーインタラクションなしで API アクセスが必要なバックエンドサービスに最適です。

    認証を選択

    TIP
    サーバー間認証オプションが表示されない場合は、統合を設定するユーザーが、サービスが関連付けられている製品プロファイルに開発者として追加されていないということを意味します。詳しくは、サーバー間認証を有効にするを参照してください。
  5. (必要に応じて)識別を容易にするために資格情報の名前を変更し、「次へ」をクリックします。デモ用には、デフォルト名が使用されます。

    資格情報の名前を変更

  6. AEM Assets 共同作業者ユーザー - オーサー - プログラム XXX - 環境 XXX 製品プロファイルを選択し、「保存」をクリックします。ご覧のように、AEM Assets API ユーザーサービスに関連付けられた製品プロファイルのみを選択できます。

    製品プロファイルを選択

  7. AEM 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 を呼び出しましょう。

  1. ブラウザーで Assets Author API ドキュメントを開きます。

  2. 「メタデータ」セクションを展開し、「指定したアセットのメタデータを配信」オプションをクリックします。

  3. 右側のペインで、「試す」ボタンをクリックします。
    API に関するドキュメント

  4. 以下の値を入力します。

    セクション
    パラメーター
    値
    バケット
    例えば author-p63947-e1420428 のような、アドビドメイン名を含まない AEM インスタンス名(.adobeaemcloud.com)
    セキュリティ
    ベアラートークン
    ADC プロジェクトの OAuth サーバー間資格情報のアクセストークンを使用します。
    セキュリティ
    X-Api-Key
    ADC プロジェクトの OAuth サーバー間資格情報の ClientID 値を使用します。
    パラメーター
    assetId
    例えば urn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da のような、AEM 内のアセットの一意の ID
    パラメーター
    X-Adobe-Accept-Experimental
    1

    API の呼び出し - アクセストークン

    API の呼び出し - 入力値

  5. 「送信」をクリックして API を呼び出し、「応答」タブで応答を確認します。

    API の呼び出し - 応答

上記の手順は、AEM as a Cloud Service 環境の最新化を確認し、AEM API へのアクセスを可能にします。また、ADC プロジェクトの設定が成功したことや、AEM オーサーインスタンスとの OAuth サーバー間資格情報の ClientID 通信が成功したことも確認します。

サンプル NodeJS アプリケーション

サンプル NodeJS アプリケーションを開発しましょう。

アプリケーションを開発するには、Run-the-sample-application または Step-by-step-development 手順を使用します。

Run-the-sample-application
  1. サンプルの demo-nodejs-app-to-invoke-aem-openapi アプリケーションの zip ファイルをダウンロードして抽出します。

  2. 抽出フォルダーに移動して依存関係をインストールします。

    $ npm install
    
  3. .env ファイルのプレースホルダーを ADC プロジェクトの OAuth サーバー間資格情報の実際の値に置き換えます。

  4. src/index.js ファイルの <BUCKETNAME> と <ASSETID> を実際の値に書き換えます。

  5. NodeJS アプリケーションを実行します。

    $ node src/index.js
    
段階的な開発
  1. 新しい NodeJS プロジェクトを作成します。

    $ mkdir demo-nodejs-app-to-invoke-aem-openapi
    $ cd demo-nodejs-app-to-invoke-aem-openapi
    $ npm init -y
    
  2. fetch ライブラリと dotenv ライブラリをインストールして、HTTP リクエストを行い、それぞれの環境変数を読み取ります。

    $ npm install node-fetch
    $ npm install dotenv
    
  3. お気に入りのコードエディターでプロジェクトを開き、package.json ファイルを更新して type を module に追加します。

    {
        ...
        "version": "1.0.0",
        "type": "module",
        "main": "index.js",
        ...
    }
    
  4. .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>
    
  5. 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();
    
  6. 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 アプリケーションコードの主要な呼び出しは次のとおりです。

  1. 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;
    };
    ...
    
  2. 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 資格情報」タブで確認できます。

    製品プロファイル 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-Key
    ADC プロジェクトの 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-Experimental
    1
  • 「送信」をクリックして PATCH リクエストを呼び出し、403 エラー応答を確認します。

    API の呼び出し - PATCH リクエスト

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 アプリケーションを開発しました。

その他のリソース

  • OAuth サーバー間資格情報実装ガイド
recommendation-more-help
4859a77c-7971-4ac9-8f5c-4260823c6f69