In questa pagina: Scopri come utilizzare l’helper externalDataLookup per recuperare dinamicamente i dati da un endpoint esterno e personalizzare il contenuto per i canali in entrata in Adobe Journey Optimizer.
L’helper externalDataLookup nell’editor di personalizzazione Journey Optimizer può essere utilizzato per recuperare dinamicamente i dati da un endpoint esterno per la generazione di contenuti per i canali in entrata come Esperienza basata su codice, Canali Web e Messaggi in-app.
Per utilizzare l’helper, devi prima definire un’azione nel menu Amministrazione > Configurazioni. Un’azione è il luogo in cui puoi configurare i dettagli di un endpoint esterno, ad esempio URL, metodo GET vs. POST, parametri di intestazione, parametri di query, schema JSON del corpo POST e schema JSON di risposta.
Una volta definita l’azione, questa può essere utilizzata in entrambi i modi:
- Nei percorsi, in un’attività Azione personalizzata per recuperare il contenuto,
- Nei percorsi e nelle campagne in entrata, in un helper externalDataLookup per recuperare dati in un’azione in entrata.
Guardrail e limitazioni
Fare riferimento alle azioni personalizzate anche in Journey Optimizer campagne e Percorsi di canali in entrata#GuardrailsandGuidelines
- Numero massimo di ricerche. Una richiesta di messaggio in entrata supporta un massimo di 10 ricerche di qualsiasi tipo, incluse quelle di dati esterni. Il superamento di questo limite non dà esito positivo all’intera richiesta. Ulteriori informazioni
- Timeout predefinito - Per impostazione predefinita, Journey Optimizer utilizza un timeout di 300 ms quando chiama un endpoint esterno. Per aumentare il timeout per un endpoint, contatta il rappresentante Adobe.
- Esplorazione schema di risposta e convalida espressione - Nell’editor di personalizzazione non è possibile sfogliare lo schema della risposta dell’endpoint durante l’inserimento delle espressioni. Journey Optimizer non convalida i riferimenti agli attributi JSON dalla risposta utilizzata nelle espressioni.
- Tipi di dati supportati per i parametri - I tipi di dati supportati per i parametri della variabile di payload da sostituire tramite l’helper externalDataLookup sono
String,Integer,Decimal,Boolean,listString,listInt,listInteger,listDecimal. - Aggiornamento automatico per azioni aggiornate - Le modifiche alla configurazione di un’azione non vengono applicate alle corrispondenti chiamate externalDataLookup nelle campagne e nei percorsi live. Affinché una modifica venga rispecchiata, è necessario copiare o modificare tutte le campagne o i percorsi live che utilizzano l’azione in un helper externalDataLookup.
- Sostituzione variabile - Per il momento, l’utilizzo delle variabili non è supportato nei parametri helper externalDataLookup.
- Percorso dinamico - Per il momento, il percorso URL dinamico non è supportato.
- Rendering a più passaggi - È supportato il rendering a più passaggi.
- Autenticazione - Per il momento, le opzioni di autenticazione nella configurazione Action non sono supportate dall’helper externalDataLookup. Nel frattempo, per l’autenticazione basata su chiave API o altre chiavi di autorizzazione in testo normale, puoi specificarle come campi di intestazione nella configurazione Azione.
Configurare un’azione e utilizzare l’helper
Per definire un’azione e utilizzare l’helper per la personalizzazione, segui questi passaggi:
-
Crea un’azione per configurare l’endpoint per la ricerca. Questa operazione deve essere eseguita solo una volta per ogni endpoint e deve essere eseguita da un utente tecnico. Scopri come configurare un’azione personalizzata
Prendi nota dell’ID azione e copialo.
-
Crea una campagna in entrata o un’azione di percorso. Per questo esempio, viene mostrato come utilizzare l’helper externalDataLookup in un’azione JSON di esperienza basata su codice, ma può essere utilizzato in un campo di personalizzazione in qualsiasi canale in entrata.
-
Modifica il contenuto dell’azione, vai a Funzioni helper nell’editor di personalizzazione e passa a Funzioni helper > Helper.
-
Fare clic sul pulsante
+per inserire l’helper externalDataLookup. L’espressione helper viene inserita nell’editor, con valori segnaposto peractionIderesult.
Sostituire i valori segnaposto come segue:
actionId: incolla l’ID azione copiato in precedenza.result: impostare il nome desiderato. Utilizzerai questa variabile di risultati per accedere al contenuto recuperato.
-
Aggiungi eventuali valori dei parametri della variabile da passare come parte della chiamata dell’endpoint. Ad esempio, ecco come si può trasmettere un parametro di linguaggio e un parametro di elementi max.
-
Utilizza la variabile di risultati per accedere ai dati recuperati e inserirli nel contenuto per l’azione in entrata. Ad esempio, ecco come restituire un array JSON di elementi recuperati dall’endpoint.
Come funziona
Esecuzione runtime
Quando un’azione in entrata include un helper externalDataLookup, l’endpoint viene chiamato in modo dinamico nel momento in cui la richiesta di personalizzazione Journey Optimizer viene ricevuta ed elaborata dall’Edge Network di AEP.
Ciò significa che l’endpoint esterno deve essere in grado di gestire un carico e una velocità effettiva simultanei almeno pari a quelli che il client invia per la superficie specificata all’Edge Network di AEP.
Sintassi
{{externalDataLookup actionId="d130c8e2-9a2d-45d5-bcb6-bc39865b4a56" result="result" optional-parameters...}}
Trasmissione dei parametri
Quando viene chiamato l’endpoint esterno, tutti i valori di intestazione costanti, i parametri di query e il valore di payload della richiesta definiti nell’azione vengono inviati con i valori forniti nella configurazione dell’azione.
Per qualsiasi valore di intestazione variabile, parametri di query/percorso o valori di payload della richiesta, è possibile trasmettere valori in modo dinamico utilizzando i parametri all’helper externalDataLookup.
Nomi parametri:
- Parametri intestazione:
header.<parameter-name> - Parametri query:
query.<parameter-name> - Parametri payload:
payload.<parameter-name> - Parametri percorso:
dynamic_path.<parameter-name>
Ad esempio:
{{externalDataLookup actionId="..." result="result" header.myHeaderParameter="value1" query.myQueryParameter="value2" payload.myPayloadParameter="value3"}}`
I valori dei parametri possono essere valori fissi o personalizzati facendo riferimento a campi di profilo o altri attributi contestuali, ad esempio:
{{externalDataLookup actionId="..." result="result" query.myQueryParameter=profile.myProfileValue}}
I parametri di payload possono essere forniti utilizzando la notazione del punto per fare riferimento agli attributi JSON nidificati, ad esempio:
{{externalDataLookup actionId="..." result="result" payload.context.channel="web"}}
Accesso al risultato
Per accedere ai dati recuperati da una chiamata di ricerca dell’endpoint esterno, puoi fare riferimento ai campi definiti nel payload di risposta nella definizione dell’azione utilizzando espressioni di personalizzazione e funzioni di supporto.
Ad esempio, se il payload di risposta nell’azione è simile al seguente:
{
"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",
...
}
]
}
Ad esempio, puoi recuperare e accedere alla descrizione del primo video in un’azione Experience HTML basata su codice come questa:
{{externalDataLookup actionId="d130c8e2-9a2d-45d5-bcb6-bc39865b4a56" result="result"}}
First video description: <b>result.videos[0].description</b>
Oppure, ad esempio, puoi recuperare e sfogliare gli elementi per restituire un array di elementi in un’azione JSON per l’esperienza basata su codice come segue:
{{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}}
]
Risoluzione dei problemi
Timeout e gestione degli errori
Journey Optimizer utilizza un timeout rigido quando chiama l’endpoint esterno per mantenere le caratteristiche di prestazioni a bassa latenza e throughput elevato per Adobe Experience Platform Edge Network.
Se l’endpoint si interrompe o viene rilevato un errore di qualsiasi tipo che raggiunge l’endpoint, la variabile di risultato sarà vuota. Anche eventuali riferimenti agli attributi all’interno della variabile di risultato in questo caso saranno vuoti. Se visualizzi semplicemente l’attributo nel contenuto, questo verrà visualizzato come vuoto. Se si tenta di scorrere ciclicamente un attributo di array nel risultato, non verrà restituito alcun elemento.
Se desideri gestire in modo più appropriato i timeout o gli errori mostrando il contenuto di fallback, puoi verificare se il risultato della ricerca è vuoto e visualizzare in tal caso il contenuto di fallback.
Ad esempio, puoi visualizzare un valore di fallback per un singolo attributo come questo:
First video description: {%=result.videos[0].description ?: "none found" %}
oppure puoi eseguire il rendering condizionale di un intero blocco di contenuto come questo:
{{externalDataLookup actionId="d130c8e2-9a2d-45d5-bcb6-bc39865b4a56" result="result"}}
{%#if result%}
... do something with result ...
{%else%}
... return fallback content ...
{%/if%}
Eseguire il debug
Per facilitare il debug, i dettagli del timeout e dell’errore per le ricerche di dati esterni sono inclusi nella vista Edge Delivery in Adobe Experience Platform Assurance. Se non visualizzi i risultati previsti per un helper externalDataLookup in un’azione in entrata, puoi avviare una sessione Assurance, avviare una chiamata Journey Optimizer da un’implementazione web o mobile e utilizzare la visualizzazione Edge Delivery per verificare i dettagli di timeout o errore.
Ad esempio:
Nella sezione Edge Delivery di traccia dell’affidabilità come parte dei dettagli di esecuzione è stato aggiunto un nuovo blocco customActions con dettagli di richiesta e risposta simili a quelli riportati di seguito. La sezione errori dovrebbe facilitare il debug in caso di problemi durante l’esecuzione di un’azione personalizzata
Domande frequenti faq-external-data
Di seguito sono riportate le domande frequenti sull’helper per la ricerca di dati esterni.
Hai bisogno di altri dettagli? Utilizza le opzioni di feedback nella parte inferiore di questa pagina per porre la tua domanda o connetterti alla community Adobe Journey Optimizer.
Utilizza il menu Attributi contestuali > Stream di dati > Evento per sfogliare lo schema Experience Event in uso e inserire l’attributo rilevante come valore di parametro come segue:
| 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.
Personas:
- developer: Can pass payload variable parameters to the externalDataLookup helper using the data types String, Integer, Decimal, Boolean, listString, listInt, listInteger and listDecimal. Can specify API key-based or plaintext authorization keys as header fields in the Action configuration. The page states that Journey Optimizer does not validate references to JSON attributes from the response used in expressions. Where: “Guardrails and Limitations”.
Onboarding:
- Level: Experienced
- First minimal step: Create an Action to configure the endpoint for the lookup.
- Success check: The Action ID appears and can be copied after the Action is created.
- Previous: Configure an Action before using the externalDataLookup helper: Configure a custom action (action/about-custom-action-configuration.md)
- Next: Learn more about the maximum number of lookups allowed in an inbound message request: Journey Optimizer guardrails and limitations (start/guardrails.md)