[Ultimate]{class="badge positive"}

HTTP API连接

概述 overview

IMPORTANT
此目标仅适用于Adobe Real-time Customer Data Platform Ultimate客户。

HTTP API目标是一个Adobe Experience Platform流目标,可帮助您将配置文件数据发送到第三方HTTP端点。

若要将配置文件数据发送到HTTP端点,您必须先在Adobe Experience Platform中连接到目标

用例 use-cases

HTTP API目标允许您将XDM配置文件数据和受众导出到通用HTTP端点。 在那里,您可以运行自己的Analytics,或对从Experience Platform中导出的配置文件数据执行任何其他您可能需要的操作。

HTTP端点可以是客户自己的系统或第三方解决方案。

支持的受众 supported-audiences

此部分介绍哪些类型的受众可以导出到此目标。

受众来源
支持
描述
Segmentation Service
✓ {\f13 }
通过Experience Platform分段服务生成的受众。
自定义上传
✓ {\f13 }
受众已将从CSV文件导入到Experience Platform中。

导出类型和频率 export-type-frequency

有关目标导出类型和频率的信息,请参阅下表。

项目
类型
注释
导出类型
基于配置文件
您正在导出区段的所有成员,以及所需的架构字段(例如:电子邮件地址、电话号码、姓氏),如目标激活工作流的映射屏幕中所选。
导出频率
正在流式传输
流目标为基于API的“始终运行”连接。 一旦根据受众评估在Experience Platform中更新了用户档案,连接器就会将更新发送到下游目标平台。 阅读有关流式目标的更多信息。

先决条件 prerequisites

要使用HTTP API目标从Experience Platform中导出数据,您必须满足以下先决条件:

  • 您必须具有支持REST API的HTTP端点。
  • 您的HTTP端点必须支持Experience Platform配置文件架构。 HTTP API目标不支持转换到第三方有效负载架构。 有关Experience Platform输出架构的示例,请参阅导出的数据部分。
  • 您的HTTP端点必须支持标头。
TIP
您还可以使用Adobe Experience Platform Destination SDK设置集成并将Experience Platform配置文件数据发送到HTTP端点。

mTLS协议支持和证书 mtls-protocol-support

您可以使用Mutual Transport Layer Security (mTLS)来确保到HTTP API目标连接的出站连接中的增强安全性。

mTLS是一种用于相互身份验证的端到端安全方法,可确保共享信息的双方在共享数据之前都是声明的身份。 与TLS相比,mTLS包含额外的步骤,其中服务器还会请求客户端的证书并在其末尾验证它。

如果要将mTLS与HTTP API目标一起使用,则放入目标详细信息页面的服务器地址必须禁用TLS协议,并且仅启用mTLS。 如果终结点上仍启用TLS 1.2协议,则不会为客户端身份验证发送证书。 这意味着要将mTLS与您的HTTP API目标一起使用,您的“接收”服务器终结点必须是仅启用mTLS的连接终结点。

下载证书 certificate

如果要检查Common Name (CN)和Subject Alternative Names (SAN)以进行其他第三方验证,可以下载以下证书:

IP地址允许列表 ip-address-allowlist

为了满足客户的安全性和合规性要求,Experience Platform提供了您可以允许列表以用于HTTP API目标的静态IP列表。 有关要允许列表列入允许列表的IP的完整列表,请参阅流目标的IP地址

支持的身份验证类型 supported-authentication-types

HTTP API目标支持对HTTP端点使用多种身份验证类型:

  • 没有身份验证的HTTP端点;
  • 持有者令牌认证;
  • OAuth 2.0客户端凭据正文形式的身份验证,在HTTP请求正文中具有client ID、client secret和grant type,如下例所示。
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>'
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

IMPORTANT
若要连接到目标,您需要​ 查看目标 ​和​ 管理目标 访问控制权限。 阅读访问控制概述或联系您的产品管理员以获取所需的权限。

要连接到此目标,请按照目标配置教程中描述的步骤操作。 连接到此目标时,必须提供以下信息:

身份验证信息 authentication-information

持有者令牌身份验证 bearer-token-authentication

如果选择​ 持有者令牌 ​身份验证类型连接到HTTP终结点,请输入以下字段并选择​ 连接到目标

可以使用持有者令牌身份验证连接到HTTP API目标的UI屏幕图像。

  • 持有者令牌:插入持有者令牌以对HTTP位置进行身份验证。

无身份验证 no-authentication

如果选择​ ​身份验证类型连接到HTTP终结点:

UI屏幕的图像,您可以通过该屏幕不使用身份验证连接到HTTP API目标。

当选择此身份验证打开时,您只需要选择​ 连接到目标,并且与终结点的连接已建立。

OAuth 2密码身份验证 oauth-2-password-authentication

如果选择​ OAuth 2密码 ​身份验证类型以连接到您的HTTP端点,请输入以下字段并选择​ 连接到目标

UI屏幕的图像,在该屏幕中,您可以使用带有密码身份验证的OAuth 2连接到HTTP API目标。

  • 访问令牌URL:您颁发访问令牌以及(可选)刷新令牌的一方URL。
  • 客户端ID:系统分配给Adobe Experience Platform的client ID。
  • 客户端密钥:系统分配给Adobe Experience Platform的client secret。
  • 用户名:用于访问HTTP端点的用户名。
  • 密码:用于访问HTTP端点的密码。

