[AEM Forms]{class="badge positive" title="S’applique à AEM Forms)."}

Intégration de l’API dans l’éditeur de règles

L’intégration de l’API dans l’éditeur de règles se trouve dans le programme des utilisateurs précoces. Vous pouvez écrire à aem-forms-ea@adobe.com depuis votre adresse e-mail officielle pour rejoindre le programme d’accès anticipé et demander l’accès à la fonctionnalité.

L’éditeur visuel de règles d’un Forms adaptatif prend en charge l’intégration directe d’API sans créer de modèle de données de formulaire. Vous pouvez vous connecter à un point d’entrée de l’API en saisissant l’URL de l’API (au format JSON) ou en important la configuration via une commande cURL. Une fois intégrée, l’action Invoke Service peut être utilisée pour appeler l’API.

Les champs de formulaire peuvent être mappés directement aux paramètres d’entrée définis dans la configuration de l’API. De même, les paramètres de sortie peuvent être mappés à des champs de formulaire à l’aide de l’option payload d’événement pour la réponse d’API correspondante.

En outre, l’éditeur visuel de règles vous permet de définir des gestionnaires succès et échec lors de l’appel d’un service. Les gestionnaires de succès spécifient les actions à exécuter après un appel API réussi, tandis que les gestionnaires d’échec définissent la manière dont le formulaire doit répondre lorsqu’une erreur se produit.

Comparaison : méthodes d’intégration d’API

Configuration d’intégration d’API

La capture d’écran ci-dessous affiche la fenêtre de configuration de l’intégration API :

Principales options de configuration

Configuration de l’intégration de l’API

Type d’authentification

Paramètres d’entrée

Paramètres de sortie

Cas pratique : remplir les champs Pays dans un formulaire de demande de visa

Scénario : Une agence gouvernementale fournit un formulaire de demande de visa en ligne avec les champs suivants :

Au lieu de conserver une liste statique de pays, le formulaire récupère dynamiquement les informations de pays (continent, capitale, codes ISO Alpha, etc.) à l’aide de l’API getcounname :

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

Cela garantit que les candidats voient toujours une liste actualisée et précise des pays tout en remplissant le formulaire.

Implémentation à l’aide de l’intégration d’API dans l’éditeur de règles

Vous pouvez intégrer une API sans créer de modèle de données de formulaire en cliquant sur le bouton Créer une intégration d’API dans l’éditeur de règles.

Un service d’API nommé getcontendname est configuré sous Configuration de l’intégration de l’API dans l’éditeur de règles :

Dans le Formulaire de demande de visa, les trois champs déroulants Pays de citoyenneté, Pays de délivrance du passeport et Pays de destination sont liés à l’action Invoquer le service.

Lorsque le formulaire se charge, la fonction Invoquer le service récupère la liste des pays à partir de l’API. La réponse est ensuite mappée pour renseigner automatiquement les options de liste déroulante.

Par exemple, lorsque l’utilisateur ouvre Pays de citoyenneté, la liste des pays s’affiche de manière dynamique à partir de la réponse de l’API.

De même, les Pays d’émission du passeport et Pays de destination utilisent le même appel API, ce qui garantit des données cohérentes et à jour dans les trois champs.

Modifier une intégration d’API existante

Après avoir créé une intégration d’API, vous pouvez la mettre à jour à partir de l’éditeur de règles sans créer de nouvelle intégration. Lorsqu’une instruction Invoke Service fait référence à une intégration d’API, une option Modifier est disponible pour cette intégration.

Pour modifier une intégration d’API existante :

Chiffrement et déchiffrement

Lorsque Chiffrement requis est sélectionné pour une intégration d’API, collez votre clé publique dans le champ Clé publique de la fenêtre de configuration de l’intégration d’API. L’éditeur de règles appelle chiffrer avant chaque requête sortante et déchiffrer après une réponse réussie. Si vous n’ajoutez pas de logique personnalisée dans function.js, les deux fonctions renvoient la payload inchangée.

Pour chiffrer et déchiffrer les données de requête et de réponse, ajoutez les fonctions chiffrer et déchiffrer à function.js :

L’exemple de code suivant montre comment ajouter la fonction encrypt dans function.js :

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

chiffrer (hook de payload de pré-requête)

La fonction encrypt reçoit un objet de payload avec body, headers, cryptoMetadata et options facultatifs. Elle renvoie une version modifiée de la même forme. Le champ options transfère les paramètres de l’API de récupération (par exemple, credentials: 'include') via le pipeline de requêtes. Les valeurs de options sont appliquées à l’appel fetch() sous-jacent. Le champ cryptoMetadata stocke les données à utiliser lors du déchiffrement. Tout ce que vous définissez dans cryptoMetadata pendant le chiffrement est conservé dans originalRequest.cryptoMetadata et mis à la disposition de la fonction decrypt ultérieurement. Malgré son nom, encrypt est un transformateur de pré-requête général. Vous pouvez l’utiliser pour modifier les en-têtes ou le corps de la requête, pas seulement pour le chiffrement cryptographique. L’implémentation par défaut renvoie la payload inchangée.
​>>

L’exemple de code suivant illustre une fonction decrypt :

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

déchiffrer (hook de réponse de post-requête)

La fonction decrypt s’exécute après une réponse réussie. Il reçoit le corps de la réponse et originalRequest. L’objet originalRequest comprend cryptoMetadata provenant de votre fonction encrypt, ainsi que url, method et d’autres métadonnées de requête. Il doit renvoyer le corps déchiffré de manière synchrone ou asynchrone. L’implémentation par défaut renvoie les données inchangées. La fonction decrypt s’exécute uniquement en cas de réponses réussies. Les réponses d’erreur n’appellent pas déchiffrer.

Mise en œuvre du mécanisme de reprise en cas d’échec de l’API

Lorsqu’une requête d’API échoue, il est souvent utile de relancer la requête avant de signaler une erreur à l’utilisateur. Vous pouvez implémenter un mécanisme d’interrogation et de reprise en écrivant du code personnalisé dans le fichier function.js.

L’exemple suivant montre comment gérer les échecs d’API avec jusqu’à deux tentatives de reprise et un retour exponentiel entre les reprises :

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

Dans le code ci-dessus, la fonction retryHandler gère les requêtes d’API avec des reprises automatiques en cas d’échec. Il prend une fonction de requête (requestFn) et tente de soumettre la requête jusqu’à deux fois, en ajoutant des métadonnées pour chaque nouvelle tentative.

Questions fréquentes