文档 Journey Optimizer Journey Optimizer 指南

字段引用 field-references

最近更新： 2026年9月4日

适用对象：
Journey Orchestration

主题：
历程

创建对象：

Experienced
开发人员

字段引用可以附加到事件或字段组。唯一有意义的信息是字段的名称及其路径。

如果您在字段中使用特殊字符，则需要使用双引号或简单引号。以下是需要引用时的情况：

该字段以数字字符开头
字段以“ — ”字符开头
该字段包含a-z、A-Z、0-9、、-_以外的任何内容

例如，如果您的字段是3h： #{OpenWeather.weatherData.rain.‘3h’} > 0

// event field
@event{<event name>.<XDM path to the field>}
@event{LobbyBeacon.endUserIDs._experience.emailid.id}

// field group
#{<data source name>.<field group name>.<path to the field>}
#{ExperiencePlatform.ProfileFieldGroup.profile.personalEmail.address}

在表达式中，事件字段通过“@”引用，数据源字段通过“#”引用。

语法颜色用于直观地区分事件字段（绿色）和字段组（蓝色）。

字段引用的默认值 default-value

默认值可以与字段名称关联。语法如下：

// event field
@event{<event name>.<XDM path to the field>, defaultValue: <default value expression>}
@event{LobbyBeacon.endUserIDs._experience.emailid.id, defaultValue: "example@adobe.com"}
// field group
#{<data source name>.<field group name>.<path to the field>, defaultValue: <default value expression>}
#{ExperiencePlatform.ProfileFieldGroup.profile.personalEmail.address, defaultValue: "example@adobe.com"}

NOTE

字段的类型和默认值必须相同。例如，@event{LobbyBeacon.endUserIDs._experience.emailid.id, defaultValue : 2}无效，因为默认值为整数，而预期值应为字符串。

示例：

// for an event 'OrderEvent' having the following payload:
{
    "orderId": "12345"
}

expression example:
- @event{OrderEvent.orderId}                                    -> "12345"
- @event{OrderEvent.productId, defaultValue : "not specified" } -> "not specified" // default value, productId is not a field present in the payload
- @event{OrderEvent.productId}                                  -> null


// for an entity 'Profile' on datasource 'ACP' having fields person/lastName, with fetched data such as:
{
    "person": {
        "lastName":"Snow"
    },
    "emails": [
        { "email":"john.snow@winterfell.westeros" },
        { "email":"snow@thewall.westeros" }
    ]
}

expression examples:
- #{ACP.Profile.person.lastName}                 -> "Snow"
- #{ACP.Profile.emails.at(1).email}              -> "snow@thewall.westeros"
- #{ACP.Profile.person.age, defaultValue : -1}   -> -1 // default value, age is not a field present in the payload
- #{ACP.Profile.person.age}                      -> null

您可以添加任何类型的表达式作为默认值。唯一的限制是表达式必须返回预期的数据类型。使用函数时，需要使用()封装函数。

#{ExperiencePlatform.Subscriptions.profile.consents.marketing.any.time, defaultValue : (now())}
== date("2022-02-10T00:00:00Z")

对收藏集中字段的引用

集合中定义的元素使用特定函数all、first和last引用。有关详细信息，请参见此页面。

示例：

