连接到流目标并使用流服务API激活数据

Last update: Mon Jan 22 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

主题：
Destinations

创建对象：

Admin
User

IMPORTANT

要连接到目标，您需要 查看目标 和 管理目标 访问控制权限.

要激活数据，您需要 查看目标， 激活目标， 查看配置文件、和 查看区段 访问控制权限.

阅读访问控制概述或与产品管理员联系以获取所需的权限。

本教程将演示如何使用API调用连接到Adobe Experience Platform数据，创建与流云存储目标的连接(Amazon Kinesis 或 Azure事件中心)，创建到新创建目标的数据流，并将数据激活到新创建的目标。

本教程使用 Amazon Kinesis 目标，但步骤与相同 Azure Event Hubs.

概述 — 创建流目标和激活受众的步骤

如果您希望使用Platform中的用户界面连接到目标并激活数据，请参阅连接目标和将受众数据激活到流式受众导出目标教程。

快速入门

本指南要求您对 Adobe Experience Platform 的以下组件有一定了解：

Experience Data Model (XDM) System：Experience Platform用于组织客户体验数据的标准化框架。
Catalog Service： Catalog 是记录Experience Platform内数据位置和族系的系统。
沙盒：Experience Platform提供了可将单个Platform实例划分为多个单独的虚拟环境的虚拟沙箱，以帮助开发和改进数字体验应用程序。

以下部分提供了您需要了解的其他信息，以便将数据激活到Platform中的流目标。

收集所需的凭据

要完成本教程中的步骤，您应该准备好以下凭据，具体取决于要连接和激活受众的目标类型。

对象 Amazon Kinesis 连接： accessKeyId， secretKey， region 或 connectionUrl
对象 Azure Event Hubs 连接： sasKeyName， sasKey， namespace

正在读取示例 API 调用 reading-sample-api-calls

本教程提供了示例API调用来演示如何格式化请求。这些包括路径、必需的标头和格式正确的请求负载。还提供了在 API 响应中返回的示例 JSON。有关文档中用于示例API调用的惯例的信息，请参阅如何读取示例API调用在Experience Platform疑难解答指南中。

收集必需标题和可选标题的值 gather-values

要调用Platform API，您必须先完成身份验证教程. 完成身份验证教程将为所有Experience PlatformAPI调用中的每个所需标头提供值，如下所示：

授权：持有者 {ACCESS_TOKEN}
x-api-key： {API_KEY}
x-gw-ims-org-id： {ORG_ID}

Experience Platform中的资源可以隔离到特定的虚拟沙箱。在对Platform API的请求中，您可以指定将执行操作的沙盒的名称和ID。这些是可选参数。

x-sandbox-name： {SANDBOX_NAME}

NOTE

有关Experience Platform中沙箱的详细信息，请参阅沙盒概述文档.

所有包含有效负载(POST、PUT、PATCH)的请求都需要额外的媒体类型标头：

内容类型： application/json

Swagger文档 swagger-docs

在本教程中，您可以在Swagger中找到所有API调用的随附参考文档。请参阅有关Adobe I/O的流服务API文档. 我们建议您并行使用此教程和Swagger文档页面。

获取可用流目标的列表 get-the-list-of-available-streaming-destinations

目标步骤概述步骤1

第一步，您应该决定要将数据激活到的流目标。首先，请执行调用以请求可连接并激活受众的可用目标列表。向发出以下GET请求 connectionSpecs 端点返回可用目标列表：

API格式

GET /connectionSpecs

请求

curl --location --request GET 'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs' \
--header 'accept: application/json' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

响应

成功的响应包含可用目标及其唯一标识符的列表(id)。存储您计划使用的目标的值，因为后续步骤需要该值。例如，如果要连接并将受众交付到 Amazon Kinesis 或 Azure Event Hubs，在响应中查找以下代码片段：

