[AEM Forms]{class="badge positive" title="适用于AEM Forms)。"}
在规则编辑器中集成API
规则编辑器中的Integrating API位于早期采用程序程序下。 您可以通过您的官方电子邮件 ID 向 aem-forms-ea@adobe.com 发送电子邮件,以加入早期采用者计划并请求对该功能的访问权限。
自适应Forms中的可视规则编辑器支持直接API集成,而无需创建表单数据模型。 您可以通过输入API URL(以JSON格式)或通过cURL命令导入配置来连接到API端点。 集成后,调用服务操作可用于调用API。
表单字段可以直接映射到API配置中定义的输入参数。 同样,可以使用相应API响应的 事件有效负载 选项将输出参数映射到表单字段。
此外,可视规则编辑器允许您在调用服务时定义 success 和failure处理程序。 成功处理程序指定在成功API调用后要执行的操作,而失败处理程序定义表单在错误发生时应如何响应。
比较: API集成方法
API 集成配置
以下屏幕截图显示API集成配置窗口:
关键配置选项
API集成配置
- 从cURL导入:通过粘贴现成的cURL命令配置API集成,而不是手动输入详细信息,如API URL、HTTP方法、标头和参数。
- 显示名称: API服务的自定义名称。
- API URL: API服务的端点。
- 选择HTTP方法:用于调用API的HTTP请求方法。
- 内容类型:定义请求和响应格式。
- 需要加密: (可选)确保在传输期间对敏感数据进行加密。
- 在客户端执行:启用后,将从客户端(浏览器)而不是服务器执行API调用。
身份验证类型
- 选项:无、基本、API密钥、OAuth 2.0。
输入参数
-
上载输入的JSON:上载示例JSON文件以自动填充输入映射。
- 名称: API所需的输入参数名称。
- 类型:输入的数据类型(字符串、数字、布尔等)。
- In:参数(查询、标头或正文)的位置。
- 默认值:如果未由用户提供,则为预填充值。
- 添加:用于添加其他输入参数的选项。
输出参数
-
上载输出的JSON:上载示例API响应以自动生成映射。
- 名称: API响应中的输出参数名称。
- 类型:输出参数的预期数据类型(字符串、数字等)。
- In:定义需要映射值的位置。
- 添加/删除:添加新映射或删除现有映射。
用例:在签证申请表中填写国家/地区字段
方案:政府机构提供包含以下字段的在线签证申请表:
- 全名(文本)
- 出生日期(日期)
- 国籍国家/地区(下拉列表)
- 护照号码(文本)
- 护照签发国家/地区(下拉列表)
- 目标国家/地区(下拉列表)
- 预定到达日期(日期)
表单使用 getcountryname API 动态获取国家/地区信息(大陆、资本、ISO Alpha代码等),而不是维护静态的国家/地区列表:
https://secure.geonames.org/countryInfoJSON?username=aemforms
这可确保在填写表单时始终看到最新的准确国家/地区列表。
在规则编辑器中使用API集成进行实施
您可以通过单击规则编辑器中的 创建API集成 按钮,在不创建表单数据模型的情况下集成API。
在规则编辑器中的 API集成配置 下配置了名为 getcountryname 的API服务:
- API终结点URL →
https://secure.geonames.org/countryInfoJSON?username=aemforms - GET→的HTTP方法
- 内容类型→JSON
- 输入→
username作为查询参数(aemforms)传递。 - 输出 →响应字段(如
continent、capital、countrynames、isoAlpha3和languages)映射到表单字段。
在 Visa申请表 中,三个下拉字段公民国家/地区、Passport颁发国家/地区和 目的地国家/地区 将绑定到 调用服务 操作。
加载表单时,调用服务从API获取国家/地区列表。 然后,将映射响应以自动填充下拉选项。
例如,当用户打开 公民国家/地区 时,将从API响应动态显示国家/地区列表。
同样,Passport Issuance国家/地区和 目标国家/地区 使用相同的API调用,确保所有三个字段中的数据一致且最新。
您可以通过调用API并使用自定义函数从JSON数组检索属性值。 此方法允许您提取值并将其直接绑定到表单字段。
实施API失败的重试机制
当API请求失败时,在向用户报告错误之前重试请求通常很有用。 通过在 function.js 文件中写入自定义代码,您可以实施轮询和重试机制。
以下示例演示了如何处理最多包含两次重试和两次重试之间的指数回退的API失败:
/**
* Handles request retries with up to 2 retry attempts
* @param {function} requestFn - The request function to execute
* @return {Promise} A promise that resolves with the response or rejects after all retries
*/
function retryHandler(requestFn) {
const MAX_RETRIES = 2;
/**
* Attempts the request with retry metadata
* @param {number} retryCount - Current retry attempt count
* @return {Promise} The request promise
*/
function attemptRequest(retryCount = 0) {
// Include retry metadata if this is a retry
const requestOptions = retryCount > 0 ? {
headers: {
'X-Retry': 'true',
'X-Retry-Count': retryCount.toString(),
'X-Retry-Time': new Date().toISOString()
},
body: {
retry: true,
retryCount: retryCount,
timestamp: Date.now()
}
} : undefined;
return requestFn(requestOptions)
.then(function(response) {
if (response && response.status >= 400) {
console.warn('Request failed with status ' + response.status);
throw new Error('Request failed with status ' + response.status);
}
return response;
})
.catch(function(error) {
console.warn('Request attempt ' + (retryCount + 1) + ' failed:', error.message);
// Retry if max attempts not reached
if (retryCount < MAX_RETRIES) {
console.log('Retrying request, attempt ' + (retryCount + 2) + ' of ' + (MAX_RETRIES + 1));
// Exponential backoff delay: 1s, 2s, 4s...
const delay = Math.pow(2, retryCount) * 1000;
return new Promise(function(resolve) {
setTimeout(resolve, delay);
}).then(function() {
return attemptRequest(retryCount + 1);
});
} else {
// All retries exhausted
console.error('All retry attempts failed. Final error:', error.message);
throw new Error('Request failed after ' + (MAX_RETRIES + 1) + ' attempts: ' + error.message);
}
});
}
// Start the first attempt
return attemptRequest(0);
}
在上述代码中,retryHandler函数通过自动重试管理API请求,以防失败。 它使用一个请求函数(requestFn),最多尝试请求两次,为每次重试添加元数据。
常见问题解答
-
我是否需要创建表单数据模型以集成Adaptive Forms中的API?
不行。通过可视化规则编辑器,您可以使用 创建API集成 选项直接集成API,而无需创建表单数据模型。 此方法最适合轻量级或特定于表单的用例。 -
我能否保护从规则编辑器发出的API调用?
是。API集成配置提供身份验证选项,如基本、API密钥和OAuth 2.0。 您还可以启用 需要加密 以确保安全传输敏感数据。