API externa external-api
Descrição description
A atividade External API traz dados para o workflow de um sistema externo por meio de uma chamada à API HTTP.
Os pontos de extremidade do sistema externo podem ser pontos de extremidade de API públicos, sistemas de gerenciamento de clientes ou instâncias de aplicativos sem servidor (por exemplo, Adobe I/O Runtime), para mencionar algumas categorias.
As principais características dessa atividade são:
- Capacidade de transmitir dados em um formato JSON para um ponto de extremidade de API REST de terceiros
- Capacidade de receber uma resposta JSON de volta, mapeá-la para tabelas de saída e transmiti-la downstream para outras atividades do workflow.
- Gerenciamento de falhas com uma transição específica de saída
Avisos de compatibilidade com versões anteriores from-beta-to-ga
Com a versão 20.4 do Campaign Standard, o limite de tamanho dos dados de resposta http e as medidas de proteção do tempo de espera da resposta foram reduzidos para se alinharem às práticas recomendadas - consulte Limitações e medidas de proteção. Essas modificações nas medidas de proteção não entrarão em vigor nas atividades de API externas existentes; portanto, é recomendado substituir as atividades de API externas existentes por novas versões em todos os workflows.
Ao substituir as atividades de API externas, adicione a nova atividade ao workflow, copie manualmente os detalhes de configuração e exclua a atividade antiga.
Limitações e medidas de proteção guardrails
Aplicam-se a esta atividade as seguintes medidas de proteção:
- Limite de tamanho de dados de resposta http de 5 MB (observação: é uma alteração do limite de 50 MB na versão anterior)
- O tempo de espera da solicitação é de 1 minuto (observação: é uma alteração do tempo limite de 10 minutos na versão anterior)
- Não são permitidos redirecionamentos HTTP
- São rejeitados Urls que não sejam HTTPS
- São permitidos cabeçalho de solicitação “Accept: application/json” e cabeçalho de resposta “Content-Type: application/json”
Foram colocadas em prática medidas de proteção específicas:
- Profundidade máx. JSON: limite a profundidade máxima de um JSON aninhado e personalizado que pode ser processado para 10 níveis.
- Extensão máx. da chave JSON: limite o comprimento máximo da chave interna gerada para 255. Essa chave está associada à ID da coluna.
- Chaves máximas de duplicação JSON permitidas: limite o número total máximo de nomes de propriedades JSON do duplicado usados como ID da coluna para 150.
Configuração configuration
Arraste e solte uma atividade External API no seu workflow e abra a atividade para iniciar a configuração.
Mapeamento de entrada
O mapeamento de entrada é uma tabela temporária gerada por uma atividade de entrada anterior que será exibida e enviada como JSON na interface.
Com base nessa tabela temporária, o usuário pode fazer modificações nos dados de entrada.
A lista suspensa Recurso de entrada permite selecionar a atividade de query que criará a tabela temporária.
A caixa de seleção Adicionar parâmetro de contagem adicionará um valor de contagem para cada linha proveniente da tabela temporária. Observe que essa caixa de seleção só estará disponível se a atividade de entrada estiver gerando uma tabela temporária.
A seção Colunas de entrada permite que o usuário adicione quaisquer campos a partir da tabela de transição de entrada. As colunas selecionadas serão as chaves no objeto de dados. O objeto de dados no JSON será uma lista de matriz contendo dados para colunas selecionadas de cada linha da tabela de transição de entrada.
A caixa de texto personalizar parâmetro permite adicionar um JSON válido com dados adicionais necessários para a API externa. Esses dados adicionais serão adicionados ao objeto params no JSON gerado.
Mapeamento de saída
Essa guia permite que você defina a estrutura JSON de amostra retornada pela chamada à API.
O analisador de JSON foi projetado para hospedar tipos padrão de estrutura JSON, com algumas exceções. Um exemplo de padrão é:{“data”:[{“key”:“value”}, {“key”:“value”},...]}
A definição do JSON de amostra deve ter as seguintes características:
- Os elementos da matriz devem conter propriedades de primeiro nível (níveis mais profundos não são compatíveis).
Os nomes de propriedades acabarão se tornando nomes de colunas para o schema de saída da tabela temporária de saída. - Os elementos JSON capturados devem estar em 10 ou menos níveis de aninhamento na resposta JSON.
- A definição do nome da coluna é baseada no primeiro elemento da matriz "data".
A definição de colunas (adicionar/remover) e o valor de tipo da propriedade podem ser editados na guia Definição de coluna.
Comportamento da Caixa de seleção Nivelar:
A caixa de seleção Nivelar (desmarcada por padrão) é fornecida para indicar se o JSON deve ser nivelado em um mapa de chave/valor.
-
Quando a caixa de seleção estiver desabilitada (desmarcada), a amostra JSON será analisada para procurar um objeto de matriz. O usuário precisará fornecer uma versão reduzida do formato JSON de amostra de resposta da API para que o Adobe Campaign possa determinar exatamente qual matriz o usuário está interessado em usar. No momento da criação do workflow, o caminho para o objeto de matriz aninhado será determinado e registrado, para que possa ser usado no tempo de execução para acessar esse objeto de matriz pelo corpo de resposta JSON recebido da chamada de API.
-
Quando a caixa de seleção estiver ativada (marcada), a amostra JSON será nivelada e todas as propriedades especificadas na amostra JSON fornecida serão usadas para criar colunas da tabela temporária de saída, e serão exibidas na guia Definições de coluna. Observe que se houver algum objeto de matriz na amostra JSON, todos os elementos desses objetos de matriz também serão nivelados.
Se a análise for validada, será exibida uma mensagem com um convite para personalizar o mapeamento de dados na guia "Definição de coluna". Caso contrário, uma mensagem de erro será exibida.
Execução
Essa guia permite que você defina o ponto de extremidade da conexão. O campo URL permite definir o Ponto de Extremidade HTTPS com o qual o Campaign Standard se comunicará.
Se necessário para o endpoint, dois tipos de método de autenticação estão disponíveis:
-
Autenticação básica: digite suas informações de nome de usuário/senha na seção Request Header(s).
-
Autenticação OAuth: ao clicar em Use connection parameters defined in an external account em uma conta externa, é possível selecionar uma conta externa na qual a autenticação OAuth é definida. Para obter mais informações, consulte a seção Contas externas.
Propriedades
Essa guia permite controlar as propriedades gerais na atividade externa da API, como o rótulo exibido na interface. A ID interna não é personalizável.
Definição de coluna
A guia Definição de coluna permite especificar com precisão a estrutura dos dados de cada coluna para importar dados que não contenham erros e fazer a correspondência deles com os tipos presentes no banco de dados do Adobe Campaign para operações futuras.
Por exemplo, você pode alterar o rótulo de uma coluna, selecionar o tipo (string, número inteiro, data etc.) ou até mesmo especificar o processamento de erros.
Para obter mais informações, consulte a seção Carregar arquivo.
Transição
Essa guia permite ativar a transição de saída e seu rótulo. Essa transição específica é útil em caso de tempo de espera ou se a carga exceder o limite de tamanho de dados.
Opções de execução
Esta guia está disponível na maioria das atividades de workflow. Para obter mais informações, consulte a seção Propriedades de atividade.
Testes
Para testar a funcionalidade da API externa com um endpoint de teste simples, você pode usar o Postman Echo: https://docs.postman-echo.com.
Solução de problemas
Existem dois tipos de mensagens de log adicionados a esta nova atividade de workflow: informações e erros. Elas podem ser úteis na solução de possíveis problemas.
Informações
Essas mensagens de log são usadas para registrar informações sobre pontos de verificação úteis durante a execução da atividade do workflow.
Erros
Essas mensagens de log são usadas para registrar informações sobre condições de erro inesperadas, que eventualmente podem causar falha na atividade do workflow.
O URL da API não pôde ser analisado (erro: "-2010").
Observação: esse erro é registrado quando o URL da API apresenta falha nas regras de validação.
O host do URL da API não deve ser “localhost” nem o endereço IP literal (Host de URL: ‘localhost’).
O host do URL da API não deve ser “localhost” nem o endereço IP literal (Host de URL: '192.168.0.5').
O host do URL da API não deve ser “localhost” nem o endereço IP literal (Host de URL: '[2001]').
Falha ao criar o corpo de solicitação JSON. Erro ao adicionar 'params'.
Falha ao criar o corpo de solicitação JSON. Erro ao adicionar 'data'.
HTTP header key is bad (header key: '%s').
Observação: este erro é registrado quando a chave do cabeçalho personalizado falha na validação de acordo com a RFC
HTTP header value is bad (header value: '%s').
Observação: este erro é registrado quando o valor do cabeçalho personalizado falha na validação de acordo com a RFC
Formato JSON malformado ou inaceitável.
Observação: esta mensagem se aplica somente à análise do corpo da resposta a partir da API externa e é registrada ao tentar validar se o corpo da resposta está em conformidade com o formato JSON determinado por essa atividade.
Quando a atividade falha devido à resposta de erro HTTP 401 - Falha na atividade (motivo: 'HTTP - 401')
Quando a atividade falha devido a uma falha na chamada interna - Falha na atividade (motivo: 'iRc - -Nn').
Quando a atividade falha devido a um cabeçalho de tipo de conteúdo inválido. - Falha na atividade (motivo: 'Content-Type - application/html’).