En esta página: Aprenda a utilizar el asistente externalDataLookup para recuperar dinámicamente datos de un extremo externo y personalizar el contenido de los canales entrantes en Adobe Journey Optimizer.
El asistente de externalDataLookup en el editor de personalización de Journey Optimizer se puede usar para recuperar dinámicamente datos de un extremo externo para usarlos en la generación de contenido para canales entrantes como la experiencia basada en código y los canales de mensajes web y en la aplicación.
Para usar el asistente, primero debe definir una acción en el menú Administración > Configuraciones. Una acción es donde se configuran los detalles de un extremo externo, como una dirección URL, el método GET frente a POST, parámetros de encabezado, parámetros de consulta, esquema JSON del cuerpo de POST y esquema JSON de respuesta.
Una vez definida la acción, se puede utilizar tanto:
- En recorrido, en una actividad de acción personalizada para recuperar contenido,
- En recorridos y campañas entrantes, en un asistente externo de DataLookup para recuperar datos en una acción entrante.
Mecanismos de protección y limitaciones
Consulte también Acciones personalizadas en Journey Optimizer canales entrantes, campañas y Recorridos #GuardrailsandGuidelines.
- Número máximo de búsquedas: una solicitud de mensaje entrante admite un máximo de 10 búsquedas de cualquier tipo, incluidas las búsquedas de datos externos. Si se supera este límite, se produce un error en toda la solicitud. Más información
- Tiempo de espera predeterminado: de manera predeterminada, Journey Optimizer utiliza un tiempo de espera de 300 ms al llamar a un extremo externo. Póngase en contacto con su representante de Adobe para aumentar este tiempo de espera para un punto final.
- Exploración del esquema de respuesta y validación de expresiones: en el editor de personalización, no se puede examinar el esquema de la respuesta del extremo al insertar expresiones. Journey Optimizer no valida las referencias a atributos JSON de la respuesta utilizada en las expresiones.
- Tipos de datos admitidos para los parámetros: los tipos de datos admitidos para los parámetros de variable de carga útil que se sustituirán mediante el asistente externalDataLookup son
String,Integer,Decimal,Boolean,listString,listInt,listInteger,listDecimal. - Actualización automática para acciones actualizadas: los cambios en una configuración de acción no se reflejan en las llamadas externalDataLookup correspondientes de campañas y recorridos activos. Para que se refleje un cambio, debe copiar o modificar cualquier campaña o recorrido activo que utilice la acción en un asistente de DataLookup externo.
- Sustitución de variables: por ahora, el uso de variables no es compatible con los parámetros de ayuda externalDataLookup.
- Ruta dinámica: por ahora, no se admite la ruta dinámica de URL.
- Procesamiento de varias pasadas: se admite el procesamiento de varias pasadas.
- Autenticación: por ahora, el asistente externalDataLookup no admite las opciones de autenticación de la configuración de acción. Mientras tanto, para la autenticación basada en claves de API u otras claves de autorización de texto sin formato, puede especificarlas como campos de encabezado en la configuración de acción.
Configurar una acción y utilizar el asistente
Para definir una acción y utilizar el asistente para la personalización, siga estos pasos:
-
Cree una acción para configurar el extremo de la búsqueda. Esto solo debe hacerse una vez para cada punto de conexión y debe hacerlo un usuario técnico. Aprenda a configurar una acción personalizada
Observe el ID de acción y cópielo.
-
Cree una campaña entrante o una acción de recorrido. Para este ejemplo, se muestra cómo utilizar el asistente externalDataLookup en una acción JSON de experiencia basada en código, pero se puede utilizar en un campo de personalización en cualquier canal entrante.
-
Edite el contenido de la acción, vaya a Funciones de ayuda en el editor de personalización y vaya a Funciones de ayuda > ayudantes.
-
Haga clic en el botón
+para insertar el asistente externalDataLookup. La expresión de ayuda se inserta en el editor, con valores de marcador de posición paraactionIdyresult.
Reemplace los valores de marcador de posición de la siguiente manera:
actionId: pegue el ID de acción copiado anteriormente.result: establezca el nombre que desee. Utilizará esta variable de resultado para acceder al contenido recuperado.
-
Agregue cualquier valor de parámetro de variable que se vaya a pasar como parte de la llamada al extremo. Por ejemplo, así es como se puede pasar un parámetro de idioma y un parámetro de elementos máximos.
-
Utilice la variable de resultado para acceder a los datos recuperados e insertarlos en el contenido para la acción entrante. Por ejemplo, así es como podría devolver una matriz JSON de elementos recuperados del extremo.
Funcionamiento
Ejecución en tiempo de ejecución
Cuando una acción entrante incluye un asistente externalDataLookup, se llama dinámicamente al extremo en el momento en que AEP Edge Network recibe y procesa la solicitud de personalización Journey Optimizer.
Esto significa que el extremo externo debe poder gestionar al menos la misma carga y rendimiento simultáneos que el cliente envía para la superficie determinada a AEP Edge Network.
Sintaxis
{{externalDataLookup actionId="d130c8e2-9a2d-45d5-bcb6-bc39865b4a56" result="result" optional-parameters...}}
Pasar parámetros
Cuando se llama al extremo externo, todos los valores de encabezado constante, parámetros de consulta y valor de carga útil de solicitud definidos en la acción se envían con los valores proporcionados en la configuración de acción.
Para cualquier valor de encabezado de variable, parámetro de consulta/ruta o valor de carga útil de solicitud, puede pasar valores dinámicamente mediante parámetros al asistente externalDataLookup.
Nombres de parámetros:
- Parámetros de encabezado:
header.<parameter-name> - Parámetros de consulta:
query.<parameter-name> - Parámetros de carga útil:
payload.<parameter-name> - Parámetros de ruta:
dynamic_path.<parameter-name>
Por ejemplo:
{{externalDataLookup actionId="..." result="result" header.myHeaderParameter="value1" query.myQueryParameter="value2" payload.myPayloadParameter="value3"}}`
Los valores de parámetro pueden ser valores fijos o pueden personalizarse haciendo referencia a campos de perfil u otros atributos contextuales, por ejemplo:
{{externalDataLookup actionId="..." result="result" query.myQueryParameter=profile.myProfileValue}}
Los parámetros de carga útil se pueden proporcionar utilizando la notación de puntos para hacer referencia a atributos JSON anidados, por ejemplo:
{{externalDataLookup actionId="..." result="result" payload.context.channel="web"}}
Acceso al resultado
Para acceder a los datos recuperados de una llamada de búsqueda de extremo externa, puede hacer referencia a los campos definidos en la carga útil de respuesta en la definición de acción mediante expresiones de personalización y funciones de ayuda.
Por ejemplo, si la carga útil de respuesta en la acción tiene este aspecto:
{
"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",
...
}
]
}
Por ejemplo, puede recuperar y acceder a la descripción del primer vídeo en una acción de Experience HTML basada en código de esta manera:
{{externalDataLookup actionId="d130c8e2-9a2d-45d5-bcb6-bc39865b4a56" result="result"}}
First video description: <b>result.videos[0].description</b>
Por ejemplo, puede recuperar y recorrer los elementos para devolver una matriz de elementos en una acción JSON de experiencia basada en código como la siguiente:
{{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}}
]
Resolución de problemas
Tiempos de espera y gestión de errores
Journey Optimizer usa un tiempo de espera estricto al llamar al extremo externo para mantener características de rendimiento de alto rendimiento y baja latencia para Adobe Experience Platform Edge Network.
Si se agota el tiempo de espera del extremo o hay algún otro tipo de error que llegue al extremo, la variable de resultado estará vacía. Cualquier referencia a atributos dentro de la variable de resultado en este caso también estará vacía. Si simplemente muestra el atributo en el contenido, se mostrará en blanco. Si intenta recorrer en bucle un atributo de matriz en el resultado, no devolverá ningún elemento.
Si desea gestionar los tiempos de espera o los errores de forma más correcta mostrando el contenido de reserva, puede comprobar si el resultado de la búsqueda está vacío y mostrar el contenido de reserva en ese caso.
Por ejemplo, puede mostrar un valor de reserva para un único atributo como este:
First video description: {%=result.videos[0].description ?: "none found" %}
o puede procesar condicionalmente un bloque entero de contenido como este:
{{externalDataLookup actionId="d130c8e2-9a2d-45d5-bcb6-bc39865b4a56" result="result"}}
{%#if result%}
... do something with result ...
{%else%}
... return fallback content ...
{%/if%}
Depuración
Para ayudar con la depuración, se incluyen detalles de tiempo de espera y error para búsquedas de datos externos en la vista de Edge Delivery en Adobe Experience Platform Assurance. Si no ve los resultados esperados para un asistente externalDataLookup en una acción entrante, puede iniciar una sesión de Assurance, iniciar una llamada de Journey Optimizer desde una implementación web o móvil y utilizar la vista de Edge Delivery para buscar detalles de tiempo de espera o error.
Por ejemplo:
En la sección Edge Delivery del seguimiento de seguridad como parte de los detalles de ejecución, se ha agregado un nuevo bloque customActions con detalles de solicitud y respuesta similares al de abajo. La sección de errores debe ayudar con la depuración si hubo algún problema al ejecutar la acción personalizada
Preguntas frecuentes faq-external-data
A continuación, encontrará las preguntas más frecuentes sobre el asistente de búsqueda de datos externos.
¿Necesita más información? Use las opciones de comentarios situados en la parte inferior de esta página para plantear su pregunta o conecte con la comunidad de Adobe Journey Optimizer.
Utilice el menú Atributos contextuales > Flujo de datos > Evento para examinar el esquema de Experience Event que está utilizando e insertar el atributo relevante como valor de parámetro como se muestra a continuación:
| 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.