文档Experience Platform源连接器指南

[Beta 版]{class="badge informative"}

使用流服务API为Customer.io创建源连接和数据流

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主题：

创建对象：

  • 开发人员
NOTE
Customer.io源为测试版。 有关使用测试版标记源的更多信息，请参阅源概述。

以下教程将指导您完成创建Customer.io源连接和数据流的步骤，以便使用Flow Service API将Customer.io事件数据引入Adobe Experience Platform。

快速入门 getting-started

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

  • 源：Experience Platform允许从各种源摄取数据，同时允许您使用Platform服务来构建、标记和增强传入数据。
  • 沙盒：Experience Platform提供了将单个Platform实例划分为多个单独的虚拟环境的虚拟沙盒，以帮助开发和改进数字体验应用程序。

使用Flow Service API将Customer.io连接到平台 connect-platform-to-flow-api

下面概述了创建源连接和数据流以Experience PlatformCustomer.io事件数据所需执行的步骤。

创建源连接 source-connection

创建源连接，方法是：向Flow Service API发出POST请求，同时提供源的连接规范ID、名称和描述等详细信息以及数据的格式。

API格式

POST /sourceConnections

请求

以下请求为Customer.io创建源连接：

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
  -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": "Streaming Source Connection for Customer.io",
      "providerId": "521eee4d-8cbe-4906-bb48-fb6bd4450033",
      "description": "Streaming Source Connection for customer.io",
      "connectionSpec": {
          "id": "96479064-7b8a-4d69-b9ed-21c5683837ea",
          "version": "1.0"
      },
      "data": {
          "format": "json"
      }
    }'
属性
描述
name
源连接的名称。 请确保源连接的名称是描述性的，因为您可以使用此名称查找有关源连接的信息。
description
可包含的可选值，用于提供有关源连接的更多信息。
connectionSpec.id
与源对应的连接规范ID。
data.format
要摄取的Customer.io数据的格式。 当前，唯一支持的数据格式为json。

响应

成功的响应返回新创建的源连接的唯一标识符(id)。 此ID是稍后步骤创建数据流所必需的。

{
    "id": "133bb51f-f310-4b4a-b8b2-731aef1e223c",
    "etag": "\"af00a717-0000-0200-0000-63ef2cbd0000\""
}

创建目标XDM架构 target-schema

为了在Platform中使用源数据，必须创建目标架构，以根据您的需求构建源数据。 然后，使用目标架构创建包含源数据的Platform数据集。

通过向架构注册表API执行POST请求，可以创建目标XDM架构。

有关如何创建目标XDM架构的详细步骤，请参阅有关使用API 创建架构的教程。

创建目标数据集 target-dataset

可以通过向目录服务API执行POST请求，在有效负载中提供目标架构的ID来创建目标数据集。

有关如何创建目标数据集的详细步骤，请参阅有关使用API创建数据集的教程。

创建目标连接 target-connection

目标连接表示与要存储所摄取数据的目标的连接。 要创建目标连接，您必须提供对应于数据湖的固定连接规范ID。 此ID为： c604ff05-7f1a-43c0-8e18-33bf874cb11c。

现在，您拥有目标架构、目标数据集以及到数据湖的连接规范ID。 使用这些标识符，您可以使用Flow Service API创建目标连接，以指定将包含入站源数据的数据集。

API格式

POST /targetConnections

请求

以下请求为Customer.io创建目标连接：

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
  -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": "Streaming Target Connection for Customer.io",
      "description": "Streaming Target Connection for Customer.io",
      "connectionSpec": {
          "id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
          "version": "1.0"
      },
      "data": {
          "format": "json",
          "schema": {
              "id": "https://ns.adobe.com/extconndev/schemas/945546112b746524bfd9f1264b26c2b7d8e7f5b7fadb953a",
              "version": "application/vnd.adobe.xed-full+json;version=1"
          }
      },
      "params": {
          "dataSetId": "63ec807d3f5ce91bd2d06c65"
      }
  }'
属性
描述
name
目标连接的名称。 确保目标连接的名称是描述性的，因为您可以使用此名称查找有关目标连接的信息。
description
可包含的可选值，用于提供有关目标连接的更多信息。
connectionSpec.id
对应于数据湖的连接规范ID。 此固定ID为： c604ff05-7f1a-43c0-8e18-33bf874cb11c。
data.format
要摄取的Customer.io数据的格式。
params.dataSetId
在上一步中检索到的目标数据集ID。

响应

成功的响应返回新目标连接的唯一标识符(id)。 此ID在后续步骤中是必需的。

{
    "id": "da8b75ad-f6ee-4991-95df-291e62936e98",
    "etag": "\"70003dff-0000-0200-0000-63ef4a090000\""
}