OAuth 2客户端凭据身份验证 oauth-2-client-credentials-authentication

如果选择​ OAuth 2客户端凭据 ​身份验证类型连接到您的HTTP端点,请输入以下字段并选择​ 连接到目标

UI屏幕的图像,在该屏幕中,您可以将OAuth 2与客户端凭据身份验证结合使用,连接到HTTP API目标。

  • 访问令牌URL:您颁发访问令牌以及(可选)刷新令牌的一方URL。

  • 客户端ID:系统分配给Adobe Experience Platform的client ID。

  • 客户端密钥:系统分配给Adobe Experience Platform的client secret。

  • 客户端凭据类型:选择您的终结点支持的OAuth2客户端凭据授予类型:

    • 正文表单已编码:在这种情况下,client ID和client secret包含在发送到目标的请求​ 的正文中。 有关示例,请参阅支持的身份验证类型部分。
    • 基本授权:在这种情况下,client ID和client secret在经过base64编码并发送到目标之后,包含在Authorization标头​ 中的 ​中。 有关示例,请参阅支持的身份验证类型部分。

填写目标详细信息 destination-details

要配置目标的详细信息,请填写下面的必需和可选字段。 UI中字段旁边的星号表示该字段为必填字段。

显示HTTP目标详细信息已完成字段的UI屏幕图像。

  • 名称:输入将来用于识别此目标的名称。
  • 描述:输入有助于以后识别此目标的描述。
  • 标头:输入任何要包含在目标调用中的自定义标头,格式如下: header1:value1,header2:value2,...headerN:valueN
  • HTTP终结点:要将配置文件数据发送到的HTTP终结点的URL。
  • 查询参数:您可以选择将查询参数添加到HTTP终结点URL。 格式化您使用的查询参数,如下所示:parameter1=value&parameter2=value
  • 包括区段名称:如果希望数据导出包括正在导出的受众的名称,请切换。 有关选择此选项的数据导出示例,请参阅下面的导出的数据部分。
  • 包括区段时间戳:如果要在数据导出时包括创建和更新受众时的UNIX时间戳,以及在将受众映射到目标以进行激活时的UNIX时间戳,请切换此选项。 有关选择此选项的数据导出示例,请参阅下面的导出的数据部分。

启用警报 enable-alerts

您可以启用警报,以接收有关发送到目标的数据流状态的通知。 从列表中选择警报以订阅接收有关数据流状态的通知。 有关警报的详细信息,请参阅使用UI订阅目标警报的指南

完成提供目标连接的详细信息后,选择​ 下一步

激活此目标的受众 activate

IMPORTANT

有关将受众激活到此目标的说明,请参阅将受众数据激活到流式配置文件导出目标

目标属性 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目标,其中在数据流中选择了三个受众,并且四个属性映射到目标。

HTTP API目标数据流示例。

配置文件导出到目标可以由符合或退出​ 三个映射区段 ​之一的配置文件确定。 但是,在数据导出中,在segmentMembership对象(请参阅下面的导出的数据部分)中,如果该特定配置文件是其他未映射受众的成员,并且这些受众与触发导出的受众共享相同的合并策略,则可能会显示这些受众。 如果某个配置文件符合​ 具有DeLorean Cars的客户 ​区段的资格,但同时也是​ 观看的“回到未来” ​电影和​ 科幻迷 ​区段的成员,则另外这两个受众也将出现在数据导出的segmentMembership对象中,即使它们未在数据流中映射,前提是它们与​ 具有DeLorean Cars的客户 ​区段共享相同的合并策略。

从配置文件属性的角度来看,对上述四个映射属性所做的任何更改都将决定目标导出,并且配置文件中存在的四个映射属性中的任何一个都会出现在数据导出中。

历史数据回填 historical-data-backfill

在将新受众添加到现有目标时,或者创建新目标并将受众映射到该目标时,Experience Platform会将历史受众资格数据导出到该目标。 在​ 之前添加受众到目标时,符合受众 ​资格的配置文件将在大约1小时内导出到目标。

导出的数据 exported-data

导出的Experience Platform数据以JSON格式登陆到HTTP目标。 例如,以下导出包含一个符合某个区段资格条件的配置文件,该配置文件是另一个区段的成员,并且已退出另一个区段。 导出还包括配置文件属性名字、姓氏、出生日期和个人电子邮件地址。 此配置文件的身份为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": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "realized",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
            "name": "First name equals John"
          }
        }
      }
以下数据导出示例在segmentMembership部分中包含受众时间戳
code language-json
"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "realized",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
          }
        }
      }

限制和重试策略 limits-retry-policy

在95%的时间中,Experience Platform会尝试为成功发送的消息提供少于10分钟的吞吐量延迟,每个数据流向HTTP目的地的请求速率每秒少于10,000次。

如果对HTTP API目标的请求失败,Experience Platform将存储失败的请求,并重试两次以将请求发送到您的端点。

recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6