[AEM Forms]{class="badge positive" title="Gilt für AEM Forms)."}

Integrieren der API im Regeleditor

Die Integration der API im Regeleditor erfolgt im Rahmen des Early-Adopter-Programms. Sie können von Ihrer offiziellen E-Mail-ID an aem-forms-ea@adobe.com schreiben, um dem Early-Adopter-Programm beizutreten und Zugriff auf die Funktion anzufordern.

Der Visual Rule Editor in Adaptive Forms unterstützt die direkte API-Integration ohne Erstellen eines Formulardatenmodells. Sie können eine Verbindung zu einem API-Endpunkt herstellen, indem Sie entweder die API-URL (im JSON-Format) eingeben oder die Konfiguration über einen cURL-Befehl importieren. Nach der Integration kann Aktion „Service" verwendet werden, um die API aufzurufen.

Formularfelder können direkt den Eingabeparametern zugeordnet werden, die in der API-Konfiguration definiert sind. Ebenso können Ausgabeparameter mithilfe der Option Ereignis-Payload“ für die entsprechende API-Antwort Formularfeldern werden.

Darüber hinaus können Sie mit dem visuellen Regeleditor beim Aufrufen Services Erfolgs und Fehlerhandler“ definieren. Erfolgs-Handler geben die Aktionen an, die nach einem erfolgreichen API-Aufruf ausgeführt werden sollen, während Fehler-Handler definieren, wie das Formular auf einen Fehler reagieren soll.

Vergleich: API-Integrationsmethoden

Konfiguration der API-Integration

Im folgenden Screenshot sehen Sie das Konfigurationsfenster für die API-Integration:

Wichtige Konfigurationsoptionen

API-Integrationskonfiguration

Authentifizierungstyp

Eingabeparameter

Ausgabeparameter

Anwendungsfall: Ausfüllen von Länderfeldern in einem Visumantragsformular

Szenario: Eine Regierungsbehörde stellt ein Online-Antragsformular für ein Visum mit den folgenden Feldern bereit:

Anstatt eine statische Liste von Ländern zu verwalten, ruft das Formular dynamisch Länderinformationen ab (Kontinent, Hauptstadt, ISO-Alpha-Codes usw.) mithilfe der getCountryName-API:

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

Dadurch wird sichergestellt, dass Antragsteller beim Ausfüllen des Formulars stets eine aktuelle und genaue Liste der Länder erhalten.

Implementierung mithilfe der API-Integration im Regeleditor

Sie können eine API integrieren, ohne ein Formulardatenmodell zu erstellen, indem Sie im Regeleditor auf API-Integration erstellen klicken.

Ein API-Service mit dem getCountryName wird unter API-Integrationskonfiguration im Regeleditor konfiguriert:

Im Visumantragsformular sind die drei Dropdown-Felder Land der, Land der Passausstellung und Zielland an die Aktion Dienst aufrufen gebunden.

Beim Laden des Formulars ruft Dienst aufrufen die Liste der Länder aus der API ab. Die Antwort wird dann zugeordnet, um die Dropdown-Optionen automatisch auszufüllen.

Wenn der/die Benutzende beispielsweise Land der Staatsangehörigkeit öffnet, wird die Liste der Länder dynamisch aus der API-Antwort angezeigt.

Ebenso verwenden Land der Passausstellung und Zielland denselben API-Aufruf, um konsistente und aktuelle Daten in allen drei Feldern sicherzustellen.

Bearbeiten einer vorhandenen API-Integration

Nachdem Sie eine API-Integration erstellt haben, können Sie sie über den Regeleditor aktualisieren, ohne eine neue Integration zu erstellen. Wenn eine Invoke Service-Anweisung auf eine API-Integration verweist ist für diese Integration eine Bearbeiten“ verfügbar.

So bearbeiten Sie eine vorhandene API-Integration:

Verschlüsselung und Entschlüsselung

Wenn Verschlüsselung erforderlich für eine API-Integration ausgewählt ist, fügen Sie Ihren öffentlichen Schlüssel in das Feld Öffentlicher Schlüssel im Konfigurationsfenster der API-Integration ein. Der Regeleditor ruft vor jeder ausgehenden Anfrage verschlüsseln auf und nach Antwort „entschlüsseln“. Wenn Sie in „function.js“ keine benutzerdefinierte Logik , beide Funktionen die Payload unverändert zurück.

Um Anfrage- und Antwortdaten zu ver- und entschlüsseln, fügen Sie "" "" Funktionen zu function.js:

Im folgenden Beispielcode wird veranschaulicht, wie die Funktion encrypt in ".js“ hinzugefügt:

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
    };
}

Verschlüsseln (Payload-Hook für die Anfrage)

Die encrypt-Funktion empfängt ein Payload-Objekt mit body, headers und optional cryptoMetadata und options. Gibt eine geänderte Version derselben Form zurück. Das options-Feld übernimmt Abrufen von API-Einstellungen (z. B. credentials: 'include') über die Anfrage-Pipeline. Werte in options werden auf den zugrunde liegenden fetch() angewendet. Das cryptoMetadata-Feld speichert Daten für die Verwendung während der Entschlüsselung. Was Sie in cryptoMetadata während der Verschlüsselung festlegen, wird in originalRequest.cryptoMetadata beibehalten und später für die decrypt-Funktion verfügbar gemacht. Trotz des Namens encrypt ein allgemeiner Pre-Request-Transformator. Sie können damit Kopfzeilen oder den Anfragetext ändern, nicht nur zur kryptografischen Verschlüsselung. Die Standardimplementierung gibt die Payload unverändert zurück.
​>>

Der folgende Beispiel-Code veranschaulicht eine ""-:

function decrypt(encryptedData, originalRequest) {
    const { keyId } = originalRequest?.cryptoMetadata || {};
    return await myRsaDecrypt(encryptedData, keyId);
}

Entschlüsseln (Hook für POST-Anforderungsantwort)

Die Funktion decrypt wird nach einer erfolgreichen Antwort ausgeführt. Sie erhält den Antworttext und originalRequest. Das originalRequest-Objekt enthält cryptoMetadata aus Ihrer encrypt-Funktion zusammen mit url, method und anderen Anfragemetadaten. Er muss den entschlüsselten Text synchron oder asynchron zurückgeben. Die Standardimplementierung gibt die Daten unverändert zurück. Die Funktion decrypt wird nur bei erfolgreichen Antworten ausgeführt. Fehlerantworten rufen nicht auf decrypt.

Implementieren des Wiederholungsmechanismus bei API-Fehlern

Wenn eine API-Anfrage fehlschlägt, ist es oft nützlich, die Anfrage erneut auszuführen, bevor dem Benutzer ein Fehler gemeldet wird. Sie können einen Abruf- und Wiederholungsmechanismus implementieren, indem Sie benutzerdefinierten Code in die Datei function.js schreiben.

Das folgende Beispiel zeigt, wie API-Fehler mit bis zu zwei Wiederholungsversuchen und einem exponentiellen Backoff zwischen Wiederholungsversuchen gehandhabt werden:

/**
 * 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);
}

Im obigen Code verwaltet die Funktion retryHandler API-Anfragen mit automatischen Wiederholungsversuchen im Falle eines Fehlers. Es dauert eine Anfragefunktion (requestFn) und versucht die Anfrage bis zu zweimal, wobei für jeden erneuten Versuch Metadaten hinzugefügt werden.

Häufig gestellte Fragen