文档 Journey Optimizer Journey Optimizer 指南

外部数据源 external-data-sources

最近更新： 2026年9月13日

主题：
管理
配置

创建对象：

中级
管理员
开发人员

在此页面上：连接到第三方REST API并配置身份验证，以便您将外部数据提取到历程中以进行条件和个性化。

style

shade-box

使用外部数据源 gs-ext-data-sources

外部数据源允许您与第三方系统建立连接，例如在使用酒店预订系统时，可通过该连接检查用户是否已登记房间。与内置Adobe Experience Platform数据源相反，您可以根据需要创建尽可能多的外部数据源。

NOTE

此页面上列出了使用外部系统时的护栏。
由于现在支持响应，因此您应该对外部数据源用例使用自定义操作而不是数据源。有关响应的详细信息，请参阅自定义操作响应。当数据仅在历程中有用并且外部系统可通过API端点访问时，无数据湖持久性的自定义操作是正确的选择。有关所有数据访问选项的比较，请参阅选择您的数据访问策略。

支持使用 POST 或 GET 的 REST API 和返回 JSON。支持 API 密钥、基本和自定义身份验证模式。

让我们举一个天气 API 服务的例子，我想借助该服务根据实时天气数据定制我的历程的行为。

以下是两个 API 调用示例：

https://api.adobeweather.org/weather?city=London,uk&appid=1234
https://api.adobeweather.org/weather?lat=35&lon=139&appid=1234

