文件 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