外部数据源 external-data-sources

外部数据源允许您定义与第三方系统的连接,例如,如果您使用酒店预订系统来检查人员是否已注册了房间。与内置 Adobe Experience Platform 数据源相反,您可以根据需要创建尽可能多的外部数据源。

NOTE
中列出了使用外部系统时的护栏 此页面.
NOTE
由于现在支持响应,因此您应该对外部数据源用例使用自定义操作而不是数据源。

支持使用 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) 组成。

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

  1. 在数据源列表中,单击 创建数据源 以创建新的外部数据源。

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

  2. 输入数据源的名称。

    note note
    NOTE
    只允许使用字母数字字符和下划线。 最大长度为30个字符。
  3. 向数据源添加描述。此步骤是可选的。

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

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

  5. 根据外部服务配置配置身份验证: 无身份验证基本自定义API密钥.

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

    note note
    NOTE
    执行身份验证调用时, <username>:<password> 在base64中编码的字符串将添加到身份验证标头中。

    有关自定义身份验证模式的更多信息,请参阅此部分。在我们的示例中,我们选择API密钥身份验证模式:

    • 类型:“API密钥”
    • 名称:“appid”(这是API密钥参数名称)
    • :“1234”(这是API密钥的值)
    • 位置:“查询参数”(API密钥位于URL中)

  6. 通过单击为每个API参数集添加新字段组 添加新字段组. 字段组名称中只允许使用字母数字字符和下划线。 最大长度为30个字符。 在我们的示例中,我们需要创建两个字段组,每个参数集(“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 请求中的访问令牌。

配置自定义身份验证时,可以单击以下按钮检查自定义身份验证有效负载是否正确配置。

如果测试成功,按钮将变为绿色。

通过此身份验证,操作执行分为两步:

  1. 调用端点以生成访问令牌。
  2. 通过以正确的方式插入访问令牌以调用 REST API。
NOTE
此身份验证分为两部分。

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

  • 端点:用于生成端点的 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请求中必须插入访问令牌方式的定义 custom-authentication-access-token

  • 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'>",
}
NOTE
Encode64是身份验证有效负载中唯一可用的函数。

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

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

{
  "authentication": {
    "type": "customAuthorization",
    "authorizationType": "Bearer",
    "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小时。 在自定义身份验证有效负载中,可以通过指定另一个保留持续时间来调整该有效负载。

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

{
  "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
}
recommendation-more-help
b22c9c5d-9208-48f4-b874-1cefb8df4d76