@event{LobbyBeacon._experience.campaign.message.profile.pushNotificationTokens.all()

对映射中定义的字段的引用

`entry`函数

为了检索映射中的元素，我们使用带有给定键的入口函数。例如，在根据选定的命名空间定义事件的键时使用该变量。有关详细信息，请参阅此页面。

@event{MyEvent.identityMap.entry('Email').first().id}

在此表达式中，我们将获得事件的“IdentityMap”字段的“Email”键的条目。 “Email”条目是一个集合，我们从其中使用“first()”获取第一个元素中的“id”。有关详细信息，请参阅此页面。

`firstEntryKey`函数

要检索映射的第一个条目键，请使用firstEntryKey函数。

此示例说明如何检索特定列表订阅者的第一个电子邮件地址：

#{ExperiencePlatform.Subscriptions.profile.consents.marketing.email.subscriptions.entry('daily-email').subscribers.firstEntryKey()}

在此示例中，订阅列表名为daily-email。电子邮件地址在subscribers映射中定义为键，该映射链接到订阅列表映射。

`keys`函数

要检索到映射的所有键，请使用keys函数。

此示例说明如何为特定用户档案检索与特定列表订阅者关联的所有电子邮件地址：

#{ExperiencePlatform.Subscriptions.profile.consents.marketing.email.subscriptions.entry('daily-mail').subscribers.keys()

数据源的参数值（数据源动态值）

如果您从外部数据源中选择字段，则需要调用一个参数，则右侧会显示一个新选项卡，允许您指定此参数。请参阅此页。

对于更复杂的用例，如果要在主表达式中包含数据源的参数，可以使用关键字 params 定义其值。参数可以是任何有效的表达式，即使来自还包含另一个参数的另一个数据源也是如此。

NOTE

在表达式中定义参数值时，右侧的选项卡消失。

使用以下语法：

#{<datasource>.<field group>.fieldName, params: {<params-1-name>: <params-1-value>, <params-2-name>: <params-2-value>}}

<params-1-name>：数据源中第一个参数的确切名称。
<params-1-value>：第一个参数的值。它可以是任何有效的表达式。

示例：

#{Weather.main.temperature, params: {localisation: @event{Profile.address.localisation}}}
#{Weather.main.temperature, params: {localisation: #{GPSLocalisation.main.coordinates, params: {city: @event{Profile.address.city}}}}}

AI Knowledge Reference

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 reference event fields and data source field groups in journey expressions, including default value syntax, map access functions (entry, firstEntryKey, keys), and inline data source parameter passing with the params keyword.

Intents:

Reference an event field in an expression using the @event{eventName.fieldPath} syntax
Reference a data source field group using the #{dataSourceName.fieldGroupName.fieldPath} syntax
Assign a fallback default value to a field reference so expressions do not return null
Retrieve a specific entry from an identity map or subscription map using the entry() function
Retrieve all keys from a map field using the keys() function
Pass parameter values to an external data source inline using the params keyword

Glossary:

Field reference: An expression syntax that points to a named field within an event payload or data source field group (product-specific)
defaultValue: An optional fallback expression appended to a field reference that is returned when the field is absent or null (product-specific)
entry(key): A map function that retrieves the collection entry associated with the given key (product-specific)
firstEntryKey(): A map function that returns the first key of a map field (product-specific)
keys(): A map function that returns all keys of a map field (product-specific)
params keyword: Inline syntax for specifying parameter values for external data source fields within the main expression (product-specific)

Guardrails:

Field names containing special characters (starting with a digit, containing -, or characters outside a-z A-Z 0-9 _) must be wrapped in single or double quotes
The default value expression must return the same data type as the field — mismatched types are invalid
When the params keyword is used to define parameter values inline, the separate parameter tab on the right of the editor disappears
Functions used as default values must be encapsulated in parentheses

Terminology:

Canonical name: Field References — Acronym: none — variants: field path, field expression
Synonyms: @event{...} = “event field reference”; #{...} = “data source field reference”
Do not confuse: event fields (prefixed @) ≠ data source fields (prefixed #)

FAQ:

Q: How do I reference a field whose name starts with a number? — Wrap the field name in single or double quotes, e.g. #{OpenWeather.weatherData.rain.'3h'}.
Q: What happens when a referenced field is missing from the event payload and no default value is set? — The expression returns null.
Q: How do I set a dynamic default value using a function? — Wrap the function call in parentheses, e.g. defaultValue: (now()).
Q: How do I retrieve the email address stored as the first key in a subscriber map? — Use the firstEntryKey() function on the subscribers map field.
Q: How do I pass a parameter to an external data source without using the right-side tab? — Use the params keyword inline: #{DataSource.group.field, params: {paramName: value}}.

recommendation-more-help

journey-optimizer-help