HTTP API连接
概述 overview
HTTP API目标是 Adobe Experience Platform 可帮助您将配置文件数据发送到第三方HTTP端点的流式目标。
要将配置文件数据发送到HTTP端点,您必须首先 连接到目标 在 Adobe Experience Platform.
用例 use-cases
HTTP API目标允许您将XDM配置文件数据和受众导出到通用HTTP端点。 在那里,您可以运行自己的Analytics,或对从Experience Platform中导出的配置文件数据执行任何其他您可能需要的操作。
HTTP端点可以是客户自己的系统或第三方解决方案。
支持的受众 supported-audiences
此部分介绍哪些类型的受众可以导出到此目标。
导出类型和频率 export-type-frequency
有关目标导出类型和频率的信息,请参阅下表。
先决条件 prerequisites
要使用HTTP API目标从Experience Platform中导出数据,您必须满足以下先决条件:
- 您必须具有支持REST API的HTTP端点。
- 您的HTTP端点必须支持Experience Platform配置文件架构。 HTTP API目标不支持转换到第三方有效负载架构。 请参阅 导出的数据 部分中的Experience Platform输出模式示例。
- 您的HTTP端点必须支持标头。
IP地址允许列表 ip-address-allowlist
为了满足客户的安全性和合规性要求,Experience Platform提供了您可以允许列表以用于HTTP API目标的静态IP列表。 请参阅 列入允许列表流目的地的IP地址 要允许列表的IP的完整列表。
支持的身份验证类型 supported-authentication-types
HTTP API目标支持对HTTP端点使用多种身份验证类型:
- 没有身份验证的HTTP端点;
- 持有者令牌认证;
- OAuth 2.0客户端凭据 使用body表单进行身份验证,使用 client ID, client secret、和 grant type (在HTTP请求正文中,如以下示例所示)。
curl --location --request POST '<YOUR_API_ENDPOINT>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>'
- OAuth 2.0客户端凭据 具有基本授权,并具有包含URL编码的授权标头 client ID 和 client secret.
curl --location --request POST 'https://some-api.com/token' \
--header 'Authorization: Basic base64(clientId:clientSecret)' \
--header 'Content-type: application/x-www-form-urlencoded; charset=UTF-8' \
--data-urlencode 'grant_type=client_credentials'
连接到目标 connect-destination
要连接到此目标,请按照 目标配置教程. 连接到此目标时,必须提供以下信息:
身份验证信息 authentication-information
持有者令牌身份验证 bearer-token-authentication
如果您选择 持有者令牌 要连接到HTTP端点的身份验证类型,请输入以下字段并选择 连接到目标:
- 持有者令牌:插入持有者令牌以对HTTP位置进行身份验证。
无身份验证 no-authentication
如果您选择 无 要连接到HTTP端点的身份验证类型:
当选择此身份验证打开时,您只需选择 连接到目标 并且已建立与端点的连接。
OAuth 2密码身份验证 oauth-2-password-authentication
如果您选择 OAuth 2密码 要连接到HTTP端点的身份验证类型,请输入以下字段并选择 连接到目标:
- 访问令牌URL:您颁发访问令牌以及(可选)刷新令牌的URL。
- 客户端ID:和 client ID 系统分配给Adobe Experience Platform的区段。
- 客户端密码:和 client secret 系统分配给Adobe Experience Platform的区段。
- 用户名:用于访问HTTP端点的用户名。
- 密码:用于访问HTTP端点的密码。
OAuth 2客户端凭据身份验证 oauth-2-client-credentials-authentication
如果您选择 OAuth 2客户端凭据 要连接到HTTP端点的身份验证类型,请输入以下字段并选择 连接到目标:
-
访问令牌URL:您颁发访问令牌以及(可选)刷新令牌的URL。
-
客户端ID:和 client ID 系统分配给Adobe Experience Platform的区段。
-
客户端密码:和 client secret 系统分配给Adobe Experience Platform的区段。
-
客户端凭据类型:选择您的端点支持的OAuth2客户端凭据授权类型:
填写目标详细信息 destination-details
要配置目标的详细信息,请填写下面的必需和可选字段。 UI中字段旁边的星号表示该字段为必填字段。
- 名称:输入一个名称,您将在将来通过名称识别此目标。
- 描述:输入可帮助您将来识别此目标的描述。
- 标题:输入要包含在目标调用中的任何自定义标头,格式如下:
header1:value1,header2:value2,...headerN:valueN
. - HTTP端点:要将配置文件数据发送到的HTTP端点的URL。
- 查询参数:或者,您也可以将查询参数添加到HTTP端点URL。 格式化您使用的查询参数,如下所示:
parameter1=value¶meter2=value
。 - 包括区段名称:如果您希望数据导出包含所导出受众的名称,请进行切换。 有关选中此选项的数据导出示例,请参阅 导出的数据 部分。
- 包括区段时间戳:如果您希望数据导出包括创建和更新受众时的UNIX时间戳,以及将受众映射到目标以供激活时的UNIX时间戳,则可以进行切换。 有关选中此选项的数据导出示例,请参阅 导出的数据 部分。
启用警报 enable-alerts
您可以启用警报,以接收有关发送到目标的数据流状态的通知。 从列表中选择警报以订阅接收有关数据流状态的通知。 有关警报的详细信息,请参阅以下内容中的指南: 使用UI订阅目标警报.
完成提供目标连接的详细信息后,选择 下一个.
激活此目标的受众 activate
请参阅 将受众数据激活到流式配置文件导出目标 有关将受众激活到此目标的说明。
目标属性 attributes
在 选择属性 步骤,Adobe建议您从 合并架构. 选择要导出到目标的唯一标识符和任何其他XDM字段。
配置文件导出行为 profile-export-behavior
Experience Platform可优化将配置文件导出到HTTP API目标的行为,以便仅在符合受众资格或其他重要事件后对配置文件进行了相关更新时将数据导出到API端点。 在以下情况下,会将配置文件导出到您的目标:
- 配置文件更新取决于映射到目标的至少一个受众的受众成员身份发生更改。 例如,配置文件已符合映射到目标的其中一个受众的条件,或已退出映射到目标的其中一个受众。
- 用户档案更新由 身份映射. 例如,对于已经符合映射到目标的其中一个受众资格的用户档案,在身份映射属性中添加了一个新身份。
- 配置文件更新由映射到目标的至少一个属性的更改确定。 例如,将映射步骤中映射到目标的某个属性添加到配置文件中。
在上述所有情况中,只会将已发生相关更新的用户档案导出到您的目标。 例如,如果映射到目标流的受众具有一百个成员,并且有五个新配置文件符合该区段的条件,则导出到目标的操作将以增量方式进行,并且只包括五个新配置文件。
请注意,所有映射的属性都会导出到配置文件,无论更改位于何处。 因此,在上面的示例中,将导出这五个新配置文件的所有映射属性,即使属性本身未发生更改也是如此。
决定数据导出的因素以及导出中包含的内容 what-determines-export-what-is-included
对于为给定用户档案导出的数据,了解 确定导出到HTTP API目标的数据的方法 和 哪些数据包含在导出中.
- 映射的属性和受众会作为目标导出的提示。 这意味着,如果任何映射的受众更改状态(从
null
到realized
或从realized
到exiting
)或者更新任何映射的属性,则将会启动目标导出。 - 由于身份当前无法映射到HTTP API目标,因此给定配置文件上任何身份的更改也将决定目标导出。
- 属性的更改被定义为属性上的任何更新,无论其是否为相同的值。 这意味着即使值本身未发生更改,也会将覆盖属性视为更改。
- 此
segmentMembership
对象包括在激活数据流中映射的受众,对于该受众,在资格或受众退出事件后,用户档案的状态已发生更改。 请注意,如果配置文件符合条件的其他未映射受众属于同一受众,则这些受众也可以作为目标导出的一部分 合并策略 与激活数据流中映射的受众相同。 - 中的所有标识
identityMap
对象也包含在内(Experience Platform当前不支持HTTP API目标中的标识映射)。 - 目标导出中只包含映射的属性。
例如,考虑将此数据流映射到HTTP目标,其中在数据流中选择了三个受众,并且四个属性映射到目标。
导出到目标的配置文件可由符合或退出其中一个配置文件来确定 三个映射区段. 但是,在数据导出中,将 segmentMembership
对象(请参阅 导出的数据 如果特定配置文件是其他未映射受众的成员,并且这些受众与触发导出的受众共享相同的合并策略,则可能会显示其他未映射受众。 如果配置文件符合 拥有DeLorean Cars的客户 区段,但同时也是 观看了《回到未来》 电影和 科幻迷们 然后,其他这两个受众也将出现在中 segmentMembership
数据导出的对象,即使这些对象未在数据流中映射,只要它们与共享相同的合并策略 拥有DeLorean Cars的客户 区段。
从配置文件属性的角度来看,对上述四个映射属性所做的任何更改都将决定目标导出,并且配置文件中存在的四个映射属性中的任何一个都会出现在数据导出中。
历史数据回填 historical-data-backfill
在将新受众添加到现有目标时,或者创建新目标并将受众映射到该目标时,Experience Platform会将历史受众资格数据导出到该目标。 符合受众资格的用户档案 早于 向目标添加的受众会在大约一小时内导出到目标。
导出的数据 exported-data
已导出 Experience Platform 数据登陆到 HTTP JSON格式的目标。 例如,以下导出包含一个符合某个区段资格条件的配置文件,该配置文件是另一个区段的成员,并且已退出另一个区段。 导出还包括配置文件属性名字、姓氏、出生日期和个人电子邮件地址。 此配置文件的身份为ECID和电子邮件。
{
"person": {
"birthDate": "YYYY-MM-DD",
"name": {
"firstName": "John",
"lastName": "Doe"
}
},
"personalEmail": {
"address": "john.doe@acme.com"
},
"segmentMembership": {
"ups":{
"7841ba61-23c1-4bb3-a495-00d3g5fe1e93":{
"lastQualificationTime":"2022-01-11T21:24:39Z",
"status":"exited"
},
"59bd2fkd-3c48-4b18-bf56-4f5c5e6967ae":{
"lastQualificationTime":"2022-01-02T23:37:33Z",
"status":"realized"
},
"947c1c46-008d-40b0-92ec-3af86eaf41c1":{
"lastQualificationTime":"2021-08-25T23:37:33Z",
"status":"realized"
},
"5114d758-ce71-43ba-b53e-e2a91d67b67f":{
"lastQualificationTime":"2022-01-11T23:37:33Z",
"status":"realized"
}
}
},
"identityMap": {
"ecid": [
{
"id": "14575006536349286404619648085736425115"
},
{
"id": "66478888669296734530114754794777368480"
}
],
"email_lc_sha256": [
{
"id": "655332b5fa2aea4498bf7a290cff017cb4"
},
{
"id": "66baf76ef9de8b42df8903f00e0e3dc0b7"
}
]
}
}
以下是导出数据的更多示例,具体取决于您在的连接目标流中选择的UI设置 包括区段名称 和 包括区段时间戳 选项:
segmentMembership
部分code language-json |
---|
|
segmentMembership
部分code language-json |
---|
|
限制和重试策略 limits-retry-policy
在95%的时间中,Experience Platform会尝试为成功发送的消息提供少于10分钟的吞吐量延迟,每个数据流向HTTP目的地的请求速率每秒少于10,000次。
如果对HTTP API目标的请求失败,Experience Platform将存储失败的请求,并重试两次以将请求发送到您的端点。