外部数据源 external-data-sources
外部数据源允许您定义与第三方系统的连接，例如，如果您使用酒店预订系统来检查人员是否已注册了房间。与内置 Adobe Experience Platform 数据源相反，您可以根据需要创建尽可能多的外部数据源。
支持使用 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) 组成。
以下是创建和配置新外部数据源的主要步骤：
-
在数据源列表中，单击 创建数据源 以创建新的外部数据源。
这将打开屏幕右侧的数据源配置窗格。
-
输入数据源的名称。
note note NOTE 请勿使用空格或特殊字符。请勿使用超过 30 个字符。 -
向数据源添加描述。此步骤是可选的。
-
添加外部服务的 URL。在我们的示例中：https://api.adobeweather.org/weather。
note caution CAUTION 出于安全原因，我们强烈建议使用 HTTPS。另请注意，我们不允许使用非公开的 Adobe 地址和 IP 地址。 
-
根据外部服务配置配置身份验证： 无身份验证， 基本， 自定义 或 API密钥.
对于基本身份验证模式，您需要填写用户名和密码。
note note NOTE 执行身份验证调用时， <username>:<password>在base64中编码的字符串将添加到身份验证标头中。有关自定义身份验证模式的更多信息，请参阅此部分。在我们的示例中，我们选择API密钥身份验证模式：
- 类型：“API密钥”
- 名称：“appid”（这是API密钥参数名称）
- 值：“1234”（这是API密钥的值）
- 位置：“查询参数”（API密钥位于URL中）
-
通过单击为每个API参数集添加新字段组 添加新字段组. 请勿在字段组名称中使用空格或特殊字符。在我们的示例中，我们需要创建两个字段组，每个参数集（“city”和“long/lat”）各一个。
对于“long/lat”参数集，我们创建一个包含以下信息的字段组：
-
使用位置：显示使用字段组的旅程数。 您可以单击 查看历程 图标，以显示使用此字段组的旅程列表。
-
方法：选择POST或GET方法。 在我们的示例中，我们选择 GET 方法。
-
动态值：在我们的示例中，输入以逗号分隔的不同参数“long，lat”。 由于参数值取决于执行上下文，因此将在历程中进行定义。了解详情
-
响应有效负载：在内部单击 有效负荷 字段，并粘贴由调用返回的有效负载示例。 例如，我们使用了在天气 API 网站上找到的有效负载。验证字段类型是否正确。每次调用 API 时，系统将检索有效负载示例中包含的所有字段。请注意，您可以单击 粘贴新的有效负载 （如果要更改当前传递的有效负载）。
-
已发送有效负载：在我们的示例中不显示此字段。 仅当选择 POST 方法时才可用。粘贴将发送到第三方系统的有效负载。
如果GET调用需要参数，请在 动态值 字段，并在调用结束时自动添加它们。 如果是 POST 调用，您需要：
-
在中列出调用时要传递的参数 动态值 字段（在以下示例中：“identifier”）。
-
在发送的有效负载主体中使用完全相同的语法指定它们。为此，您需要添加“param”：“您的参数名称”（在以下示例中为“identifier”）。 请遵循以下语法：
code language-none {"id":{"param":"identifier"}}
单击 保存。
数据源现已配置完毕，可随时用于您的历程，例如在您的条件下或个性化电子邮件时。如果温度高于 30°C，您可以决定发送特定通信。
自定义身份验证模式 custom-authentication-mode
此身份验证模式用于复杂的身份验证，通常用于调用 OAuth2 等 API 封装协议，以检索要插入到操作的实际 HTTP 请求中的访问令牌。
配置自定义身份验证时，可以单击以下按钮检查自定义身份验证有效负载是否正确配置。
如果测试成功，按钮将变为绿色。
通过此身份验证，操作执行分为两步：
- 调用端点以生成访问令牌。
- 通过以正确的方式插入访问令牌以调用 REST API。
要调用以生成访问令牌的端点的定义
-
端点：用于生成端点的 URL
-
端点上 HTTP 请求的方法（GET 或 POST）
-
标头：键值对将作为标头插入此调用（如果需要）
-
主体：描述在方法为 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请求中必须插入访问令牌方式的定义
-
authorizationType：定义如何在操作的 HTTP 调用中插入生成的访问令牌。可能的值包括：
- 载体：指示必须在授权标头中插入的访问令牌，如：授权：载体<access token>
- 标头：指示必须将访问令牌作为标头插入，即由 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'>",
}
您可以更改自定义身份验证数据源的令牌的缓存时间。以下是自定义身份验证有效负载的示例。缓存时间在“cacheDuration”参数中定义。它指定缓存中生成的令牌的保留持续时间。单位可以是毫秒、秒、分钟、小时、天、月、年。
以下是持有者身份验证类型的示例：
{
"authentication": {
"type": "customAuthorization",
"authorizationType": "Bearer",
"endpoint": "https://localhost:${port}/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"
}
}
}
标头身份验证类型的示例如下：
{
"type": "customAuthorization",
"authorizationType": "header",
"tokenTarget": "x-auth-token",
"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"
}
}
以下是登录API调用的响应示例：
{
"token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S",
"expiryDuration" : 5
}