AEM Forms as a Cloud Service通信同步API处理
本指南提供了有关设置和使用AEM Forms Communications Synchronous API的全面说明。
了解如何使用OAuth服务器到服务器身份验证配置AEM as a Cloud Service环境、启用API访问和调用通信API。
先决条件
要设置用于运行和测试AEM Forms Communications API的环境，请确保您具备以下条件：
访问和权限
在开始配置Communications 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的最新版本
- 访问终端/命令行
- 用于编辑配置文件（VS代码、IntelliJ等）的文本编辑器或IDE
- 用于API测试的 Postman 或类似工具
现在，让我们详细了解每个步骤。
步骤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云服务环境和AEM Forms端点
访问您的AEM Cloud Service环境详细信息，以获取API配置所需的URL和标识符。
-
登录Adobe Cloud Manager
- 导航到my.cloudmanager.adobe.com
- 使用您的Adobe ID登录
-
导航到计划概述
从列表中选择您的项目。 您将被重定向到项目概述页面 -
访问和查看AEM云服务环境
您可以使用以下两个选项之一查看或访问AEM Cloud Service环境详细信息：
-
选项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 - Bucket： publish-pXXXXX-eYYYY
示例：https://publish-author-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通信API
您可以根据自己的要求添加其他AEM Forms Communications API。
A。对于Document Services API
-
单击添加API
-
选择Forms通信API
- 在 添加API 对话框中，按 Experience Cloud 筛选
- 选择“Forms通信API”
-
选择 OAuth服务器到服务器 身份验证方法
B。用于Forms运行时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。 例如：选择https://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。用于生产
使用Adobe IMS API以编程方式生成令牌：
必需的凭据：
- 客户端 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在AEM Environment中注册客户端ID
要使ADC项目的客户端ID能够与AEM实例进行通信，您必须使用YAML配置文件注册它，并通过配置管道进行部署。
-
查找或创建配置目录
- 导航到克隆的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配置） -
版本： API版本，通常为
"1"或"1.0" -
envTypes：此配置适用的环境类型数组
["dev"]— 仅开发环境["stage"]— 仅暂存环境["prod"]— 仅生产环境
-
allowedClientIDs：允许客户端ID访问您的AEM实例
- 作者：作者层的客户端ID
- 发布：发布层的客户端ID
- 预览：预览层的客户端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代码 选项卡
-
配置Pipeline - Source代码选项卡
在 Source代码 选项卡中：
a. 部署类型
- 选择“目标部署”
b. 部署选项
- 选择“配置”（仅部署配置文件）。 它告知Cloud Manager这是一个配置部署。
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.使用Swagger UI进行API测试
Swagger UI提供了一个用于测试API而不编写代码的交互式界面。使用 尝试它 功能调用和测试生成PDF文档服务API。
-
导航到API文档
- Forms API：Forms API引用
- 文档服务： 文档服务API引用
在浏览器中打开Document Services API文档。
-
展开 Document Generation 部分并选择从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。 主体 数据 包含要与模板合并以生成预填充PDF表单的数据的可选XML文件。 例如，您可以使用此XML来生成PDF。 参数 X-Adobe-Accept-Experimental 1 -
单击 发送 以调用API
-
检查 响应 选项卡中的响应：
- 如果响应代码为
200，则表示已成功创建PDF。 - 如果响应代码为
400，则表示请求参数无效或格式不正确。 - 如果响应代码为
500，则表示存在内部服务器错误。
在这种情况下，响应代码为
200，这表示已成功生成PDF：
现在，您可以使用下载按钮下载 创建的PDF 并在PDF查看器中查看它：
- 如果响应代码为
B.以编程方式开发NodeJS应用程序
开发Node.js应用程序以使用 Document Services API 从 XDP 模板和 XML 数据文件生成可填写的PDF表单
先决条件
- 系统上安装的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 您可以从Adobe Developer Console项目中复制 CLIENT_ID、CLIENT_SECRET和SCOPES。
步骤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禁止的错误
症状：
- API请求返回
403 Forbidden - 错误消息： 访问被拒绝或权限不足
- 即使使用有效的访问令牌也会发生
可能的原因：
- 链接到OAuth服务器到服务器凭据的产品配置文件中的权限不足
- AEM Author中的服务用户组缺少所需内容路径的必要权限
问题2： 401未授权错误
症状：
- API请求返回
401 Unauthorized - 错误消息： 令牌无效或过期
可能的原因：
- 访问令牌已过期（仅在24小时内有效）
- 客户端ID和客户端密钥不正确或不匹配
- API请求中的身份验证标头缺失或格式不正确
问题3:404 “未找到”错误
症状：
- API请求返回
404 Not Found - 错误消息：未找到资源或找不到API终结点
可能的原因：
- 未在AEM实例的
api.yaml配置中注册客户端ID - 存储段参数不正确(不符合AEM实例标识符)
- 资源ID（表单或资源）无效或不存在
问题4：服务器到服务器身份验证选项不可用
症状：
- Adobe Developer Console中缺少或禁用了OAuth服务器到服务器选项
可能的原因：
- 创建集成的用户未添加为关联产品配置文件中的开发人员
问题5：管道部署失败
症状：
- 配置管道执行失败
- 部署日志显示与
api.yaml相关的错误
可能的原因：
- YAML语法无效（缩进、引号或数组格式问题）
api.yaml放置在不正确的目录中- 配置中的客户端ID格式不正确或不正确
相关文章
要了解如何为批处理（异步API）设置环境，请参阅AEM Forms as a Cloud Service Communications批处理。