Nesta página: Saiba como usar o auxiliar externalDataLookup para buscar dados de um ponto de extremidade externo dinamicamente e personalizar o conteúdo para canais de entrada no Adobe Journey Optimizer.
O auxiliar do externalDataLookup no Editor de personalização do Journey Optimizer pode ser usado para buscar dados dinamicamente de um terminal externo para uso na geração de conteúdo para canais de entrada, como os canais de Experiência baseada em Código, Web e Mensagens no Aplicativo.
Para usar o auxiliar, primeiro defina uma Ação no menu Administração > Configurações. Uma ação é onde você configura detalhes sobre um endpoint externo, como URL, método GET vs. POST, parâmetros de cabeçalho, parâmetros de consulta, esquema JSON de corpo POST e esquema JSON de resposta.
Depois que a Ação é definida, ela pode ser usada:
- No jornada, em uma atividade de Ação personalizada para buscar conteúdo,
- No jornada e em campanhas de entrada, em um auxiliar externalDataLookup para buscar dados em uma ação de entrada.
Medidas de proteção e limitações
Consulte Ações personalizadas em Journey Optimizer Campanhas de canais de entrada e Jornada#GuardrailsandGuidelines também.
- Número máximo de pesquisas - Uma solicitação de mensagem de entrada oferece suporte a no máximo 10 pesquisas de qualquer tipo, incluindo pesquisas de dados externos. Exceder esse limite causa falha em toda a solicitação. Saiba mais
- Tempo limite padrão - Por padrão, Journey Optimizer usa um tempo limite de 300 ms ao chamar um ponto de extremidade externo. Entre em contato com seu representante da Adobe para aumentar esse tempo limite de um endpoint.
- Navegação de esquema de resposta e validação de expressão - No editor de personalização, não é possível navegar pelo esquema da resposta do ponto de extremidade ao inserir expressões. Journey Optimizer não valida referências a atributos JSON da resposta usada em expressões.
- Tipos de dados com suporte para parâmetros - Os tipos de dados com suporte para parâmetros variáveis de carga a serem substituídos por meio do auxiliar externalDataLookup são
String,Integer,Decimal,Boolean,listString,listInt,listInteger,listDecimal. - Atualização automática para ações atualizadas - As alterações em uma configuração Action não são refletidas nas chamadas externalDataLookup correspondentes em campanhas e jornadas ativas. Para que uma alteração seja refletida, é necessário copiar ou modificar campanhas ou jornadas ativas que estejam usando a Ação em um auxiliar externalDataLookup.
- Substituição de variável - Por enquanto, não há suporte para o uso de variáveis nos parâmetros auxiliares externalDataLookup.
- Caminho dinâmico - Por enquanto, não há suporte para o caminho de URL dinâmico.
- Renderização de várias passagens - Há suporte para a renderização de várias passagens.
- Autenticação - Por enquanto, o auxiliar externalDataLookup não oferece suporte às opções de autenticação na configuração Ação. Enquanto isso, para a autenticação baseada em chave de API ou outras chaves de autorização de texto sem formatação, você pode especificá-las como campos de cabeçalho na configuração Ação.
Configurar uma ação e usar o auxiliar
Para definir uma ação e usar o helper para personalização, siga estas etapas:
-
Crie uma Ação para configurar o endpoint para a pesquisa. Isso só precisa ser feito uma vez para cada endpoint e deve ser feito por um usuário técnico. Saiba como configurar uma ação personalizada
Anote a ID de ação e copie-a.
-
Crie uma campanha de entrada ou ação de jornada. Neste exemplo, estamos mostrando como usar o auxiliar externalDataLookup em uma ação JSON da experiência baseada em código, mas ele pode ser usado em um campo de personalização em qualquer canal de entrada.
-
Edite o conteúdo da ação, vá para Funções de ajuda no editor de personalização e navegue até Funções de ajuda > Ajuda.
-
Clique no botão
+para inserir o auxiliar externalDataLookup. A expressão auxiliar é inserida no editor, com valores de espaço reservado paraactionIderesult.
Substitua os valores de espaço reservado da seguinte maneira:
actionId: Colar a ID de Ação copiada anteriormente.result: Defina o nome de sua escolha. Você usará essa variável de resultado para acessar o conteúdo buscado.
-
Adicione quaisquer valores de parâmetro de variável que serão transmitidos como parte da chamada de endpoint. Por exemplo, veja como você pode passar um parâmetro de idioma e um parâmetro de número máximo de itens.
-
Use a variável result para acessar os dados buscados e inseri-los no conteúdo da ação de entrada. Por exemplo, veja como você pode retornar uma matriz JSON de itens buscados no endpoint.
Como funciona
Execução em tempo de execução
Quando uma ação de entrada inclui um auxiliar externalDataLookup, o ponto de extremidade é chamado dinamicamente no momento em que a solicitação de personalização Journey Optimizer é recebida e processada pelo AEP Edge Network.
Isso significa que o endpoint externo precisa ser capaz de lidar com pelo menos a mesma carga e taxa de transferência simultâneas que o cliente está enviando para a superfície específica para o AEP Edge Network.
Sintaxe
{{externalDataLookup actionId="d130c8e2-9a2d-45d5-bcb6-bc39865b4a56" result="result" optional-parameters...}}
Parâmetros de envio
Quando o endpoint externo é chamado, todos os valores de cabeçalho constantes, parâmetros de consulta e valor de carga de solicitação definidos na Ação serão enviados com os valores fornecidos na configuração da Ação.
Para quaisquer valores de cabeçalho de variável, parâmetros de consulta/caminho ou valores de carga de solicitação, você pode transmitir valores dinamicamente usando parâmetros para o auxiliar externalDataLookup.
Nomes dos parâmetros:
- Parâmetros de cabeçalho:
header.<parameter-name> - Parâmetros de consulta:
query.<parameter-name> - Parâmetros de carga:
payload.<parameter-name> - Parâmetros de Caminho:
dynamic_path.<parameter-name>
Por exemplo:
{{externalDataLookup actionId="..." result="result" header.myHeaderParameter="value1" query.myQueryParameter="value2" payload.myPayloadParameter="value3"}}`
Os valores de parâmetro podem ser valores fixos ou personalizados referenciando campos de perfil ou outros atributos contextuais, por exemplo:
{{externalDataLookup actionId="..." result="result" query.myQueryParameter=profile.myProfileValue}}
Parâmetros de carga podem ser fornecidos usando a notação de pontos para fazer referência a atributos JSON aninhados, por exemplo:
{{externalDataLookup actionId="..." result="result" payload.context.channel="web"}}
Acessar o resultado
Para acessar os dados buscados de uma chamada de pesquisa de ponto de extremidade externo, você pode referenciar campos definidos na carga da resposta na definição Ação usando expressões de personalização e funções auxiliares.
Por exemplo, se a carga de resposta na Ação tiver esta aparência:
{
"videos": [
{
"id": "integer",
"title": "string",
"description": "string",
"thumbnail_url": "string",
"video_page_url": "string",
"url": "string",
"video_type": "string",
"start_timestamp": "dateOnly",
"created_on": "dateOnly",
...
}
]
}
Em seguida, por exemplo, você pode buscar e acessar a descrição do primeiro vídeo em uma ação do Experience HTML baseada em código, como esta:
{{externalDataLookup actionId="d130c8e2-9a2d-45d5-bcb6-bc39865b4a56" result="result"}}
First video description: <b>result.videos[0].description</b>
Por exemplo, você pode buscar e executar um loop pelos itens para retornar uma matriz de itens em uma ação JSON de experiência baseada em código, desta forma:
{{externalDataLookup actionId="d130c8e2-9a2d-45d5-bcb6-bc39865b4a56" result="result"}}
[
{{#each result.videos as |item|}}
{
"title": "{{item.title}}",
"url": "{{item.video_page_url}}",
"thumbnail_url": "{{item.thumbnail_url}}",
"start_timestamp": "{{item.start_timestamp}}"
},
{{/each}}
]
Solução de problemas
Tempo limite e tratamento de erros
Journey Optimizer usa um tempo limite estrito ao chamar o ponto de extremidade externo para manter as características de desempenho de alta taxa de transferência e baixa latência para o Adobe Experience Platform Edge Network.
Se o ponto de extremidade atingir o tempo limite ou se houver qualquer outro tipo de erro que chegue ao ponto de extremidade, a variável resultante estará vazia. Nesse caso, todas as referências a atributos na variável result também estarão vazias. Se você estiver apenas exibindo o atributo no conteúdo, ele será exibido em branco. Se você estiver tentando percorrer um atributo de matriz no resultado, ele não retornará itens.
Se você quiser lidar com tempos limite ou erros de maneira mais adequada mostrando o conteúdo de fallback, poderá verificar se o resultado da pesquisa está vazio e exibir o conteúdo de fallback nesse caso.
Por exemplo, você pode mostrar um valor de fallback para um único atributo como este:
First video description: {%=result.videos[0].description ?: "none found" %}
ou você pode renderizar condicionalmente um bloco inteiro de conteúdo como este:
{{externalDataLookup actionId="d130c8e2-9a2d-45d5-bcb6-bc39865b4a56" result="result"}}
{%#if result%}
... do something with result ...
{%else%}
... return fallback content ...
{%/if%}
Depuração
Para ajudar na depuração, os detalhes de tempo limite e erro para pesquisas de dados externas são incluídos na exibição do Edge Delivery no Adobe Experience Platform Assurance. Se você não estiver vendo os resultados esperados para um auxiliar externalDataLookup em uma ação de entrada, poderá iniciar uma sessão do Assurance, iniciar uma chamada do Journey Optimizer de uma implementação da Web ou móvel e usar o modo de exibição do Edge Delivery para verificar detalhes de tempo limite ou erro.
Por exemplo:
Na Seção Edge Delivery do rastreamento de garantia como parte dos detalhes de execução, um novo bloco customActions foi adicionado com detalhes de solicitação e resposta semelhantes ao abaixo. A seção de erros deve ajudar na depuração se houver problemas ao executar uma ação personalizada
Perguntas frequentes faq-external-data
Você encontrará abaixo as Perguntas frequentes sobre o Auxiliar de pesquisa de dados externos.
Precisa de mais detalhes? Use as opções de feedback na parte inferior desta página para fazer a pergunta ou conecte-se à comunidade Adobe Journey Optimizer.
Use o menu Atributos contextuais > Sequência de dados > Evento para navegar pelo esquema do Evento de experiência que você está usando e insira o atributo relevante como um valor de parâmetro como este:
| code language-none |
|---|
|
This section contains structured knowledge intended to support interpretation, retrieval, and question answering related to this topic.
For complete understanding, this information should be combined with the documentation on this page. Neither source is intended to stand alone; the page describes the feature, while this section provides additional context that helps disambiguate terminology, intent, applicability, and constraints.
- TL;DR: This page explains how to configure an Action for an external endpoint and use the
externalDataLookuphelper in the personalization editor to dynamically fetch that data at runtime for personalizing inbound channel content.
Intents:
- Configure an Action defining an external endpoint (URL, HTTP method, parameters, request/response schemas)
- Insert the
externalDataLookuphelper in a personalization expression for an inbound action - Pass variable header, query, payload, or path parameters to the external endpoint at call time
- Access fetched data via the result alias using personalization expressions and helper functions
- Handle timeouts and errors gracefully with fallback content patterns
- Debug external lookup issues using Adobe Experience Platform Assurance
Glossary:
- externalDataLookup: A helper function in the personalization editor that dynamically fetches data from a configured external endpoint at request time, for use in inbound channel content personalization. (product-specific)
- Action: A configuration object in Journey Optimizer (Administration > Configurations) that defines an external endpoint — URL, HTTP method, header/query parameters, POST body schema, and response schema. Required before using
externalDataLookup. (product-specific) - result variable: An arbitrary alias assigned in the
externalDataLookupcall; used to reference all fields from the fetched response in subsequent personalization expressions. - Inbound channels: Channels where content is delivered on demand when a user opens a surface — Code-based Experience, Web, In-App Message. (product-specific)
- AEP Edge Network: The infrastructure that receives personalization requests and triggers the external data lookup call at runtime.
Guardrails:
- Feature is in Limited Availability — only available for a set of organizations.
- Default timeout for external endpoint calls: 300ms (default; contact your Adobe representative to increase this timeout for a specific endpoint).
- Response schema browsing is not supported in the personalization editor; Journey Optimizer does not validate references to JSON attributes from the response used in expressions.
- Supported data types for payload variable parameters:
String,Integer,Decimal,Boolean,listString,listInt,listInteger,listDecimal. - Variable substitution within
externalDataLookuphelper parameters is not currently supported. - Dynamic URL paths are not currently supported.
- Authentication options in the Action configuration are not currently supported by
externalDataLookup; use header fields for API key-based or plaintext authorization as a workaround. - Changes to an Action configuration are not reflected in live campaigns or journeys using that Action; copy or modify any live campaigns/journeys to apply the changes.
- Multi-pass rendering is supported.
- Journey Optimizer does not currently cache external endpoint responses.
- The external endpoint must be able to handle at least as much concurrent load and throughput as the inbound traffic sent to the AEP Edge Network for the given surface.
Terminology:
- Canonical name: externalDataLookup — variants: external data lookup, external data lookup helper, External Data Lookup Helper
- Synonyms: “externalDataLookup” = “external data lookup helper”
- Do not confuse:
actionId(ID of the configured Action, identifying the external endpoint) ≠result(alias for the fetched response data) ≠ parameter names (variable values passed to the endpoint at call time) - Do not confuse: using
externalDataLookupin an inbound personalization action (fetches data dynamically at Edge Network request time) ≠ using a Custom Action in a journey activity (fetches content within a journey flow)
FAQ:
- Q: What happens if the external endpoint times out or returns an error? — The result variable will be empty. Attribute references within the result will display as blank, and array iterations will return no items. Use fallback content patterns — such as
?: "none found"for single attributes or{%#if result%}…{%else%}…{%/if%}for entire content blocks — to handle these cases gracefully. - Q: How do I pass a contextual attribute from the request as a parameter to an external data lookup? — Use the Contextual Attributes > Datastream > Event menu in the personalization editor to browse the Experience Event schema and insert the relevant attribute as a parameter value, for example:
query.myQueryParameter=context.datastream.event.<schemaId>.my.xdm.attribute. - Q: Does Journey Optimizer cache external endpoint responses? — Not currently. Caching will be supported in the future.
- Q: How do I debug issues with externalDataLookup? — Use Adobe Experience Platform Assurance. Start an Assurance session, initiate a Journey Optimizer call from your web or mobile implementation, and use the Edge Delivery view to inspect the customActions block for timeout or error details.
- Q: Can I use authentication in the Action configuration with externalDataLookup? — Authentication options in the Action configuration are not currently supported. For API key-based or other plaintext authorization, specify the credentials as header fields in the Action configuration.