[Ultimate]{class="badge positive"}

HTTP API连接

概述 overview

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

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

用例 use-cases

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

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

支持的受众 supported-audiences

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

按受众数据类型划分的受众支持：

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

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

先决条件 prerequisites

要使用HTTP API目标将数据导出到Experience Platform中，您必须满足以下先决条件：

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

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

mTLS是一种相互认证协议，它确保共享信息的双方在共享数据之前都是他们声称的身份。 mTLS包括与标准TLS相比的附加步骤，其中服务器还请求并验证客户端的证书，而客户端验证服务器的证书。

mTLS注意事项 mtls-considerations

HTTP API目标的mTLS支持仅将​应用于发送配置文件导出的数据接收终结点（HTTP Endpoint​目标详细信息中的字段）。

配置用于数据导出的mTLS configuring-mtls

若要将mTLS与HTTP API目标一起使用，您在​ HTTP Endpoint ​目标详细信息页面中配置的 （数据接收端点）必须禁用TLS协议，并且仅启用mTLS。 如果在端点上仍然启用TLS 1.2协议，则不会发送用于客户端身份验证的证书。 这意味着要将mTLS与HTTP API目标一起使用，您的数据接收服务器端点必须是仅启用mTLS的连接端点。

检索和检查证书详细信息 certificate

如果要检查证书详细信息(如公用名(CN)和使用者备用名(SAN)以进行其他第三方验证，请使用API检索证书并从响应中提取这些字段。

有关详细信息，请参阅公共证书终结点文档。

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

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

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

HTTP API目标支持对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>'

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

如果选择​ Bearer token ​身份验证类型连接到HTTP终结点，请输入以下信息并选择​Connect to destination：

无身份验证 no-authentication

如果选择​ None ​身份验证类型连接到HTTP端点：

当您选择此身份验证选项时，您只需选择​Connect to destination，即可建立与端点的连接。

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

如果选择​ OAuth 2 Password ​身份验证类型连接到HTTP终结点，请输入以下信息并选择​Connect to destination：

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

如果选择​ OAuth 2 Client Credentials ​身份验证类型连接到HTTP终结点，请输入以下信息并选择​Connect to destination：

填写目标详细信息 destination-details

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

启用警报 enable-alerts

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

完成提供目标连接的详细信息后，选择​Next。

激活此目标的受众 activate

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

目标属性 attributes

在Select attributes步骤中，Adobe建议您从合并架构中选择唯一标识符。 选择要导出到目标的唯一标识符和任何其他XDM字段。

配置文件导出行为 profile-export-behavior

Experience Platform会优化将配置文件导出到HTTP API目标的行为，以便仅在符合受众资格或其他重要事件后对配置文件进行了相关更新时将数据导出到API端点。 在以下情况下，会将配置文件导出到您的目标：

在上述所有情况中，只会将已发生相关更新的用户档案导出到您的目标。 例如，如果映射到目标流的受众具有一百个成员，且五个新配置文件符合受众的条件，则导出到目标的操作将以增量方式进行，并且仅包括五个新配置文件。

决定数据导出的因素以及导出中包含的内容 what-determines-export-what-is-included

关于为给定配置文件导出的数据，了解​ 是什么决定了数据导出到您的HTTP API目标 ​和​ 哪些数据包含在导出中 ​这两个不同的概念很重要。

例如，考虑将此数据流映射到HTTP目标，其中在数据流中选择了三个受众，并且四个属性映射到目标。

当配置文件符合或退出​ 三个映射的受众 ​之一时，会触发配置文件导出到目标的操作。 在数据导出中，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"
      }
    ]
  }
}

下面是导出数据的更多示例，具体取决于您在连接目标流中​ Include Segment Names ​和​ Include Segment Timestamps ​选项选择的UI设置：

"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"
          },
          "354e086f-2e11-49a2-9e39-e5d9a76be683": {
            "lastQualificationTime": "2020-04-15T02:41:50+0000",
            "status": "realized"
          }
        }
      }

"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会存储这些请求并重试两次。

疑难解答 troubleshooting

要确保可靠的数据传递并避免超时问题，请确保您的HTTP端点在2秒内响应Experience Platform请求，如先决条件部分中所指定。 响应时间越长将导致超时错误。