[AEM Forms]{class="badge positive" title="Aplicável ao AEM Forms)."}

Integração da API no Editor de regras

A integração da API no Editor de regras está no Programa de Primeiros Usuários. Você pode escrever para aem-forms-ea@adobe.com com sua ID de email oficial para entrar no programa de primeiros usuários e solicitar acesso ao recurso.

O Editor de regras visuais no Adaptive Forms oferece suporte à integração direta de API sem criar um Modelo de dados de formulário. Você pode se conectar a um endpoint de API inserindo o URL da API (no formato JSON) ou importando a configuração por meio de um comando cURL. Depois de integrada, a ação Invocar Serviço pode ser usada para chamar a API.

Os campos de formulário podem ser mapeados diretamente para os parâmetros de entrada definidos na configuração da API. Da mesma forma, os parâmetros de saída podem ser mapeados para campos de formulário usando a opção carga do evento para a resposta da API correspondente.

Além disso, o Editor de Regras Visuais permite que você defina sucesso e manipuladores de falha ao invocar um serviço. Os manipuladores de sucesso especificam as ações a serem executadas após uma chamada de API bem-sucedida, enquanto os manipuladores de falha definem como o formulário deve responder quando ocorrer um erro.

Comparação: Métodos de integração de API

Configuração da integração da API

A captura de tela abaixo exibe a janela de configuração da integração de API:

Opções de configuração de chave

Configuração de Integração de API

Tipo de autenticação

Parâmetros de entrada

Parâmetros de saída

Caso de uso: Preencher campos do país em um formulário de solicitação de visto

Cenário: uma agência governamental fornece um Formulário de Solicitação de Visto online com os seguintes campos:

Em vez de manter uma lista estática de países, o formulário busca dinamicamente informações de países (continente, capital, códigos ISO Alpha etc.) usando a API getcountryname:

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

Isso garante que os candidatos sempre vejam uma lista atualizada e precisa de países enquanto preenchem o formulário.

Implementação usando a integração de API no Editor de regras

É possível integrar uma API sem criar um modelo de dados de formulário clicando no botão Criar integração de API no Editor de regras.

Um serviço de API chamado getcountryname está configurado na Configuração de Integração de API no Editor de Regras:

No Formulário de Solicitação de Visto, os três campos suspensos, País de Cidadania, País de Emissão de Passaporte e País de Destino, estão vinculados à ação Invocar Serviço.

Quando o formulário é carregado, o Invoke Service busca a lista de países da API. A resposta é mapeada para preencher automaticamente as opções suspensas.

Por exemplo, quando o usuário abre País de cidadania, a lista de países é exibida dinamicamente na resposta da API.

Da mesma forma, o País de Emissão de Passaporte e o País de Destino usam a mesma chamada de API, garantindo dados consistentes e atualizados em todos os três campos.

Editar uma integração de API existente

Depois de criar uma integração de API, você pode atualizá-la no Editor de regras sem criar uma nova integração. Quando uma instrução Invocar Serviço faz referência a uma integração de API, uma opção Editar está disponível para essa integração.

Para editar uma integração de API existente:

Criptografia e descriptografia

Quando a opção Criptografia necessária for selecionada para uma integração de API, cole a chave pública no campo Chave pública da janela de configuração da integração de API. O Editor de Regras invoca criptografar antes de cada solicitação de saída e descriptografar após uma resposta bem-sucedida. Se você não adicionar uma lógica personalizada em function.js, ambas as funções retornarão a carga inalterada.

Para criptografar e descriptografar dados de solicitação e resposta, adicione as funções criptografar e descriptografar a function.js:

O código de exemplo a seguir demonstra como adicionar a função encrypt em 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
    };
}

criptografar (gancho de carga pré-solicitação)

A função criptografar recebe um objeto de carga com corpo, cabeçalhos e cryptoMetadata e opções opcionais. Retorna uma versão modificada da mesma forma. O campo options carrega as configurações da API Fetch (por exemplo, credentials: 'include') por meio do pipeline de solicitação. Os valores em options são aplicados à chamada fetch() subjacente. O campo cryptoMetadata armazena dados para uso durante a descriptografia. O que quer que você defina em cryptoMetadata durante a criptografia é preservado em originalRequest.cryptoMetadata e disponibilizado para a função descriptografar mais tarde. Apesar do nome, criptografar é um transformador geral de pré-solicitação. Você pode usá-lo para modificar cabeçalhos ou o corpo da solicitação, não apenas para criptografia criptográfica. A implementação padrão retorna a carga inalterada.
​>>

O código de exemplo a seguir demonstra uma função decrypt:

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

descriptografar (gancho de resposta pós-solicitação)

A função descriptografar é executada após uma resposta bem-sucedida. Ele recebe o corpo da resposta e originalRequest. O objeto originalRequest inclui cryptoMetadata da sua função encrypt, juntamente com url, method e outros metadados de solicitação. Ele deve retornar o corpo descriptografado de forma síncrona ou assíncrona. A implementação padrão retorna os dados inalterados. A função descriptografar é executada somente em respostas bem-sucedidas. As respostas de erro não invocam descriptografar.

Implementação do mecanismo de repetição para falhas de API

Quando uma solicitação de API falha, geralmente é útil repetir a solicitação antes de relatar um erro ao usuário. Você pode implementar um mecanismo de pesquisa e tentativa gravando o código personalizado no arquivo function.js.

O exemplo a seguir demonstra como lidar com falhas de API com até duas tentativas de repetição e retrocesso exponencial entre tentativas:

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

No código acima, a função retryHandler gerencia solicitações de API com tentativas automáticas em caso de falha. Ele executa uma função de solicitação (requestFn) e tenta a solicitação até duas vezes, adicionando metadados para cada tentativa.

Perguntas frequentes