Show Menu
TÓPICOS×

API externa

Descrição

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.
Por motivos de segurança, o uso de JSSPs não é compatível com o Campaign Standard. Se você precisar executar um código, poderá chamar uma instância do Adobe I/O Runtime por meio da atividade API externa.
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

Transição de Beta para GA

Com a versão Campaign Standard 20.3, o recurso de API externa mudou de Beta para GA (Disponibilidade geral).
Como consequência, se você estava usando atividades de API externa beta, precisará substituí-las por atividades de API externa GA em todos os workflows.  Os Workflows que usam a versão beta da API externa pararão de funcionar a partir da versão 20.3.
Ao substituir atividades de API externas, adicione a nova atividade de API externa ao fluxo de trabalho, copie manualmente os detalhes de configuração e exclua a atividade antiga.
Não será possível copiar os valores do cabeçalho, pois eles são mascarados dentro da atividade.
Em seguida, reconfigure outras atividades no fluxo de trabalho que apontam e/ou usam dados da atividade beta External API para apontar e/ou usar dados da nova atividade External API. Exemplos de atividades: delivery de e-mail (campos de personalização), atividade do enriquecimento etc.

Limitações e calhas

Os seguintes coletores se aplicam a esta atividade:
  • Limite de tamanho de dados de resposta http de 50 MB (recomenda-se 5 MB)
  • O tempo limite da solicitação é de 10 minutos
  • Redirecionamentos HTTP não são permitidos
  • Urls que não sejam HTTPS são rejeitados
  • "Aceitar: cabeçalho de solicitação application/json" e "Content-Type: o cabeçalho de resposta application/json é permitido
A partir da versão 20.4 da Campanha, o limite de tamanho de dados da resposta http e os limites de tempo limite da resposta serão reduzidos para 5 MB e 1 minuto, respectivamente. Embora essa alteração afete apenas as novas atividades de API externas, é altamente recomendável que as implementações atuais da atividade de API externa se alinhem com esses novos painéis de controle para seguir as práticas recomendadas.
Foram postos em prática medidas específicas para o JSON:
  • Profundidade máx. JSON: limite a profundidade máxima de um JSON aninhado 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.
  • Teclas máximas de Duplicado JSON permitidas : limite o número total máximo de nomes de propriedades JSON do duplicado, que são usados como ID da coluna, para 150.
A atividade não tem suporte para a estrutura JSON como:
  • Combinação de objetos de matriz com outros elementos que não são de matriz
  • O objeto de matriz JSON é aninhado dentro de um ou mais objetos de matriz intermediários.
A atividade de API externa destina-se a obter dados de toda a campanha (conjunto mais recente de ofertas, pontuações mais recentes etc.), não para recuperar informações específicas para cada perfil, pois isso pode resultar na transferência de grandes quantidades de dados. Se o caso de uso exigir isso, a recomendação é usar a atividade Transferir arquivo .

Configuração Fi