{
    "id": "86043421-563b-46ec-8e6c-e23184711bf6",
  "name": "Amazon Kinesis",
  ...
  ...
}

{
    "id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
  "name": "Azure Event Hubs",
  ...
  ...
}

连接到您的Experience Platform数据 connect-to-your-experience-platform-data

目标步骤概述步骤2

接下来，您必须连接到Experience Platform数据，以便能够导出配置文件数据并在首选目标中激活该数据。这包含下面描述的两个子步骤。

首先，您必须执行调用以通过设置基本连接来授权对Experience Platform中数据的访问。
然后，使用基本连接ID进行另一个调用，其中创建源连接，从而建立与Experience Platform数据的连接。

授权访问Experience Platform中的数据

API格式

POST /connections

请求

curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "Base connection to Experience Platform",
            "description": "This call establishes the connection to Experience Platform data",
            "connectionSpec": {
                "id": "{CONNECTION_SPEC_ID}",
                "version": "1.0"
            }
}'

{CONNECTION_SPEC_ID}：为配置文件服务使用连接规范ID - 8a9c3494-9708-43d7-ae3f-cda01e5030e1.

响应

成功的响应包含基本连接的唯一标识符(id)。将此值存储为创建源连接时所需的值。

{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

连接到您的Experience Platform数据 connect-to-platform-data

API格式

POST /sourceConnections

请求

curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "Connecting to Profile Service",
            "description": "Optional",
            "connectionSpec": {
                "id": "{CONNECTION_SPEC_ID}",
                "version": "1.0"
            },
            "baseConnectionId": "{BASE_CONNECTION_ID}",
            "data": {
                "format": "json"
            },
            "params": {}
}'

{BASE_CONNECTION_ID}：使用您在上一步中获取的ID。
{CONNECTION_SPEC_ID}：为配置文件服务使用连接规范ID - 8a9c3494-9708-43d7-ae3f-cda01e5030e1.

响应

成功的响应将返回唯一标识符(id)作为新创建的到配置文件服务的源连接。这表示您已成功连接到Experience Platform数据。将此值存储为后续步骤中所需的值。

{
    "id": "ed48ae9b-c774-4b6e-88ae-9bc7748b6e97"
}

连接到流目标 connect-to-streaming-destination

目标步骤概述步骤3

在此步骤中，您将设置与所需流目标的连接。这包含下面描述的两个子步骤。

首先，您必须通过设置基本连接来执行调用以授权对流目标的访问。
然后，使用基本连接ID进行另一个调用，以便在其中创建目标连接，指定存储帐户中要传送导出数据的位置以及要导出的数据的格式。

授权对流目标的访问

API格式

POST /connections

请求

IMPORTANT

以下示例包含前缀为的代码注释 //. 这些注释突出显示不同的流目标必须使用不同值的位置。在使用代码片段之前，请删除注释。

curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Connection for Amazon Kinesis/ Azure Event Hubs",
    "description": "summer advertising campaign",
    "connectionSpec": {
        "id": "{_CONNECTION_SPEC_ID}",
        "version": "1.0"
    },
    "auth": {
        "specName": "{AUTHENTICATION_CREDENTIALS}",
        "params": { // use these values for Amazon Kinesis connections
            "accessKeyId": "{ACCESS_ID}",
            "secretKey": "{SECRET_KEY}",
            "region": "{REGION}"
        },
        "params": { // use these values for Azure Event Hubs connections
            "sasKeyName": "{SAS_KEY_NAME}",
            "sasKey": "{SAS_KEY}",
            "namespace": "{EVENT_HUB_NAMESPACE}"
        }
    }
}'

