[AEM Forms]{class="badge positive" title="適用於AEM Forms)。"}

在規則編輯器中整合API

規則編輯器中的Integrating API在早期採用者程式之下。 您可以使用您的官方電子郵件 ID 寫信至 aem-forms-ea@adobe.com,來加入早期採用者計劃,並要求存取此功能。

NOTE
視覺化規則編輯器支援Adaptive Forms中的API整合(根據核心元件和在Universal Editor🔗中編寫的Edge Delivery Services Forms)。

最適化Forms中的視覺化規則編輯器支援直接API整合,而不需要建立表單資料模型。 您可以輸入API URL (JSON格式)或透過cURL命令匯入設定,以連線至API端點。 整合後,Invoke Service​動作可用於呼叫API。

表單欄位可以直接對應到API設定中定義的輸入引數。 同樣地,對於對應的API回應,可以使用​ 事件裝載 ​選項將輸出引數對應至表單欄位。

此外,視覺規則編輯器可讓您在叫用服務時定義​ success ​和​failure處理常式。 成功處理常式會指定要在成功的API呼叫後執行的動作,而失敗處理常式會定義發生錯誤時表單的回應方式。

比較: API整合方法

層面
API與表單資料模型(FDM)整合
直接API整合(透過​建立API整合
用途
跨多個表單的集中式、可重複使用的API整合
快速、表單特定的API整合
安裝位置
在表單資料模型編輯器(AEM主控台)中建立和編輯
直接在自適應表單規則編輯器中建立和編輯
複雜度
更高的設定工作量(需要對應和設定)
簡單輕量
最適合
具有多種表單的企業或大型使用案例
小型表單、原型或一次性API呼叫

API 整合設定

底下熒幕擷圖顯示API整合設定視窗:

API整合設定

主要組態選項

API整合設定

  • 從cURL匯入:貼上現成的cURL命令來設定API整合,而非手動輸入詳細資料,例如API URL、HTTP方法、標頭和引數。
  • 顯示名稱: API服務的自訂名稱。
  • API URL: API服務的端點。
  • 選取HTTP方法:用來呼叫API的HTTP要求方法。
  • 內容型別:定義要求與回應格式。
  • 需要加密: (選擇性)選取時,可以使用​ function.js ​中的自訂函式加密要求與回應裝載。 公開金鑰​欄位出現。 在儲存API整合設定之前,請將公開金鑰貼入此欄位。
  • 在使用者端執行:啟用時,會從使用者端(瀏覽器)而不是伺服器執行API呼叫。
NOTE
如需步驟與範例​ encrypt ​與​ decrypt ​函式,請參閱加密與解密

驗證型別

  • 選項:無、基本、API金鑰。

輸入引數

  • 為輸入上傳JSON:上傳範例JSON檔案以自動填入輸入對應。

    • 名稱: API需要的輸入引數名稱。
    • 型別:輸入的資料型別(字串、數字、布林值等)。
    • In:引數(查詢、標頭或內文)的位置。
    • 預設值:若使用者未提供,則為預填值。
    • 新增:新增其他輸入引數的選項。

輸出引數

  • 為輸出上傳JSON:上傳範例API回應以自動產生對應。

    • 名稱: API回應中的輸出引數名稱。
    • 型別:輸出引數的預期資料型別(字串、數字等)。
    • In:定義對應值的預期位置。
    • 新增/刪除:新增對應或移除現有對應。

使用案例:在簽證申請表單中填入國家/地區欄位

案例:政府機構提供包含下列欄位的線上簽證申請表:

  1. 全名(文字)
  2. 出生日期(日期)
  3. 公民身分國家(下拉式清單)
  4. 護照號碼(文字)
  5. 護照簽發國家/地區(下拉式清單)
  6. 目的地國家/地區(下拉式清單)
  7. 預定抵達日期(日期)

此表單不會維護靜態的國家/地區清單,而是會動態擷取國家/地區資訊(大陸、資本、ISO Alpha代碼等) 使用​getcountryname API

https://secure.geonames.org/countryInfoJSON?username=aemforms

這可確保在填寫表單時,申請人一律能看到最新且正確的國家清單。

在規則編輯器中使用API整合的實作

您可以按一下規則編輯器中的「建立API整合」按鈕,整合API而不建立表單資料模型。

建立API整合

名稱為​ getcountryname ​的API服務是在規則編輯器中的​ API整合組態 ​下設定:

API REST端點設定

  • API端點URLhttps://secure.geonames.org/countryInfoJSON?username=aemforms
  • HTTP方法 → GET
  • 內容型別 → JSON
  • 輸入username已傳遞為查詢引數(aemforms)。
  • 輸出 →回應欄位(例如continentcapitalcountrynamesisoAlpha3languages)已對應至表單欄位。

在​ 簽證申請表單 ​中,三個下拉式欄位(公民國家/地區護照簽發國家/地區​和​目的地國家/地區)繫結至​ 叫用服務 ​動作。

表單載入時,叫用服務​會從API擷取國家/地區清單。 接著會對映回應,以自動填入下拉式選項。

例如,當使用者開啟​ 公民權國家 ​時,API回應會動態顯示國家/地區清單。

invoke-service-api-integration

API整合輸出

同樣地,Passport Issuance​和​ 目的地國家/地區 ​使用相同的API呼叫,確保所有三個欄位中的資料一致且為最新狀態。

NOTE
您可以叫用API並使用自訂函式🔗,從JSON陣列擷取屬性值。 此方法可讓您擷取值,並將其直接繫結至表單欄位。

編輯現有的API整合

建立API整合後,您可以從規則編輯器更新它,而不需要建立新的整合。 當​ Invoke Service ​陳述式參考API整合時,Edit​選項可用於該整合。

若要編輯現有的API整合:

  1. 在包含​ Invoke Service ​陳述式的規則編輯器中開啟規則。
  2. 在​ Invoke Service ​陳述式中,選取您要更新的API整合。
  3. 按一下​ 編輯 ​圖示以開啟​ API整合組態 ​視窗。
  4. 更新API URL、驗證、輸入和輸出引數或其他設定,並儲存變更。

編輯API整合

加密與解密

當為API整合選取​ 需要加密 ​時,請將您的公開金鑰貼到API整合設定視窗的​ 公開金鑰 ​欄位中。 規則編輯器會在每個傳出請求前叫用​encrypt,並在成功回應後叫用​decrypt。 如果您未在​ function.js ​中新增自訂邏輯,則兩個函式都會傳回未變更的裝載。

若要加密和解密要求與回應資料,請新增​ encrypt ​與​ decrypt ​函式至​function.js

  1. 開啟最適化表單的​ function.js ​檔案。
  2. 新增​ encrypt ​函式,以便在API呼叫之前轉換請求(內文、標頭和相關選項)。
  3. 新增​ decrypt ​函式,以便在成功的API呼叫後轉換回應。 decrypt​函式會收到加密的回應和​originalRequest,其中包含加密期間設定的任何​cryptoMetadata
  4. 儲存​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​函式會在成功回應之後執行。 它接收回應本文和​originalRequestoriginalRequest​物件包含您​ encrypt ​函式中的​cryptoMetadata,以及​url方法​和其他要求中繼資料。 它必須同步或非同步傳回解密的主體。 預設實施會傳回未變更的資料。 decrypt​函式只會在成功的回應上執行。 錯誤回應不會叫用​decrypt

NOTE
在上述範例中,以您的加密函式取代myRsaEncryptmyRsaDecrypt

實作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 ​邏輯。 如需設定步驟與範例,請參閱加密與解密

recommendation-more-help
experience-manager-cloud-service-help-main-toc