Arraste e solte uma External API atividade no seu fluxo de trabalho e abra a atividade para start da 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 do usuário. 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 da tabela 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 de API.
O analisador JSON foi projetado para acomodar 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 suportados). 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 a serem 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.
Nivelar o comportamento da caixa de seleção:
A caixa de seleção Nivelar (padrão: desmarcada) é fornecida para indicar se o JSON deve ser nivelado em um mapa de chave/valor ou não.
  • Quando a caixa de seleção estiver desativada (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 a Adobe Campaign possa determinar exatamente em qual matriz o usuário está interessado em usar. No tempo de criação do fluxo de trabalho, 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 a partir do 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 fornecida JSON serão usadas para criar colunas da tabela temporária de saída e 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 , uma mensagem será exibida e convidará você a personalizar o mapeamento de dados na guia "Definição de coluna". Em outros casos, uma mensagem de erro é exibida.

Execução

Essa guia permite que você defina o Ponto de extremidade HTTPS que enviará dados para o ACS. Se necessário, você pode inserir informações de autenticação nos campos abaixo.

Propriedades

Essa guia permite controlar as propriedades ​gerais na atividade externa da API, como o rótulo exibido na interface do usuário. A ID interna não é personalizável.

Definição de coluna

Essa guia é exibida quando o formato de dados de resposta é concluído e validado na guia Mapeamento de saída.
The Column definition tab allows you to precisely specify the data structure of each column in order to import data that does not contain any errors and make it match the types that are already present in the Adobe Campaign database for future operations.
Por exemplo, você pode alterar o rótulo de uma coluna, selecionar o tipo (sequência, número inteiro, data etc.) ou até mesmo especificar o processamento de erros.
For more information, refer to the Load File section.

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 limite 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 fluxo de trabalho. For more information, consult the Activity properties section.

Solução de problemas

Existem dois tipos de mensagens de registro adicionados a esta nova atividade de fluxo de trabalho: informações e erros. Eles podem ajudá-lo a solucionar 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 fluxo de trabalho. Especificamente, as mensagens de log a seguir são usadas para registrar a primeira tentativa, bem como uma tentativa de nova tentativa (e o motivo da falha da primeira tentativa) para acessar a API.
Formato de mensagem Exemplo
Chamando o URL da API '%s'.
Invocando URL da API 'https://example.com/api/v1/web-coupon?count=2'.
Tentando novamente o URL da API '%s', falha na tentativa anterior ('%s').
Tentando novamente o URL da API 'https://example.com/api/v1/web-coupon?count=2', falha na tentativa anterior ('HTTP - 401').
Transferindo conteúdo de '%s' (%s / %s).
Transferência de conteúdo de 'https://example.com/api/v1/web-coupon?count=2' (1234 / 1234).

Erros

Essas mensagens de registro são usadas para registrar informações sobre condições de erro inesperadas, que podem eventualmente causar falha na atividade do fluxo de trabalho.
Código - Formato da mensagem Exemplo
WKF-560250 - O corpo da solicitação de API excedeu o limite (limite: '%d').
O corpo da solicitação de API excedeu o limite (limite: '5242880').
WKF-560239 - Resposta da API excedeu o limite (limite: '%d').
Limite de resposta da API excedido (limite: 5242880').
WKF-560245 - O URL da API não pôde ser analisado (erro: '%d').
O URL da API não pôde ser analisado (erro: "-2010").
Observação: Esse erro é registrado quando o URL da API falha nas regras de validação.
WKF-560244 - O host do URL da API não deve ser 'localhost', nem o literal de endereço IP (host do URL: '%s').
O host do URL da API não deve ser 'localhost' ou o literal de endereço IP (host do URL: 'localhost').
O host do URL da API não deve ser 'localhost' ou o literal de endereço IP (host do URL: "192.168.0.5").
O host do URL da API não deve ser 'localhost' ou o literal de endereço IP (host do URL: '[2001]').
WKF-560238 - O URL da API deve ser um URL seguro (https) (URL solicitado: '%s').
O URL da API deve ser um URL seguro (https) (URL solicitado: 'https://example.com/api/v1/web-coupon?count=2').
WKF-560249 - Falha ao criar o corpo de solicitação JSON. Erro ao adicionar '%s'.
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'.
WKF-560246 - A chave do cabeçalho HTTP está incorreta (chave do cabeçalho: '%s').
A chave do cabeçalho HTTP está incorreta (chave do cabeçalho: '%s').
Observação: Este erro é registrado quando a chave do cabeçalho personalizado falha na validação de acordo com a RFC
WKF-560248 - A chave do cabeçalho HTTP não é permitida (chave do cabeçalho: '%s').
A chave do cabeçalho HTTP não é permitida (chave do cabeçalho: 'Aceitar').
WKF-560247 - O valor do cabeçalho HTTP é incorreto (valor do cabeçalho: '%s').
O valor do cabeçalho HTTP é incorreto (valor do cabeçalho: '%s').
Observação: Este erro é registrado quando o valor do cabeçalho personalizado falha na validação de acordo com a RFC
WKF-560240 - A carga JSON tem a propriedade '%s' incorreta.
A carga JSON tem uma propriedade ruim "blá".
WKF-560241 - Formato JSON malformado ou inaceitável.
Formato JSON malformado ou inaceitável.
Observação: Esta mensagem se aplica somente à análise do corpo da resposta da API externa e é registrada ao tentar validar se o corpo da resposta está em conformidade com o formato JSON mandatado por essa atividade.
WKF-560246 - Falha na Atividade (motivo: '%s').
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 - a Atividade falhou (motivo: 'iRc - -Nn').
Quando a atividade falha devido a um cabeçalho Content-Type inválido. - Falha na Atividade (motivo: 'Content-Type - application/html').