{CONNECTION_SPEC_ID}：使用在步骤中获得的连接规范ID 获取可用目标列表.
{AUTHENTICATION_CREDENTIALS}：填写流目标的名称： Aws Kinesis authentication credentials 或 Azure EventHub authentication credentials.
{ACCESS_ID}： 对象 Amazon Kinesis 连接。 您的Amazon Kinesis存储位置的访问ID。
{SECRET_KEY}： 对象 Amazon Kinesis 连接。 您的Amazon Kinesis存储位置的密钥。
{REGION}： 对象 Amazon Kinesis 连接。 您所在的地区 Amazon Kinesis Platform将用来流式传输您的数据的帐户。
{SAS_KEY_NAME}： 对象 Azure Event Hubs 连接。 填写您的SAS密钥名称。了解如何对进行身份验证 Azure Event Hubs 使用SAS键 Microsoft文档.
{SAS_KEY}： 对象 Azure Event Hubs 连接。 填写您的SAS密钥。了解如何对进行身份验证 Azure Event Hubs 使用SAS键 Microsoft文档.
{EVENT_HUB_NAMESPACE}： 对象 Azure Event Hubs 连接。 填写 Azure Event Hubs Platform将用来流式传输您的数据的命名空间。有关更多信息，请参阅创建事件中心命名空间在 Microsoft 文档。

响应

成功的响应包含基本连接的唯一标识符(id)。将此值存储为创建目标连接时在下一步中所需的值。

{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

指定存储位置和数据格式

API格式

POST /targetConnections

请求

IMPORTANT

以下示例包含前缀为的代码注释 //. 这些注释突出显示不同的流目标必须使用不同值的位置。在使用代码片段之前，请删除注释。

curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Amazon Kinesis/ Azure Event Hubs target connection",
    "description": "Connection to Amazon Kinesis/ Azure Event Hubs",
    "baseConnectionId": "{BASE_CONNECTION_ID}",
    "connectionSpec": {
        "id": "{CONNECTION_SPEC_ID}",
        "version": "1.0"
    },
    "data": {
        "format": "json"
    },
    "params": { // use these values for Amazon Kinesis connections
        "stream": "{NAME_OF_DATA_STREAM}",
        "region": "{REGION}"
    },
    "params": { // use these values for Azure Event Hubs connections
        "eventHubName": "{EVENT_HUB_NAME}"
    }
}'

{BASE_CONNECTION_ID}：使用您在上一步中获取的基本连接ID。
{CONNECTION_SPEC_ID}：使用您在步骤中获得的连接规范获取可用目标列表.
{NAME_OF_DATA_STREAM}： 对象 Amazon Kinesis 连接。 提供您的现有数据流的名称 Amazon Kinesis 帐户。 Platform会将数据导出到此流。
{REGION}： 对象 Amazon Kinesis 连接。 Amazon Kinesis帐户中Platform将流式传输您的数据的区域。
{EVENT_HUB_NAME}： 对象 Azure Event Hubs 连接。 填写 Azure Event Hub Platform将用来流式传输您的数据的名称。有关更多信息，请参阅创建事件中心在 Microsoft 文档。

响应

成功的响应将返回唯一标识符(id)，以获取新创建的到流目标的目标连接。在后续步骤中根据需要存储此值。

{
    "id": "12ab90c7-519c-4291-bd20-d64186b62da8"
}

创建数据流

目标步骤概述步骤4

现在，您可以使用在之前步骤中获取的ID在Experience Platform数据和要将数据激活到的目标之间创建数据流。将此步骤视为构建管道，数据稍后将通过该管道在Experience Platform和您的所需目标之间流动。

要创建数据流，请执行POST请求（如下所示），同时在有效负载中提供下面提到的值。

执行以下POST请求以创建数据流。

API格式

POST /flows

请求

curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d  '{
  "name": "Azure Event Hubs",
  "description": "Azure Event Hubs",
  "flowSpec": {
    "id": "{FLOW_SPEC_ID}",
    "version": "1.0"
  },
  "sourceConnectionIds": [
    "{SOURCE_CONNECTION_ID}"
  ],
  "targetConnectionIds": [
    "{TARGET_CONNECTION_ID}"
  ],
  "transformations": [
    {
      "name": "GeneralTransform",
      "params": {
        "profileSelectors": {
          "selectors": [

          ]
        },
        "segmentSelectors": {
          "selectors": [

          ]
        }
      }
    }
  ]
}

