在規則編輯器中整合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要求方法。
- 內容型別:定義要求與回應格式。
- 需要加密: (選擇性)確保在傳輸期間加密機密資料。
- 在使用者端執行:啟用時,會從使用者端(瀏覽器)而不是伺服器執行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而不建立表單資料模型。
名稱為 getcountryname 的API服務是在規則編輯器中的 API整合組態 下設定:
- API端點URL →
https://secure.geonames.org/countryInfoJSON?username=aemforms - GET→的HTTP方法
- 內容型別 → JSON
- 輸入 →
username已傳遞為查詢引數(aemforms)。 - 輸出 →回應欄位(例如
continent、capital、countrynames、isoAlpha3和languages)已對應至表單欄位。
在 簽證申請表單 中,三個下拉式欄位(公民國家/地區、護照簽發國家/地區和目的地國家/地區)繫結至 叫用服務 動作。
表單載入時,叫用服務會從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),並嘗試請求最多兩次,為每次重試新增中繼資料。
常見問題
-
我需要建立表單資料模型以整合最適化Forms中的API嗎?
不行。使用視覺化規則編輯器,您可以使用 建立API整合 選項直接整合API,而不需要建立表單資料模型。 此方法最適合輕量型或特定表單的使用案例。 -
我可以保護從規則編輯器發出的API呼叫嗎?
可以。API整合設定提供驗證選項,例如Basic、API Key和OAuth 2.0。 您也可以啟用需要加密,以確保機密資料的安全傳輸。