该调用由一个主 URL (https://api.adobeweather.org/weather)、两个参数集（“city”表示城市，“lat/long”表示纬度和经度）和 API 密钥 (appid) 组成。

TIP

我们建议在外部API的令牌有效期与Journey Optimizer cacheDuration设置之间至少保留一分钟的缓冲区，特别是在工作负载较重的情况下，以避免过期不匹配和401错误。

创建和配置外部数据源 create-ext-data-sources

以下是创建和配置新外部数据源的主要步骤：

从数据源列表中，单击 创建数据Source 以创建新的外部数据源。

这将打开屏幕右侧的数据源配置窗格。

在屏幕右侧打开
输入数据源的名称。

只允许使用字母数字字符和下划线。最大长度为30个字符。

向数据源添加描述。此步骤是可选的。

添加外部服务的 URL。在我们的示例中：https://api.adobeweather.org/weather。

note caution
CAUTION
出于安全原因，我们强烈建议使用 HTTPS。另请注意，我们不允许使用非公开的Adobe地址和IP地址。

外部数据源URL字段输入了示例天气API终结点

根据外部服务配置配置身份验证： 无身份验证、基本、自定义或API密钥。

对于基本身份验证模式，您需要填写用户名和密码。

note
NOTE
执行身份验证调用时，在Authentication标头中添加以base64编码的字符串`<username>:<password>`。 Adobe Journey Optimizer自动加密自定义操作中定义的密钥。每个组织的加密密钥都在一个与其组织绑定的专用保险库中受到安全管理。当凭据显示在界面中时，默认情况下它们会被掩盖，以防止意外泄露。

有关自定义身份验证模式的详细信息，请参阅自定义身份验证模式部分。在我们的示例中，我们选择API密钥身份验证模式，如下所示：

类型： “API密钥”
名称：“appid”（这是API密钥参数名称）
值：“1234”（这是我们API密钥的值）
位置：“查询参数”（API密钥位于URL中）

显示“类型”、“名称”、“值”和“位置”输入的

通过单击添加新字段组，为每个API参数集添加新字段组。字段组名称中只允许使用字母数字字符和下划线。最大长度为30个字符。在我们的示例中，我们需要创建两个字段组，每个参数集（“city”和“long/lat”）各一个。

对于“long/lat”参数集，我们创建一个包含以下信息的字段组：

用于：显示使用字段组的历程数。您可以单击 查看历程 图标以显示使用此字段组的历程列表。
方法：选择POST或GET方法。在我们的示例中，我们选择 GET 方法。
动态值：在我们的示例中，输入用逗号“long，lat”分隔的不同参数。由于参数值取决于执行上下文，因此将在历程中进行定义。了解有关表达式的详细信息
响应有效负载：在 有效负载 字段中单击，并粘贴调用返回的有效负载示例。例如，我们使用了在天气 API 网站上找到的有效负载。验证字段类型是否正确。每次调用 API 时，系统将检索有效负载示例中包含的所有字段。请注意，如果要更改当前传递的有效负载，可以单击粘贴新的有效负载。
已发送有效负载：在我们的示例中不显示此字段。仅当选择 POST 方法时才可用。粘贴将发送到第三方系统的有效负载。

如果GET调用需要参数，请在 动态值 字段中输入参数，这些参数将在调用结束时自动添加。如果是 POST 调用，您需要：

在 动态值 字段中列出调用时要传递的参数（在以下示例中：“标识符”）。
在发送的有效负载主体中使用完全相同的语法指定它们。为此，您需要添加“param”：“您的参数名称”（在以下示例中为“identifier”）。请遵循以下语法：

{"id":{"param":"identifier"}}

具有动态值和响应有效负载字段的字段组配置面板

保存更改后，数据源即配置完毕，可随时用于您的历程，例如在您的条件下或个性化电子邮件时。如果温度高于 30°C，您可以决定发送特定通信。

自定义身份验证模式 custom-authentication-mode

自定义身份验证模式用于复杂身份验证，通常用于调用OAuth2等API封装协议，以检索要插入到操作的实际HTTP请求中的访问令牌。

配置自定义身份验证时，请使用 单击以检查身份验证 按钮来控制自定义身份验证有效负载是否已正确配置。

数据源配置中的自定义身份验证测试按钮

测试成功后，按钮将变为绿色。

身份验证测试按钮变为绿色，表示验证成功

在此身份验证模式下，操作执行分为两步：

调用端点以生成访问令牌。
通过以正确的方式插入访问令牌以调用 REST API。

NOTE

此身份验证分为两部分。

要调用以生成访问令牌的端点的定义 custom-authentication-endpoint

endpoint：用于生成终结点的URL
终结点（GET或POST）上的HTTP请求方法
headers：键值对将作为标头插入此调用（如果需要）
body：描述方法为POST时的调用正文。我们支持一个有限的主体结构，在bodyParams（键值对）中定义。 bodyType 描述调用中主体的格式和编码：
- form：表示内容类型将为application/x-www-form-urlencoded (charset UTF-8)，并且键值对将按如下方式进行序列化：key1=value1&key2=value2&…
- json：表示内容类型将为application/json (charset UTF-8)，并且键值对将序列化为json对象，如下所示： { “key1”： “value1”， “key2”： “value2”， …}

在操作的HTTP请求中必须插入访问令牌方式的定义 custom-authentication-access-token

authorizationType：定义如何在操作的HTTP调用中插入生成的访问令牌。可能的值包括：
- bearer：表示必须在授权标头中插入访问令牌，如： 授权：持有者<access token>
- header：指示访问令牌必须作为标头插入，该标头名称由属性tokenTarget定义。例如，如果tokenTarget是myHeader，则访问令牌将作为标头插入： myHeader： <access token>
- queryParam：指示访问令牌必须作为queryParam插入，即由属性tokenTarget定义的查询参数名称。例如，如果 tokenTarget 是 myQueryParam，则操作调用的 URL 将为：<url>?myQueryParam=<access token>
tokenInResponse：指示如何从身份验证调用中提取访问令牌。此属性可以是：
- response：指示HTTP响应是访问令牌
- json中的选择器（假定响应为json，我们不支持XML等其他格式）。此选择器的格式为 json://<path to the access token property>。例如，如果调用的响应为 { "access token": “theToken”、“timestamp”: 12323445656 }，则 tokenInResponse 将为 json: //access_token_

此身份验证的格式为：

{
    "type": "customAuthorization",
    "endpoint": "<URL of the authentication endpoint>",
    "method": "<HTTP method to call the authentication endpoint, in 'GET' or 'POST'>",
    (optional) "headers": {
        "<header name>": "<header value>",
        ...
    },
    (optional, mandatory if method is 'POST') "body": {
        "bodyType": "<'form'or 'json'>,
        "bodyParams": {
            "param1": value1,
            ...
        }
    },
    "tokenInResponse": "<'response' or json selector in format 'json://<field path to access token>'",
    "cacheDuration": {
        (optional, mutually exclusive with 'duration') "expiryInResponse": "<json selector in format 'json://<field path to expiry>'",
        (optional, mutually exclusive with 'expiryInResponse') "duration": <integer value>,
        "timeUnit": "<unit in 'milliseconds', 'seconds', 'minutes', 'hours', 'days', 'months', 'years'>"
    },
    "authorizationType": "<value in 'bearer', 'header' or 'queryParam'>",
    (optional, mandatory if authorizationType is 'header' or 'queryParam') "tokenTarget": "<name of the header or queryParam if the authorizationType is 'header' or 'queryParam'>",
}

NOTE

Encode64是身份验证有效负载中唯一可用的函数。

您可以更改自定义身份验证数据源的令牌的缓存时间。以下是自定义身份验证有效负载的示例。缓存持续时间在cacheDuration参数中定义。它指定缓存中生成的令牌的保留持续时间。单位可以是毫秒、秒、分钟、小时、天、月、年。

以下是持有者身份验证类型的示例：

{
    "type": "customAuthorization",
    "endpoint": "https://<your_auth_endpoint>/epsilon/oauth2/access_token",
    "method": "POST",
    "headers": {
      "Authorization": "Basic EncodeBase64(<epsilon Client Id>:<epsilon Client Secret>)"
    },
    "body": {
      "bodyType": "form",
      "bodyParams": {
        "scope": "cn mail givenname uid employeeNumber",
        "grant_type": "password",
        "username": "<epsilon User Name>",
        "password": "<epsilon User Password>"
      }
    },
    "tokenInResponse": "json://access_token",
    "cacheDuration": {
      "duration": 5,
      "timeUnit": "minutes"
    },
  },

NOTE

每个历程缓存身份验证令牌：如果两个历程使用相同的自定义操作，则每个历程将缓存其自己的令牌。该令牌不会在这些历程之间共享。
缓存持续时间有助于避免对身份验证端点的调用过多。身份验证令牌保留缓存在服务中，没有持久性。如果重新启动服务，它会从干净的缓存开始。默认情况下，缓存持续时间为1小时。在自定义身份验证有效负载中，可以通过指定另一个保留持续时间来调整该有效负载。

基于证书的自定义身份验证 certificate-credential

对于强制实施基于证书的身份验证的企业API（如Microsoft Entra ID），您可以通过将"subType": "certificateCredential"添加到自定义授权有效负载来配置基于证书的自定义身份验证。 Journey Optimizer使用Adobe的托管证书来签署JWT客户端声明，并将其交换为访问令牌。不需要客户端密码。

此选项将两个必填字段添加到标准customAuthorization架构中： subType和aud。所有其他字段（endpoint、method、正文参数、tokenInResponse）保持不变。当subType不存在时，行为与标准自定义身份验证相同 — 不影响现有配置。

subType：设置为"certificateCredential"以激活基于证书的身份验证。
aud： JWT客户端断言中包含的受众值。对于Microsoft Entra ID，这与endpoint URL相同，但必须始终显式设置它。

client_assertion和client_assertion_type字段从未由用户创作。它们由平台在运行时自动注入，紧接在令牌端点调用之前。

工作原理 certificate-credential-how-it-works

基于证书的自定义身份验证使用JWT客户端断言实施OAuth 2.0客户端凭据，如RFC 7523中所定义，该标准与Microsoft Entra ID和Okta支持的标准相同。 Journey Optimizer使用使用Adobe的受管私钥签名的JWT来验证其身份，而不是客户端密码。您的身份提供程序使用Adobe的公共证书验证签名，您只需在身份提供程序中注册一次该公共证书。

令牌交换遵循以下步骤：

Journey Optimizer构建使用Adobe私钥签名的JWT客户端断言。
断言将随您的client_id、grant_type和scope一起发送到您的令牌端点。
您的身份提供程序根据Adobe注册的公共证书验证JWT签名。
您的身份提供程序返回持有者访问令牌。
Journey Optimizer使用该令牌调用您的自定义操作端点。

Adobe证书详细信息 certificate-credential-details

Adobe管理证书及其关联的私钥。下表概述了其主要属性：

属性

值

颁发者

DigiCert（公共CA）

管理者

Adobe

算法

RS256 (RSA)

在您的身份提供程序中注册什么

仅限Adobe的叶证书 — 不是中间或根CA

如何获取

从mTLS公共证书API检索它（请参阅下面的证书护栏）

旋转

Adobe会在过期前60天自动轮换证书（证书生命周期：13个月）。之前的证书有效期将持续到过期前30天。当前未通知客户轮换 — 定期调用mTLS公共证书API以检查expiryDate并重新配置您的IDP，然后再吊销旧证书。

Adobe会在过期前60天自动轮换证书。之前的证书有效期将持续到过期前30天。当前未通知客户 — 请参阅下面的证书轮换护栏，了解如何以编程方式监视轮换。

JWT断言结构 certificate-credential-jwt

您不编写JWT客户端声明 — Journey Optimizer会为您生成并签署该声明。此处提供了预期的结构，以便您的身份提供程序团队可以验证声明。

标题：

{
  "alg": "RS256",
  "x5t": "<base64url SHA-1 thumbprint of Adobe's leaf certificate>"
}

有效负载：

{
  "iss": "<client_id>",
  "sub": "<client_id>",
  "aud": "<token endpoint URL>",
  "iat": "<current unix timestamp>",
  "exp": "<iat + 600 seconds>",
  "jti": "<unique UUID per request>"
}

请注意以下事项：

exp − iat始终≤10分钟 — 与Okta和Entra ID要求一致。
每个断言都使用唯一的jti，这使得它不会受到重放攻击。
client_assertion和client_assertion_type由平台自动插入，从不创作。

以下是Microsoft Entra ID的证书凭据身份验证类型的示例：

{
  "type": "customAuthorization",
  "subType": "certificateCredential",
  "aud": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
  "authorizationType": "Bearer",
  "endpoint": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
  "method": "POST",
  "body": {
    "bodyType": "form",
    "bodyParams": {
      "client_id": "<your-client-id>",
      "grant_type": "client_credentials",
      "scope": "https://api.example.com/.default"
    }
  },
  "tokenInResponse": "json://access_token"
}

以下是Okta中相同证书凭据身份验证类型的示例：

{
  "type": "customAuthorization",
  "subType": "certificateCredential",
  "authorizationType": "bearer",
  "endpoint": "https://<your-okta-domain>/oauth2/v1/token",
  "aud": "https://<your-okta-domain>/oauth2/v1/token",
  "method": "POST",
  "body": {
    "bodyType": "form",
    "bodyParams": {
      "client_id": "<your-okta-app-client-id>",
      "grant_type": "client_credentials",
      "scope": "<your-api-scope>"
    }
  },
  "tokenInResponse": "json://access_token"
}

CAUTION

配置基于证书的自定义身份验证时，请牢记以下护栏：

令牌终结点URL：必须为HTTPS。避免包含?的URL — 这是粘贴授权终结点而不是令牌终结点的标志。
method：必须为POST。 OAuth令牌端点仅接受POST请求。
client_id：不能为空，并且不能包含前导或尾随空格。空白值会生成看起来有效的JWT，身份提供程序将以不透明错误拒绝该JWT。
scope：在bodyParams中以单个空格分隔的字符串表示。最多总计1000个字符。
证书： Adobe管理证书和私钥 — 您从不上传或输入证书。在实时历程中使用自定义操作之前，必须在身份提供程序中注册Adobe的叶证书。要检索它，请调用mTLS公共证书API并查找certCommonName为ajo-journeys.aep-mtls.adobe.com的条目。从该条目中注册publicCertificate值 — 不要使用中间或根CA证书。由于客户当前未收到证书轮换的通知，因此您必须定期调用mTLS公共证书API以检查expiryDate并更新IDP中的注册证书，这样旧证书在过期前30天被吊销。

标头身份验证类型的示例如下：

{
  "type": "customAuthorization",
  "endpoint": "https://myapidomain.com/v2/user/login",
  "method": "POST",
  "headers": {
    "x-retailer": "any value"
  },
  "body": {
    "bodyType": "form",
    "bodyParams": {
      "secret": "any value",
      "username": "any value"
    }
  },
  "tokenInResponse": "json://token",
  "cacheDuration": {
    "expiryInResponse": "json://expiryDuration",
    "timeUnit": "minutes"
  },
  "authorizationType": "header",
  "tokenTarget": "x-auth-token"
}

以下是登录API调用的响应示例：

{
  "token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S",
  "expiryDuration" : 5
}

CAUTION

为自定义操作配置自定义身份验证时，请注意，嵌套JSON对象（如bodyParams中的子对象）是支持的。

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 create and configure external data sources that connect to third-party REST APIs, including the supported authentication modes, field group setup, custom authentication payloads, and certificate-based custom authentication.

Intents:

Create and configure an external data source that connects to a third-party REST API
Choose an authentication mode among No authentication, Basic, Custom, and API key
Define field groups per API parameter set with Method, Dynamic Values, and payload fields
Configure custom authentication for protocols such as OAuth2 and check it with the check authentication button
Configure certificate-based custom authentication for enterprise APIs such as Microsoft Entra ID and Okta
Set the token cache duration to limit calls to the authentication endpoint

Glossary:

External data source: A connection to a third-party system that you create; you can create as many as you need (product-specific)
Field group: A set of fields configured per API parameter set, with Method, Dynamic Values, Response Payload, and (for POST) Sent Payload (product-specific)
Custom authentication mode: An authentication mode for complex protocols such as OAuth2, where the action execution is a two-step process that first generates an access token and then injects it in the HTTP request (product-specific)
cacheDuration: The parameter that specifies the retention duration of the generated token in the cache (product-specific)
Certificate-based custom authentication: A custom authentication subtype (subType: certificateCredential) where Journey Optimizer uses Adobe’s managed certificate to sign a JWT client assertion and exchange it for an access token, with no client secret required (product-specific)

Guardrails:

REST APIs using POST or GET and returning JSON are supported; API Key, basic, and custom authentication modes are supported.
Adobe addresses that are not publicly available and the use of IP addresses are not allowed; HTTPS is strongly recommended for security reasons.
Data source name: only alphanumeric characters and underscores are allowed, maximum length 30 characters (hard limit).
Field group name: only alphanumeric characters and underscores are allowed, maximum length 30 characters (hard limit).
The Sent Payload field is only available if you select the POST method.
The default cache duration is 1 hour (default) and can be adapted in the custom authentication payload; a one-minute buffer between the external API’s token expiration and the cacheDuration setting is recommended to avoid 401 errors.
The authentication token is cached per journey and is not shared between journeys; there is no persistence, so a service restart starts with a clean cache.
Encode64 is the only function available in the authentication payload.
For certificate-based custom authentication, subType and aud are mandatory; the token endpoint URL must be HTTPS, method must be POST, client_id must not be blank and must have no leading or trailing whitespace.
scope is a single space-separated string in bodyParams, maximum 1000 characters total (hard limit).
You never upload or enter a certificate; before using the custom action in a live journey you must register Adobe’s leaf certificate (not the intermediate or root CA) in your Identity Provider.
The Adobe certificate uses RS256 (RSA); Adobe rotates it 60 days before expiry (certificate lifetime 13 months) and the previous certificate remains valid until 30 days before expiry; customers are not currently notified, so periodically call the mTLS Public Certificate API to check the expiryDate.
Nested JSON objects (for example, sub-objects within bodyParams) are supported.

Terminology:

Canonical name: external data source — Acronym: n/a — variants: external data sources, third-party data source
Synonyms: “check the authentication” = “Click to check the authentication” button
Do not confuse: “Dynamic Values” (parameters defined in journeys and passed at call time) ≠ “Response Payload” (example payload returned by the call) ≠ “Sent Payload” (payload sent to the third-party system, POST only)
Do not confuse: “standard custom authentication” ≠ “certificate-based custom authentication” (subType: certificateCredential, using Adobe’s managed certificate instead of a client secret)

FAQ:

Q: What kinds of APIs are supported for external data sources? — REST APIs using POST or GET and returning JSON, with API Key, basic, or custom authentication modes.
Q: What is the maximum length of a data source or field group name? — 30 characters, using only alphanumeric characters and underscores.
Q: How do I verify that my custom authentication payload is configured correctly? — Use the Click to check the authentication button; when the test is successful, the button turns green.
Q: What is the default token cache duration and can I change it? — The default cache duration is 1 hour, and you can adapt it by specifying another retention duration in the cacheDuration parameter of the custom authentication payload.
Q: Do I need to upload a certificate for certificate-based custom authentication? — No, Adobe manages the certificate and private key; you register Adobe’s leaf certificate in your Identity Provider, retrieved from the mTLS Public Certificate API.
Q: Are nested JSON objects allowed in the custom authentication body? — Yes, nested JSON objects such as sub-objects within bodyParams are supported.

recommendation-more-help

journey-optimizer-help