{FLOW_SPEC_ID}：基于配置文件的目标的流规范ID为 71471eba-b620-49e4-90fd-23f1fa0174d8. 在调用中使用此值。
{SOURCE_CONNECTION_ID}：使用在步骤中获得的源连接ID 连接到您的Experience Platform.
{TARGET_CONNECTION_ID}：使用您在步骤中获取的目标连接ID 连接到流目标.

响应

成功的响应会返回ID (id)和 etag. 记下这两个值。与在下一步中激活受众时一样。

{
    "id": "8256cfb4-17e6-432c-a469-6aedafb16cd5",
    "etag": "8256cfb4-17e6-432c-a469-6aedafb16cd5"
}

将数据激活到新目标 activate-data

目标步骤概述步骤5

创建了所有连接和数据流后，现在您可以将配置文件数据激活到流平台。在此步骤中，您可以选择将哪些受众和哪些配置文件属性发送到目标，并且您可以进行计划并将数据发送到目标。

要将受众激活到新目标，您必须执行JSONPATCH操作，类似于以下示例。您可以在一次调用中激活多个受众和配置文件属性。要了解有关JSONPATCH的更多信息，请参阅 RFC规范.

API格式

PATCH /flows

请求

curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'If-Match: "{ETAG}"' \
--data-raw '[
  {
    "op": "add",
    "path": "/transformations/0/params/segmentSelectors/selectors/-",
    "value": {
      "type": "PLATFORM_SEGMENT",
      "value": {
        "name": "Name of the audience that you are activating",
        "description": "Description of the audience that you are activating",
        "id": "{SEGMENT_ID}"
      }
    }
  },
  {
    "op": "add",
    "path": "/transformations/0/params/profileSelectors/selectors/-",
    "value": {
      "type": "JSON_PATH",
      "value": {
        "operator": "EXISTS",
        "path": "{PROFILE_ATTRIBUTE}"
      }
    }
  }
]

属性

描述

{DATAFLOW_ID}

在URL中，使用您在上一步中创建的数据流的ID。

{ETAG}

获取 {ETAG} 根据上一步的响应，创建数据流. 上一步中的响应格式对引号进行了转义。您必须在请求的标头中使用未转义值。请参阅以下示例：

响应示例： "etag":""7400453a-0000-1a00-0000-62b1c7a90000""
要在请求中使用的值： "etag": "7400453a-0000-1a00-0000-62b1c7a90000"

每次成功更新数据流时，etag值都会更新。

{SEGMENT_ID}

提供要导出到此目标的受众ID。要检索要激活的受众的受众ID，请参阅检索受众定义 (在Experience PlatformAPI参考中)。

{PROFILE_ATTRIBUTE}

例如："person.lastName"

op

操作调用，用于定义更新数据流所需的操作。操作包括： add， replace、和 remove. 要将受众添加到数据流，请使用 add 操作。

path

定义要更新的流部分。将受众添加到数据流时，请使用示例中指定的路径。

value

要用于更新参数的新值。

id

指定要添加到目标数据流的受众的ID。

name

可选. 指定要添加到目标数据流的受众的名称。请注意，此字段不是必填字段，您无需提供名称即可将受众成功添加到目标数据流。

响应

查找“202 OK（202确定）”响应。未返回响应正文。要验证请求是否正确，请参阅下一步验证数据流。

验证数据流

目标步骤概述步骤6

作为本教程的最后一步，您应该验证受众和配置文件属性是否确实已正确映射到数据流。

要验证这一点，请执行以下GET请求：

API格式

GET /flows

请求

curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: prod' \
--header 'If-Match: "{ETAG}"'

