AEM Forms as a Cloud Service通信の同期 API 処理
このガイドでは、AEM Forms Communications Synchronous API の設定と使用に関する包括的な手順を説明します。
OAuth サーバー間認証を使用して、AEM as a Cloud Service環境を設定し、API アクセスを有効にし、通信 API を呼び出す方法について説明します。
前提条件
AEM Forms Communications API の実行とテストを行うための環境を設定するには、以下が揃っていることを確認してください。
アクセスと権限
通信 API の設定を開始する前に、必要なアクセス権と権限があることを確認してください。
ユーザーおよび役割の権限
- Adobe IDは https://account.adobe.com/ で作成されました
- 組織のメールに関連付けられたAdobe ID
- Adobe Managed Services製品コンテキストの割り当て
- Adobe Admin Consoleで割り当てられた開発者の役割
- Adobe Developer Consoleでプロジェクトを作成する権限
Cloud Manager アクセス
- Cloud Manager のログイン資格情報
- プログラムの環境を表示および管理するためのアクセス
- CI/CD パイプラインを作成および実行する権限
- 環境の詳細および設定へのアクセス
Git リポジトリへのアクセス
- Cloud Manager Git リポジトリーへのアクセス
- クローン作成と変更のプッシュのための Git 資格情報
開発ツール
- サンプルアプリケーションの実行用の Node.js
- Git の最新バージョン
- ターミナル/コマンドライン へのアクセス
- 設定ファイル編集用の テキストエディターまたは IDE （VS Code、IntelliJ など）
- Postman または API テスト用の同様のツール
次に、各手順を詳しく説明します。
手順 1:AEM インスタンスの更新
AEM インスタンスを更新するには：
-
Adobe Cloud Managerへのログイン
- my.cloudmanager.adobe.com に移動します。
- Adobe IDでログイン
-
プログラムの概要に移動
- リストからプログラムを選択します。 プログラムの概要ページにリダイレクトされます
-
環境の詳細を見つける
-
環境名の横にある「
ellipsis（…）」アイコンを選択し、「更新」をクリックします -
送信 ボタンをクリックし、提案されたフルスタックパイプラインを実行します。
-
手順 2:Git リポジトリの複製
Cloud Manager Git リポジトリーをクローンして、API 設定ファイルを管理します。
-
リポジトリセクションを見つける
-
プログラムの概要 ページで、「リポジトリ」タブをクリックします
-
リポジトリ名を見つけ、省略記号メニュー（…）をクリックします。
-
リポジトリー URL をコピー
note note NOTE 通常、URL 形式は https://git.cloudmanager.adobe.com/<org>/<program>/です
-
-
Git コマンドを使用したクローン
-
コマンドプロンプトまたはターミナルを開きます
-
git cloneコマンドを実行して、Git リポジトリを複製します。code language-bash git clone [repository-url]note note NOTE Git リポジトリを複製するには、Adobe Cloud Managerから提供された資格情報を使用します。 例えば、Git リポジトリーをクローンするには、次のコマンドを実行します。
code language-bash https://git.cloudmanager.adobe.com/formsinternal01/AEMFormsInternal-ReleaseSanity-p43162-uk59167/
-
Git リポジトリ統合オプション
Adobe Cloud Managerでは、次の両方のリポジトリオプションをサポートしています。
-
Cloud Manager Git リポジトリの直接使用
- Cloud Managerのネイティブ Git リポジトリを使用
- パイプラインとの組み込み統合
-
顧客管理 Git リポジトリーとの統合
- 独自の Git リポジトリ（GitHub、GitLab、Bitbucket など）を接続
- Adobe Cloud Managerとの同期の設定
Adobe Cloud ManagerとAdobe Cloud Managerの統合方法について詳しくは、Git 統合に関するドキュメント を参照してください。
手順 3:AEM Cloud Service 環境とAEM Forms エンドポイントへのアクセス
AEM Cloud Service 環境の詳細にアクセスして、API 設定に必要な URL と識別子を取得します。
-
Adobe Cloud Managerへのログイン
- my.cloudmanager.adobe.com に移動します。
- Adobe IDでログイン
-
プログラムの概要に移動
リストからプログラムを選択します。 プログラムの概要ページにリダイレクトされます -
AEM Cloud Service 環境へのアクセスと表示
AEM Cloud Service 環境の詳細の表示またはアクセスには、次の 2 つのオプションのいずれかを使用できます。
-
オプション 1：概要ページから
-
プログラムの概要 ページで、次の操作を行います
-
左側のメニューで 「環境」 クリックします。 すべての環境のリストが表示されます
-
特定の環境名をクリックすると詳細を表示できます
-
-
オプション 2：環境セクションから
-
プログラムの概要ページで、次の操作を行います
-
「環境 セクションを見つけます
-
「すべて表示」 をクリックして、すべての環境を表示します
-
環境の横にある 省略記号メニュー（…） をクリックします
-
「詳細 表示」を選択し す。
-
-
-
AEM Forms エンドポイントの検索
環境 詳細ページから、次の詳細に注意してください。
オーサーサービス URL
- URL：
https://author-pXXXXX-eYYYYY.adobeaemcloud.com - バケット：author-pXXXXX-eYYYY
例：https://author-p43162-e177398.adobeaemcloud.com
パブリッシュサービス URL
- URL：
https://publish-pXXXXX-eYYYYY.adobeaemcloud.com - バケット：publish-pXXXXX-eYYYY
例：https://publish-p43162-e177398.adobeaemcloud.com
- URL：
手順 4:API アクセスの設定
次の手順を実行して、AEM Forms Communications API を設定します。
4.1 Adobe Developer Console プロジェクトのセットアップ
-
Adobe Developer Consoleへのアクセス
- Adobe Developer Console に移動します
- Adobe IDでログイン
-
新規プロジェクトを作成
-
「クイックスタート」セクションで、「新規プロジェクトを作成」をクリックします
-
デフォルト名で新しいプロジェクトが作成されます
-
右上隅の プロジェクトを編集 をクリックします
-
意味のある名前を指定（例：「formsproject」）
-
「保存」をクリックします。
-
4.2 Forms Communication API の追加
要件に応じて、様々なAEM Forms通信 API を追加できます。
A.ドキュメントサービス API の場合
-
「API を追加」をクリックします。
-
Forms Communication API を選択
- API を追加 ダイアログで、Experience Cloudでフィルタリングします
- 「Forms Communication API を選択し す。
-
OAuth サーバー間 認証方法を選択します
B.Forms Runtime API の場合
-
「API を追加」をクリック
- プロジェクトで「API を追加」ボタンをクリックします
-
AEM Forms配信およびランタイム API を選択
- API を追加 ダイアログで、Experience Cloudでフィルタリングします
- AEM Forms配信およびランタイム API」を選択 ます。
- 「次へ」をクリックします。
-
認証方法
- OAuth サーバー間認証方式を選択します。
4.3 製品プロファイルの追加
製品プロファイルを追加するには、次の手順に従います。
-
必要なアクセスレベルに基づいて適切な 製品プロファイル を選択します。
table 0-row-2 1-row-2 2-row-2 3-row-2 アクセスタイプ 製品プロファイル 読み取り専用アクセス AEM Users - author - Program XXX - Environment XXX読み取り/書き込みアクセス AEM Assets Collaborator Users - author - Program XXX - Environment XXX完全な管理アクセス AEM Administrators - author - Program XXX - Environment XXX -
オーサーサービス URL （）に一致する 製品プロファイル
https://author-pXXXXX-eYYYYY.adobeaemcloud.comを選択します。 例：selecthttps://author-pXXXXX-eYYYYY.adobeaemcloud.com。 -
「設定済み API を保存」をクリックします。API と製品プロファイルがプロジェクトに追加されます
4.4 資格情報の生成と保存
-
認証情報へのアクセス
- Adobe Developer Consoleでプロジェクトに移動します
- OAuth サーバー間 資格情報をクリックします。
- 「資格情報の詳細 セクションを表示します
-
レコード API 資格情報
code language-text API Credentials: ================ Client ID: <your_client_id> Client Secret: <your_client_secret> Technical Account ID: <tech_account_id> Organization ID: <org_id> Scopes: AdobeID,openid,read_organizations
4.5 アクセストークンの生成
A.テスト用
Adobe Developer Consoleで手動でアクセストークンを生成します。
-
プロジェクトへの移動
- Adobe Developer Consoleで、プロジェクトを開きます
- OAuth サーバー間 をクリックします。
-
アクセストークンの生成
- プロジェクトの「API」セクションで 「アクセストークンを生成」 ボタンをクリックします
- 生成されたアクセストークンのコピー
note note NOTE アクセストークンは 24 時間有効
B.実稼動の場合
cURL コマンドを使用してプログラムでトークンを生成します。
必要な資格情報：
- クライアント ID
- クライアントの秘密鍵
- 範囲（通常：
AdobeID,openid,read_organizations）
トークン エンドポイント：
https://ims-na1.adobelogin.com/ims/token/v3
サンプルリクエスト （curl）:
curl -X POST 'https://ims-na1.adobelogin.com/ims/token/v3' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials' \
-d 'client_id=<YOUR_CLIENT_ID>' \
-d 'client_secret=<YOUR_CLIENT_SECRET>' \
-d 'scope=AdobeID,openid,read_organizations'
応答：
{
"access_token": "eyJhbGciOiJSUz...",
"token_type": "bearer",
"expires_in": 86399
}
4.6 クライアント ID のAEMへの登録
ADC プロジェクトのクライアント ID がAEM インスタンスと通信できるようにするには、YAML 設定ファイルを使用して登録し、設定パイプラインを介してデプロイする必要があります。
-
Config ディレクトリの検索または作成
- AEM プロジェクトリポジトリのクローンに移動し、
configフォルダーに移動します - 存在しない場合は、プロジェクトのルートレベルで作成します。
code language-bash mkdir config - AEM プロジェクトリポジトリのクローンに移動し、
-
api.yamlディレクトリにconfigという名前の新しいファイルを作成します。code language-bash touch config/api.yaml -
api.yamlファイルに次のコードを追加します。code language-yaml kind: "API" version: "1" metadata: envTypes: ["dev"] # or ["prod", "stage"] for production environments data: allowedClientIDs: author: - "<your_client_id>" publish: - "<your_client_id>" preview: - "<your_client_id>"設定パラメーターを次に説明します。
-
kind：常に
"API"に設定します（API 設定として識別します） -
version:API バージョン（通常は
"1"または"1.0"） -
envTypes：この設定が適用される環境タイプの配列
["dev"]– 開発環境のみ["stage"]- ステージング環境のみ["prod"]– 実稼動環境のみ
-
allowedClientIDs:AEM インスタンスへのアクセスが許可されたクライアント ID
- オーサー：オーサー層のクライアント ID
- パブリッシュ：パブリッシュ層のクライアント ID
- preview：プレビュー層のクライアント ID
例えば、
allowedClientIDsを6bc4589785e246eda29a545d3ca55980として、envTypes をdevとして追加します。
-
-
変更のコミットとプッシュ
- クローンしたリポジトリのルートフォルダーに移動して、以下のコマンドを実行します。
code language-bash git add config/api.yaml git commit -m "Whitelist client id for api invocation" git push origin <your-branch>
-
設定パイプラインをセットアップ
-
Cloud Managerへのログイン
- my.cloudmanager.adobe.com に移動します。
- Adobe IDでログイン
-
プログラムに移動
リストからプログラムを選択すると、プログラムの概要ページにリダイレクトされます -
パイプラインカードを見つける
- プログラムの概要ページで パイプライン カードを見つけます
- 「追加 ボタンをクリ ク
-
パイプラインタイプを選択
-
開発環境の場合:「実稼動以外のパイプラインを追加」 を選択します。 実稼動以外のパイプラインは、開発環境とステージング環境用です
-
実稼動環境の場合:「実稼動パイプラインを追加」 を選択します。 実稼動パイプラインには追加の承認が必要です
note note NOTE この場合、開発環境が使用可能なので、実稼動以外のパイプラインを作成します。
-
-
パイプラインの設定 – 「設定」タブ
「設定」タブで、次のように設定します。
a. パイプラインタイプ
- 「デプロイメントパイプライン を選択
b. パイプライン名
- わかりやすい名前を指定（例：パイプラインに
api-config-pipielineという名前を付ける）
c. 導入トリガー
- 手動：手動でトリガーされた場合にのみデプロイします（初期設定で推奨）
- Git の変更時：変更がブランチにプッシュされると自動デプロイされます
d. 重要な指標のエラー動作
- 毎回確認する：失敗時にアクションを要求する（デフォルト）
- 直ちに失敗：指標の失敗時にパイプラインを自動的に失敗します
- 直ちに続行：失敗しても続行します
e. 「続行」をクリックして 「Source コード」タブに進みます
-
パイプラインを設定 – 「Source コード」タブ
「Source コード」タブで、次のように設定します。
a. デプロイメントタイプ
- 「ターゲットデプロイメント を選択
b. デプロイメントオプション
- 「Config」 を選択します（設定ファイルのみをデプロイします）。 これは、Cloud Managerに config デプロイメントであることを示しています。
c. 適格なデプロイメント環境を選択
- 設定をデプロイする環境を選択します。 この場合、これは
dev環境です。
d. Source コードの詳細を定義
- リポジトリ:
api.yamlファイルを含むリポジトリを選択します。 例えば、AEMFormsInternal-ReleaseSanity-p43162-uk59167リポジトリを選択します。 - Git ブランチ：ブランチを選択します。 例えば、この場合、コードは
mainブランチにデプロイされます。 - コードの場所：ディレクトリへのパス
config入力します。api.yamlはルートのフォルダーにあconfigので、/configと入力します
e. 「保存」 をクリックして、パイプラインを作成します
-
-
設定をデプロイ
パイプラインが作成されたら、
api.yaml設定をデプロイします。-
パイプラインの概要から
- プログラムの概要ページで、「パイプライン カードを見つけます
- リストで新しく作成した設定パイプラインに移動します。 例えば、作成したパイプライン名（「api-config-pipeline」など）を探します。 ステータスや前回の実行を含むパイプラインの詳細を確認できます。
-
デプロイメントの開始
- パイプラインの横にある 「ビルド」 ボタン（または再生アイコン ▶）をクリックします
- プロンプトが表示されたらデプロイメントを確認し、パイプラインの実行を開始します
-
デプロイメントの成功の確認
-
パイプラインが完了するのを待ちます。
-
成功すると、ステータスが「成功」（緑色のチェックマーク ✓）に変わります。
-
失敗した場合は、ステータスが「失敗」（赤十字 ✗）に変わります。 ログをダウンロード をクリックして、エラーの詳細を表示します。
-
これで、Forms Communications API のテストを開始できます。 テストの目的で、Postman、curl、またはその他の REST クライアントを使用して、API を呼び出すことができます。
-
-
手順 5:API の仕様とテスト
これで環境が設定されたので、Swagger UI を使用して、または NodeJS アプリケーションを開発してプログラムで、AEM Forms Communication API のテストを開始できます。
この例では、テンプレートと XDP ファイルを使用して Document Services API を使用してPDFを生成します。
A. API テストへの Swagger UI の使用
Swagger UI は、コードを記述せずに API をテストするためのインタラクティブなインターフェイスを備えています。試す 機能を使用して、PDFを生成 ドキュメントサービス API を呼び出してテストします。
-
API ドキュメントへの移動
- Forms API:Forms API リファレンス
- ドキュメントサービス： ドキュメントサービス API リファレンス
ブラウザーで Document Services API ドキュメントを開きます。
-
「ドキュメントの生成」セクションを展開し、「XDP またはPDF テンプレートから入力可能なPDF フォームを生成します（オプションでデータ結合も可能 」を選択します。
-
右側のウィンドウで、「試す をクリックし す。
-
以下の値を入力します。
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 セクション パラメーター 値 バケット AEM インスタンス AEM インスタンス名（Adobe ドメイン名（ .adobeaemcloud.com）を除いたもの。例えば、p43162-e177398をバケットとして使用します。セキュリティ ベアラートークン Adobe Developer Console プロジェクトの OAuth サーバー間資格情報からのアクセストークンの使用 本文 テンプレート XDP をアップロードしてPDF フォームを生成します。 例えば、 この XDP を使用してPDFを生成できます。 本文 data 事前入力されたPDF フォームを生成するためにテンプレートと結合されるデータを含む、オプションの XML ファイル。 例えば、 この XML を使用してPDFを生成できます。 パラメーター X-Adobe-Accept-Experimental 1 -
「送信」をクリックして、API を呼び出します
-
「応答 タブで応答を確認します。
- 応答コードが
200の場合は、PDFが正常に作成されたことを意味します。 - 応答コードが
400の場合は、リクエストパラメーターが無効か、形式が正しくないことを意味します。 - 応答コードが
500の場合は、内部サーバーエラーがあることを意味します。
この場合、応答コードは
200です。これは、PDFが正常に生成されたことを意味します。
これで、「 ダウンロード ボタンを使用して 作成したPDF をダウンロードし、PDF ビューアで表示できます。
- 応答コードが
B. NodeJS アプリケーションをプログラムで開発する
Document Services API を使用して、 XDP テンプレートおよび XML データファイルから入力可能なPDF フォームを生成するための Node.js アプリケーションを開発 ます。
前提条件
- システムにインストールされている Node.js
- アクティブなAEM as a Cloud Service インスタンス
- Adobe Developer Consoleからの API 認証用のベアラートークン
- サンプル XDP ファイル：ClosingForm.xdp
- サンプル XML ファイル：ClosingForm.xml
Node.js アプリケーションを開発するには、以下の開発手順に従います。
手順 1：新しい Node.js プロジェクトの作成
cmd/terminal を開き、次のコマンドを実行します。
# Create a new directory
mkdir demo-nodejs-generate-pdf
cd demo-nodejs-generate-pdf
##### Initialize Node.js project
npm init -y
手順 2：必要な依存関係のインストール
node-fetch、dotenv、form-data ライブラリをインストールして、HTTP リクエストを行い、環境変数を読み取り、フォームデータを処理します。
npm install node-fetch
npm install dotenv
npm install form-data
手順 3:package.json の更新
-
cmd/terminal を開き、コマンドを実行します。
code language-bash code .
コードエディターでプロジェクトが開きます。
-
package.jsonファイルを更新して、typeをmoduleに追加します。code language-bash { "name": "demo-nodejs-generate-pdf", "version": "1.0.0", "type": "module", "main": "index.js", }
手順 4:.env ファイルの作成
-
プロジェクトのルートレベルに.env ファイルを作成します
-
次の設定を追加し、プレースホルダーを ADC プロジェクトの OAuth サーバー間資格情報の実際の値に置き換えます。
code language-bash 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>
note note NOTE CLIENT_ID、CLIENT_SECRETおよびSCOPESをAdobe Developer Console プロジェクトからコピーできます。
手順 5:src/index.jsを作成
- プロジェク
index.jsのルートレベルにファイルを作成します - 次のコードを追加し、プレースホルダーを実際の値に置き換えます。
// Import the dotenv configuration to load environment variables from the .env file
import "dotenv/config";
// Import fetch for making HTTP requests
import fetch from "node-fetch";
import fs from "fs";
import FormData from "form-data";
// REPLACE THE FOLLOWING VALUE WITH YOUR OWN
const bucket = <bucket-value>; // Your AEM Cloud Service Bucket name
const xdpFilePath = <xdp-file>;
const xmlFilePath = <xml-file>;
// Load environment variables
const clientId = process.env.CLIENT_ID;
const clientSecret = process.env.CLIENT_SECRET;
const scopes = process.env.SCOPES;
// Adobe IMS endpoint for obtaining an access token
const adobeIMSV3TokenEndpointURL = "https://ims-na1.adobelogin.com/ims/token/v3";
// Function to get an access token
const getAccessToken = async () => {
console.log("Getting access token from IMS...");
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();
console.log("Access token received.");
return responseJSON.access_token;
};
// Function to generate PDF form from XDP and XML
const generatePDF = async () => {
const accessToken = await getAccessToken();
console.log("Generating PDF form from XDP and XML...");
// Read XDP and XML files
const xdpFile = fs.readFileSync(xdpFilePath);
const xmlFile = fs.readFileSync(xmlFilePath);
const url = `https://${bucket}.adobeaemcloud.com/adobe/document/generate/pdfform`;
const formData = new FormData();
formData.append("template", xdpFile, {
filename: "form.xdp",
contentType: "application/vnd.adobe.xdp+xml"
});
formData.append("data", xmlFile, {
filename: "data.xml",
contentType: "application/xml"
});
const response = await fetch(url, {
method: "POST",
headers: {
Authorization: `Bearer ${accessToken}`,
"X-Api-Key": clientId,
"X-Adobe-Accept-Experimental": "1",
...formData.getHeaders()
},
body: formData,
});
if (response.ok) {
const arrayBuffer = await response.arrayBuffer();
fs.writeFileSync("generatedForm.pdf", Buffer.from(arrayBuffer));
console.log("✅ PDF form generated successfully (saved as generatedForm.pdf)");
} else {
console.error("❌ Failed to generate PDF. Status:", response.status);
console.error(await response.text());
}
};
// Run the PDF generation function
generatePDF();
手順 6：アプリケーションの実行
node src/index.js
demo-nodejs-generate-pdf フォルダーにPDFが作成されます。 フォルダーに移動して、generatedForm.pdf という名前の生成されたファイルを見つけます。
生成されたPDF を開いて確認できます。
トラブルシューティング
一般的な問題と考えられる原因
問題 1:403 Forbidden エラー
症状：
- API リクエストの戻り
403 Forbidden - エラーメッセージ：アクセスが拒否されました または 権限が不十分です
- 有効なアクセストークンでも発生
考えられる原因：
- OAuth サーバー間資格情報にリンクされた製品プロファイルの権限が不十分です
- AEM オーサーのサービスユーザーグループに、必要なコンテンツパスに対する必要な権限がありません
問題 2:401 Unauthorized エラー
症状：
- API リクエストの戻り
401 Unauthorized - エラーメッセージ：トークンが無効または期限切れです
考えられる原因：
- アクセストークンが期限切れです（24 時間のみ有効）
- クライアント ID とクライアント秘密鍵が正しくないか、一致しません
- API リクエストに認証ヘッダーがないか、形式が正しくありません
問題 3:404 エラーが見つからない
症状：
- API リクエストの戻り
404 Not Found - エラーメッセージ：リソースが見つかりません または API エンドポイントが見つかりません
考えられる原因：
- クライアント ID がAEM インスタンスの
api.yaml設定に登録されていません - バケットパラメーターが正しくありません（AEM インスタンスの識別子と一致しません）
- リソース ID （フォームまたはアセット）が無効または存在しません
問題 4：サーバー間認証オプションを使用できない
症状：
- Adobe Developer Consoleで OAuth サーバー間オプションが見つからないか無効になっている
考えられる原因：
- 統合を作成するユーザーは、関連する製品プロファイルに 開発者 として追加されません
問題 5：パイプラインのデプロイメントに失敗する
症状：
- 設定パイプラインの実行に失敗
- デプロイメントログに、
api.yamlに関連するエラーが表示される
考えられる原因：
- YAML 構文（インデント、引用符、または配列形式の問題）が無効です
api.yamlが間違ったディレクトリに配置されています- 設定のクライアント ID の形式が正しくないか、正しくありません
関連記事
バッチ（非同期 API）用の環境を設定する方法については、AEM Forms as a Cloud Serviceとのバッチ処理 を参照してください。