[AEM Forms]{class="badge positive" title="適用於AEM Forms)。"}
在規則編輯器中整合API
規則編輯器中的Integrating API在早期採用者程式之下。 您可以使用您的官方電子郵件 ID 寫信至 aem-forms-ea@adobe.com,來加入早期採用者計劃,並要求存取此功能。
最適化Forms中的視覺化規則編輯器支援直接API整合,而不需要建立表單資料模型。 您可以輸入API URL (JSON格式)或透過cURL命令匯入設定,以連線至API端點。 整合後,Invoke Service動作可用於呼叫API。
表單欄位可以直接對應到API設定中定義的輸入引數。 同樣地,對於對應的API回應,可以使用 事件裝載 選項將輸出引數對應至表單欄位。
此外,視覺規則編輯器可讓您在叫用服務時定義 success 和failure處理常式。 成功處理常式會指定要在成功的API呼叫後執行的動作,而失敗處理常式會定義發生錯誤時表單的回應方式。
比較: API整合方法
API 整合設定
底下熒幕擷圖顯示API整合設定視窗:
主要組態選項
API整合設定
- 從cURL匯入:貼上現成的cURL命令來設定API整合,而非手動輸入詳細資料,例如API URL、HTTP方法、標頭和引數。
- 顯示名稱: API服務的自訂名稱。
- API URL: API服務的端點。
- 選取HTTP方法:用來呼叫API的HTTP要求方法。
- 內容型別:定義要求與回應格式。
- 需要加密: (選擇性)選取時,可以使用 function.js 中的自訂函式加密要求與回應裝載。 公開金鑰欄位出現。 在儲存API整合設定之前,請將公開金鑰貼入此欄位。
- 在使用者端執行:啟用時,會從使用者端(瀏覽器)而不是伺服器執行API呼叫。
驗證型別
- 選項:無、基本、API金鑰。
輸入引數
-
為輸入上傳JSON:上傳範例JSON檔案以自動填入輸入對應。
- 名稱: API需要的輸入引數名稱。
- 型別:輸入的資料型別(字串、數字、布林值等)。
- In:引數(查詢、標頭或內文)的位置。
- 預設值:若使用者未提供,則為預填值。
- 新增:新增其他輸入引數的選項。
輸出引數
-
為輸出上傳JSON:上傳範例API回應以自動產生對應。
- 名稱: API回應中的輸出引數名稱。
- 型別:輸出引數的預期資料型別(字串、數字等)。
- In:定義對應值的預期位置。
- 新增/刪除:新增對應或移除現有對應。
使用案例:在簽證申請表單中填入國家/地區欄位
案例:政府機構提供包含下列欄位的線上簽證申請表:
- 全名(文字)
- 出生日期(日期)
- 公民身分國家(下拉式清單)
- 護照號碼(文字)
- 護照簽發國家/地區(下拉式清單)
- 目的地國家/地區(下拉式清單)
- 預定抵達日期(日期)
此表單不會維護靜態的國家/地區清單,而是會動態擷取國家/地區資訊(大陸、資本、ISO Alpha代碼等) 使用getcountryname API:
https://secure.geonames.org/countryInfoJSON?username=aemforms
這可確保在填寫表單時,申請人一律能看到最新且正確的國家清單。
在規則編輯器中使用API整合的實作
您可以按一下規則編輯器中的「建立API整合」按鈕,整合API而不建立表單資料模型。
名稱為 getcountryname 的API服務是在規則編輯器中的 API整合組態 下設定:
- API端點URL →
https://secure.geonames.org/countryInfoJSON?username=aemforms - HTTP方法 → GET
- 內容型別 → JSON
- 輸入 →
username已傳遞為查詢引數(aemforms)。 - 輸出 →回應欄位(例如
continent、capital、countrynames、isoAlpha3和languages)已對應至表單欄位。
在 簽證申請表單 中,三個下拉式欄位(公民國家/地區、護照簽發國家/地區和目的地國家/地區)繫結至 叫用服務 動作。
表單載入時,叫用服務會從API擷取國家/地區清單。 接著會對映回應,以自動填入下拉式選項。
例如,當使用者開啟 公民權國家 時,API回應會動態顯示國家/地區清單。
同樣地,Passport Issuance和 目的地國家/地區 使用相同的API呼叫,確保所有三個欄位中的資料一致且為最新狀態。
編輯現有的API整合
建立API整合後,您可以從規則編輯器更新它,而不需要建立新的整合。 當 Invoke Service 陳述式參考API整合時,Edit選項可用於該整合。
若要編輯現有的API整合:
- 在包含 Invoke Service 陳述式的規則編輯器中開啟規則。
- 在 Invoke Service 陳述式中,選取您要更新的API整合。
- 按一下 編輯 圖示以開啟 API整合組態 視窗。
- 更新API URL、驗證、輸入和輸出引數或其他設定,並儲存變更。
加密與解密
當為API整合選取 需要加密 時,請將您的公開金鑰貼到API整合設定視窗的 公開金鑰 欄位中。 規則編輯器會在每個傳出請求前叫用encrypt,並在成功回應後叫用decrypt。 如果您未在 function.js 中新增自訂邏輯,則兩個函式都會傳回未變更的裝載。
若要加密和解密要求與回應資料,請新增 encrypt 與 decrypt 函式至function.js:
- 開啟最適化表單的 function.js 檔案。
- 新增 encrypt 函式,以便在API呼叫之前轉換請求(內文、標頭和相關選項)。
- 新增 decrypt 函式,以便在成功的API呼叫後轉換回應。 decrypt函式會收到加密的回應和originalRequest,其中包含加密期間設定的任何cryptoMetadata。
- 儲存function.js,然後在規則編輯器中使用 叫用服務 測試整合。
下列範常式式碼示範如何在 function.js 中新增 encrypt 函式:
function encrypt(payload) {
const { body, headers, options } = payload;
const { encryptedBody, encryptedKey } = await myRsaEncrypt(body);
return {
body: encryptedBody,
headers: { ...headers, 'X-Encrypted-Key': encryptedKey },
cryptoMetadata: { keyId: 'rsa-2048-v1' },
options
};
}
encrypt (預先要求裝載掛接)
encrypt函式接收具有body、標頭以及選用的 cryptoMetadata 和 選項 的裝載物件。 它會傳回相同形狀的修改版本。 選項欄位透過要求管道攜帶擷取API設定(例如,credentials: 'include')。 選項中的值已套用至基礎fetch()呼叫。 cryptoMetadata欄位儲存資料以供解密時使用。 您在加密期間在 cryptoMetadata 中設定的任何專案,都會保留在 originalRequest.cryptoMetadata 中,並於稍後提供給 decrypt 函式。 儘管名稱為何,encrypt仍是一般預先要求轉換器。 您可以用它來修改標頭或請求本文,而不僅限於密碼編譯加密。 預設實施會傳回未變更的裝載。
>>
下列範常式式碼示範了 decrypt 函式:
function decrypt(encryptedData, originalRequest) {
const { keyId } = originalRequest?.cryptoMetadata || {};
return await myRsaDecrypt(encryptedData, keyId);
}
解密(後請求回應勾點)
decrypt函式會在成功回應之後執行。 它接收回應本文和originalRequest。 originalRequest物件包含您 encrypt 函式中的cryptoMetadata,以及url、方法和其他要求中繼資料。 它必須同步或非同步傳回解密的主體。 預設實施會傳回未變更的資料。 decrypt函式只會在成功的回應上執行。 錯誤回應不會叫用decrypt。
myRsaEncrypt和myRsaDecrypt。實作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),並嘗試請求最多兩次,為每次重試新增中繼資料。
常見問題
-
我需要建立表單資料模型以整合最適化Forms中的API嗎?
不行。 使用視覺化規則編輯器,您可以使用 建立API整合 選項直接整合API,而不需要建立表單資料模型。 此方法最適合輕量型或特定表單的使用案例。 -
我可以保護從規則編輯器發出的API呼叫嗎?
可以。 API整合組態提供驗證選項,例如 基本 和API金鑰。 您也可以選取「需要加密」,並在 function.js 中新增自訂 encrypt 和 decrypt 邏輯。 如需設定步驟與範例,請參閱加密與解密。