{DATAFLOW_ID}：使用上一步的数据流。
{ETAG}：使用上一步骤中的电子标记。

响应

返回的响应应包含在 transformations 参数在上一步中提交的受众和配置文件属性。示例 transformations 响应中的参数可能如下所示：

"transformations": [
    {
        "name": "GeneralTransform",
        "params": {
            "profileSelectors": {
                        "selectors": [
                            {
                                "type": "JSON_PATH",
                                "value": {
                                    "path": "personalEmail.address",
                                    "operator": "EXISTS"
                                }
                            },
                            {
                                "type": "JSON_PATH",
                                "value": {
                                    "path": "person.lastname",
                                    "operator": "EXISTS"
                                }
                            }
                        ]
                    },
            "segmentSelectors": {
                "selectors": [
                    {
                        "type": "PLATFORM_SEGMENT",
                        "value": {
                            "name": "Men over 50",
                            "description": "",
                            "id": "72ddd79b-6b0a-4e97-a8d2-112ccd81bd02"
                        }
                    }
                ]
            }
        }
    }
],

导出的数据

IMPORTANT

除了配置文件属性和步骤中的受众之外，将数据激活到新目标，中的导出数据 AWS Kinesis 和 Azure Event Hubs 还将包含有关身份映射的信息。这表示导出的配置文件的标识(例如 ECID、移动设备ID、Google ID、电子邮件地址等)。请参阅以下示例。

{
  "person": {
    "email": "yourstruly@adobe.com"
  },
  "segmentMembership": {
    "ups": {
      "72ddd79b-6b0a-4e97-a8d2-112ccd81bd02": {
        "lastQualificationTime": "2020-03-03T21:24:39Z",
        "status": "exited"
      },
      "7841ba61-23c1-4bb3-a495-00d695fe1e93": {
        "lastQualificationTime": "2020-03-04T23:37:33Z",
        "status": "realized"
      }
    }
  },
  "identityMap": {
    "ecid": [
      {
        "id": "14575006536349286404619648085736425115"
      },
      {
        "id": "66478888669296734530114754794777368480"
      }
    ],
    "email_lc_sha256": [
      {
        "id": "655332b5fa2aea4498bf7a290cff017cb4"
      },
      {
        "id": "66baf76ef9de8b42df8903f00e0e3dc0b7"
      }
    ]
  }
}

使用 Postman 收藏集以连接到流目标 collections

要以更简化的方式连接到本教程中描述的流目标，您可以使用 Postman.

Postman 是一个可用于进行API调用和管理预定义调用和环境的库的工具。

对于本特定教程，请完成以下操作 Postman 已附加收藏集：

AWS Kinesis Postman 收藏集
Azure Event Hubs Postman 收藏集

单击此处以下载收藏集存档。

每个收藏集都包含必要的请求和环境变量，例如 AWS Kinesis、和 Azure Event Hub、ID名称和ID名称等。

如何使用 Postman 收藏集 how-to-use-postman-collections

要使用连接的成功连接到目标，请执行以下操作： Postman 收藏集，请执行以下步骤：

下载并安装 Postman；
下载并解压缩附加的收藏集；
将收藏集从相应的文件夹导入到 Postman；
按照本文中的说明填写环境变量；
运行 API 请求自 Postman，根据本文中的说明。

API错误处理 api-error-handling

本教程中的API端点遵循常规Experience PlatformAPI错误消息原则。请参阅 API状态代码和请求标头错误有关解释错误响应的更多信息，请参阅平台故障排除指南。

后续步骤 next-steps

通过学习本教程，您已成功将Platform连接到其中一个首选流式传输目标，并设置了到相应目标的数据流。传出数据现在可用于客户分析的目标或您希望执行的任何其他数据操作。有关更多详细信息，请参阅以下页面：

recommendation-more-help

7f4d1967-bf93-4dba-9789-bb6b505339d6