创建映射 mapping

要将源数据摄取到目标数据集中，必须首先将其映射到目标数据集所遵循的目标架构。 这是通过向Data Prep API执行POST请求来实现的，该请求具有在请求有效负载中定义的数据映射。

API格式

POST /conversion/mappingSets

请求

curl -X POST \
  'https://platform.adobe.io/data/foundation/conversion/mappingSets' \
  -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 '{
      "outputSchema": {
          "schemaRef": {
              "id": "https://ns.adobe.com/{TENANT_ID}/schemas/945546112b746524bfd9f1264b26c2b7d8e7f5b7fadb953a",
              "contentType": "application/vnd.adobe.xed-full+json;version=1"
          }
      },
    "mappings": [
        {
            "destinationXdmPath": "_extconndev.cio_id",
            "sourceAttribute": "data.identifiers.cio_id",
            "identity": false,
            "version": 0
        },
        {
            "destinationXdmPath": "_extconndev.email",
            "sourceAttribute": "data.identifiers.email",
            "identity": false,
            "version": 0
        },
        {
            "destinationXdmPath": "_extconndev.event_id0",
            "sourceAttribute": "event_id",
            "identity": false,
            "version": 0
        },
        {
            "destinationXdmPath": "_extconndev.metricx",
            "sourceAttribute": "metric",
            "identity": false,
            "version": 0
        },
        {
            "destinationXdmPath": "_extconndev.object_type1",
            "sourceAttribute": "object_type",
            "identity": false,
            "version": 0
        },
        {
            "destinationXdmPath": "_extconndev.timestampx",
            "sourceAttribute": "timestamp",
            "identity": false,
            "version": 0
        }
    ]
  }'
属性
描述
outputSchema.schemaRef.id
在之前的步骤中生成的目标XDM架构的ID。
mappings.sourceType
正在映射的源属性类型。
mappings.source
需要映射到目标XDM路径的源属性。
mappings.destination
源属性将映射到的目标XDM路径。

响应

成功的响应返回新创建的映射的详细信息，包括其唯一标识符(id)。 在后续步骤中需要使用此值来创建数据流。

{
    "id": "59c0e53a2dc84f7791ecc1b3d6e51d5e",
    "version": 0,
    "createdDate": 1676627988129,
    "modifiedDate": 1676627988129,
    "createdBy": "{CREATED_BY}",
    "modifiedBy": "{MODIFIED_BY}"
}

创建流 flow

将数据从Customer.io引入到Platform的最后一步是创建数据流。 现在，您已准备以下必需值：

数据流负责从源中计划和收集数据。 您可以通过在有效负载中提供上述值时执行POST请求来创建数据流。

API格式

POST /flows

请求

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/flows' \
  -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": "Streaming Dataflow for Customer.io",
      "description": "Streaming Dataflow for Customer.io",
      "flowSpec": {
          "id": "e77fde5a-22a8-11ed-861d-0242ac120002",
          "version": "1.0"
      },
      "sourceConnectionIds": [
          "133bb51f-f310-4b4a-b8b2-731aef1e223c"
      ],
      "targetConnectionIds": [
          "da8b75ad-f6ee-4991-95df-291e62936e98"
      ],
      "transformations": [
      {
        "name": "Mapping",
        "params": {
          "mappingId": "59c0e53a2dc84f7791ecc1b3d6e51d5e",
          "mappingVersion": 0
        }
      }
    ]
  }'
属性
描述
name
您的数据流的名称。 确保数据流的名称是描述性的，因为您可以使用此名称查找数据流上的信息。
description
可包含的可选值，用于提供有关数据流的更多信息。
flowSpec.id
创建数据流所需的流规范ID。 此固定ID为： e77fde5a-22a8-11ed-861d-0242ac120002。
flowSpec.version
流规范ID的相应版本。 此值默认为1.0。
sourceConnectionIds
在之前的步骤中生成的源连接ID。
targetConnectionIds
在之前的步骤中生成的目标连接ID。
transformations
此属性包含需要应用于数据的各种转换。 将不符合XDM的数据引入到Platform时需要此属性。
transformations.name
分配给转换的名称。
transformations.params.mappingId
在之前的步骤中生成的映射ID。
transformations.params.mappingVersion
映射ID的相应版本。 此值默认为0。

响应

成功的响应返回新创建的数据流的ID (id)。 您可以使用此ID监视、更新或删除数据流。

{
    "id": "4982698b-e6b3-48c2-8dcf-040e20121fd2",
    "etag": "\"4c012103-0000-0200-0000-63ef57db0000\""
}

获取您的流端点URL get-streaming-endpoint-url

