使用Flow Service API为营销自动化源创建数据流
本教程介绍了从营销自动化源检索数据以及使用Flow Service API将数据引入Experience Platform的步骤。
NOTE
- 要创建数据流，您必须已具有有效的具有营销自动化源的基本连接ID。 如果您没有此ID，请参阅源概述，以查看可创建基本连接的营销自动化源的列表。
- 要让Experience Platform摄取数据，必须将所有基于表的批处理源的时区配置为UTC时区。
快速入门
本教程还要求您实际了解Adobe Experience Platform的以下组件：
-
Experience Data Model (XDM) System： Experience Platform用于组织客户体验数据的标准化框架。
- 架构组合的基础知识：了解XDM架构的基本构建块，包括架构组合中的关键原则和最佳实践。
- 架构注册表开发人员指南：包含成功执行对架构注册表API的调用所需了解的重要信息。 这包括您的
{TENANT_ID}、“容器”的概念以及发出请求所需的标头（请特别注意“接受”标头及其可能的值）。
-
Catalog Service：目录是Experience Platform中数据位置和谱系的记录系统。
-
Batch ingestion：批量摄取API允许您将数据作为批处理文件摄取到Experience Platform中。
-
沙盒： Experience Platform提供了将单个Experience Platform实例划分为多个单独的虚拟环境的虚拟沙盒，以帮助开发和改进数字体验应用程序。
使用Experience Platform API
有关如何成功调用Experience Platform API的信息，请参阅Experience Platform API快速入门指南。
创建源连接 source
您可以通过向Flow Service API发出POST请求来创建源连接。 源连接由连接ID、源数据文件的路径以及连接规范ID组成。
要创建源连接，还必须为数据格式属性定义一个枚举值。
为基于文件的连接器使用以下枚举值：
数据格式
枚举值
已分隔
delimitedJSON
jsonParquet
parquet对于所有基于表的连接器，将该值设置为tabular。
API格式
POST /sourceConnections
请求
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": "HubSpot source connection",
"baseConnectionId": "c6d4ee17-6752-4e83-94ee-1767522e83fa",
"description": "HubSpot source connection",
"data": {
"format": "tabular",
},
"params": {
"path": "Hubspot.Contacts"
},
"connectionSpec": {
"id": "cc6a4487-9e91-433e-a3a3-9cf6626c1806",
"version": "1.0"
}
}'
属性
描述
baseConnectionId您正在访问的第三方营销自动化系统的唯一连接ID。
params.path您正在访问的源文件的路径。
connectionSpec.id营销自动化系统的连接规范ID。
响应
成功的响应返回新创建的源连接的唯一标识符(id)。 将此值存储为以后创建目标连接步骤中所需的值。
{
"id": "f44dbef2-a4f0-4978-8dbe-f2a4f0e978cf",
"etag": "\"5f00fba7-0000-0200-0000-5ed560520000\""
}
创建目标XDM架构 target-schema
为了在Experience Platform中使用源数据，必须创建目标架构，以根据您的需求构建源数据。 然后，使用目标架构创建包含源数据的Experience 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
请求
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": "HubSpot target connection",
"description": "HubSpot target connection",
"data": {
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/da411446eec78026c28d9fafd9e406e304b771d55b07b91b",
"version": "application/vnd.adobe.xed-full+json;version=1"
}
},
"params": {
"dataSetId": "5ed5639d798a22191b6987b2"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
属性
描述
data.schema.id目标XDM架构的
$id。data.schema.version架构的版本。 此值必须设置为
application/vnd.adobe.xed-full+json;version=1，这将返回架构的最新次版本。params.dataSetId上一步中生成的目标数据集的ID。 注意：创建目标连接时，必须提供有效的数据集ID。 无效的数据集ID将导致错误。
connectionSpec.id用于连接到数据湖的连接规范ID。 此ID为：
c604ff05-7f1a-43c0-8e18-33bf874cb11c。{
"id": "4b3d05d8-b7aa-40de-bd05-d8b7aa80de65",
"etag": "\"dd00a1a2-0000-0200-0000-5ed564850000\""
}
创建映射 mapping
要将源数据摄取到目标数据集中，必须首先将其映射到目标数据集所遵循的目标架构。
要创建映射集，请在提供目标XDM架构mappingSets和要创建的映射集的详细信息时，向Data Prep API的$id端点发出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 '{
"version": 0,
"xdmSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/da411446eec78026c28d9fafd9e406e304b771d55b07b91b",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "_id",
"sourceAttribute": "Vid",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.firstName",
"sourceAttribute": "Properties_Firstname_Value",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "_repo.createDate",
"sourceAttribute": "Added_At",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
}
]
}'
属性
描述
xdmSchema目标XDM架构的ID。
响应
成功的响应返回新创建的映射的详细信息，包括其唯一标识符(id)。 将此值存储为创建数据流时在上一步骤中所需的值。
{
"id": "500a9b747fcf4908a21917d49bd61780",
"version": 0,
"createdDate": 1591043336298,
"modifiedDate": 1591043336298,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
查找数据流规范 specs
数据流负责从源收集数据并将这些数据引入Experience Platform。 要创建数据流，您必须首先获取负责收集营销自动化数据的数据流规范。
API格式
GET /flowSpecs?property=name=="CRMToAEP"
请求
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/flowSpecs?property=name==%22CRMToAEP%22' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
响应
成功的响应将返回数据流规范的详细信息，该规范负责将数据从源引入Experience Platform。 响应包括创建新数据流所需的唯一流规范id。
NOTE
为简单起见，以下JSON响应有效负载已隐藏。 选择“payload”（有效负载）可查看响应有效负载。
查看有效负荷
| code language-json |
|---|
|
创建数据流
收集营销自动化数据的最后一步是创建数据流。 现在，您已准备以下必需值：
数据流负责从源中计划和收集数据。 您可以通过在有效负载中提供前面提到的值时执行POST请求来创建数据流。
要计划摄取，您必须先将开始时间值设置为纪元时间（以秒为单位）。 然后，必须将频率值设置为五个选项之一： once、minute、hour、day或week。 间隔值用于指定两次连续摄取之间的时间段，创建一次性摄取不需要设置间隔。 对于所有其他频率，间隔值必须设置为等于或大于15。
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": "HubSpot dataflow",
"description": "collecting Hubspot.Contacts",
"flowSpec": {
"id": "14518937-270c-4525-bdec-c2ba7cce3860",
"version": "1.0"
},
"sourceConnectionIds": [
"f44dbef2-a4f0-4978-8dbe-f2a4f0e978cf"
],
"targetConnectionIds": [
"4b3d05d8-b7aa-40de-bd05-d8b7aa80de65"
],
"transformations": [
{
"name": "Copy",
"params": {
"deltaColumn": {
"name": "updatedAt",
"dateFormat": "YYYY-MM-DD",
"timezone": "UTC"
}
}
},
{
"name": "Mapping",
"params": {
"mappingId": "500a9b747fcf4908a21917d49bd61780",
"mappingVersion": 0
}
}
],
"scheduleParams": {
"startTime": "1591043454",
"frequency":"once",
"interval":"15"
}
}'
属性
描述
flowSpec.id在上一步中检索到流规范ID。
sourceConnectionIds在之前的步骤中检索到源连接ID。
targetConnectionIds在之前的步骤中检索到目标连接ID。
transformations.params.mappingId在之前的步骤中检索到映射ID。
transformations.params.deltaColum用于区分新数据和现有数据的指定列。 将根据选定列的时间戳摄取增量数据。
deltaColumn支持的日期格式为yyyy-MM-dd HH:mm:ss。transformations.params.mappingId与数据库关联的映射ID。
scheduleParams.startTime以纪元时间表示的数据流开始时间。
scheduleParams.frequency数据流收集数据的频率。 可接受的值包括：
once、minute、hour、day或week。scheduleParams.interval间隔指定两次连续流运行之间的周期。 间隔的值应为非零整数。 每个频率的最小接受间隔值如下：
- 一次：不适用
- 分钟： 15
- 小时： 1
- 天： 1
- 周： 1
响应
成功的响应返回新创建的数据流的ID (id)。
{
"id": "e0bd8463-0913-4ca1-bd84-6309134ca1f6",
"etag": "\"04004fe9-0000-0200-0000-5ebc4c8b0000\""
}
监测数据流
创建数据流后，您可以监视通过它摄取的数据，以查看有关流运行、完成状态和错误的信息。 有关如何监视数据流的详细信息，请参阅有关API中监视数据流的教程
后续步骤
在本教程之后，您已创建一个源连接器，以按计划从营销自动化系统中收集数据。 传入数据现在可供下游Experience Platform服务（如Real-Time Customer Profile和Data Science Workspace）使用。 有关更多详细信息，请参阅以下文档：
recommendation-more-help
337b99bb-92fb-42ae-b6b7-c7042161d089