创建数据流后，您现在可以检索流端点URL。 您将使用此端点URL将源订阅到webhook，从而允许源与Experience Platform通信。

要检索您的流端点URL，请向/flows端点发出GET请求并提供您的数据流的ID。

API格式

GET /flows/{FLOW_ID}

请求

curl -X GET \
  'https://platform.adobe.io/data/foundation/flowservice/flows/4982698b-e6b3-48c2-8dcf-040e20121fd2' \
  -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}'

响应

成功的响应返回有关数据流的信息，包括标记为inletUrl的终结点URL。 请参阅设置Webhook页面以获取所需的值。

{
    "items": [
        {
            "id": "4982698b-e6b3-48c2-8dcf-040e20121fd2",
            "createdAt": 1676629979503,
            "updatedAt": 1676629985390,
            "createdBy": "acme@AdobeID",
            "updatedBy": "acme@AdobeID",
            "createdClient": "{CREATED_CLIENT}",
            "updatedClient": "{UPDATED_CLIENT}",
            "sandboxId": "{SANDBOX_ID}",
            "sandboxName": "{SANDBOX_NAME}",
            "imsOrgId": "{ORG_ID}",
            "name": "Streaming Dataflow for Customer.io",
            "description": "Streaming Dataflow for Customer.io",
            "flowSpec": {
                "id": "e77fde5a-22a8-11ed-861d-0242ac120002",
                "version": "1.0"
            },
            "state": "enabled",
            "version": "\"4c01c003-0000-0200-0000-63ef57e10000\"",
            "etag": "\"4c01c003-0000-0200-0000-63ef57e10000\"",
            "sourceConnectionIds": [
                "133bb51f-f310-4b4a-b8b2-731aef1e223c"
            ],
            "targetConnectionIds": [
                "da8b75ad-f6ee-4991-95df-291e62936e98"
            ],
            "inheritedAttributes": {
                "properties": {
                    "isSourceFlow": true
                },
                "sourceConnections": [
                    {
                        "id": "133bb51f-f310-4b4a-b8b2-731aef1e223c",
                        "connectionSpec": {
                            "id": "96479064-7b8a-4d69-b9ed-21c5683837ea",
                            "version": "1.0"
                        }
                    }
                ],
                "targetConnections": [
                    {
                        "id": "da8b75ad-f6ee-4991-95df-291e62936e98",
                        "connectionSpec": {
                            "id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
                            "version": "1.0"
                        }
                    }
                ]
            },
            "options": {
                "inletUrl": "https://dcs.adobedc.net/collection/e75dcb5247eb65e7385df30270192e80b145566f52ed74d570505bd2e82463f3"
            },
            "transformations": [
                {
                    "name": "Mapping",
                    "params": {
                        "mappingId": "59c0e53a2dc84f7791ecc1b3d6e51d5e",
                        "mappingVersion": 0
                    }
                }
            ],
            "runs": "/runs?property=flowId==4982698b-e6b3-48c2-8dcf-040e20121fd2",
            "providerRefId": "c4726e6f-64b4-4b3b-97e3-f128ace0cc74",
            "lastOperation": {
                "started": 0,
                "updated": 0,
                "operation": "enable"
            }
        }
    ]
}

附录 appendix

以下部分提供了有关监视、更新和删除数据流的步骤的信息。

监测数据流 monitor-dataflow

创建数据流后，您可以监视通过它摄取的数据，以查看有关流运行、完成状态和错误的信息。 有关完整的API示例，请阅读有关使用API监视源数据流的指南。

更新您的数据流 update-dataflow

通过提供数据流的ID，向Flow Service API的/flows端点发出PATCH请求，更新数据流的详细信息，例如其名称和描述，以及其运行计划和关联的映射集。 发出PATCH请求时，必须在If-Match标头中提供数据流唯一的etag。 有关完整的API示例，请阅读有关使用API 更新源数据流的指南

更新您的帐户 update-account

在提供您的基本连接ID作为查询参数的同时，通过执行对Flow Service API的PATCH请求来更新源帐户的名称、描述和凭据。 发出PATCH请求时，必须在If-Match标头中提供源帐户的唯一etag。 有关完整的API示例，请阅读有关使用API更新源帐户的指南。

删除您的数据流 delete-dataflow

在查询参数中提供要删除的数据流的ID时，通过向Flow Service API执行DELETE请求来删除数据流。 有关完整的API示例，请阅读有关使用API删除数据流的指南。

删除您的帐户 delete-account

在提供要删除的帐户的基本连接ID时，通过向Flow Service API执行DELETE请求来删除您的帐户。 有关完整的API示例，请阅读有关使用API🔗删除源帐户的指南。

recommendation-more-help
337b99bb-92fb-42ae-b6b7-c7042161d089