创建 YOURSOURCE 连接使用 Flow Service API
浏览此模板时,替换或删除所有斜体段落(从此段落开始)。
首先,在页面顶部更新元数据(标题和描述)。 请忽略此页面上的所有DNL实例。 此标记可帮助我们的机器翻译流程将页面正确翻译为我们支持的多种语言。 我们会在您提交文档后向文档中添加标记。
概述
提供贵公司的简短概述,包括贵公司为客户提供的价值。 添加指向产品文档主页的链接以供进一步阅读。
先决条件
在此部分中添加有关客户在Adobe Experience Platform用户界面中开始设置源之前需要了解的任何信息。 这可能是:
- 需要添加到允许列表
- 电子邮件哈希处理的要求
- 您这边的任何帐户详情
- 如何获取API密钥以连接到您的平台
收集所需的凭据
为了连接 YOURSOURCE 要Experience Platform,必须提供以下连接属性的值:
有关这些凭据的详细信息,请参阅 YOURSOURCE 身份验证文档。 请在此处添加指向您的平台身份验证文档的链接.
连接 YOURSOURCE 到平台,使用 Flow Service API
以下教程将指导您完成创建 YOURSOURCE 源连接并创建数据流以引入 YOURSOURCE 使用将数据发送到Platform Flow Service API.
创建基本连接 base-connection
基本连接会保留您的源和平台之间的信息,包括源的身份验证凭据、连接的当前状态以及唯一的基本连接ID。 基本连接ID允许您浏览和浏览源中的文件,并标识要摄取的特定项目,包括有关其数据类型和格式的信息。
POST要创建基本连接ID,请向 /connections
端点,同时提供 YOURSOURCE 作为请求正文一部分的身份验证凭据。
API格式
POST /connections
请求
以下请求为创建基本连接 YOURSOURCE:
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/connections' \
-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": "{YOURSOURCE} base connection",
"description": "{YOURSOURCE} base connection to authenticate to Platform",
"connectionSpec": {
"id": "6360f136-5980-4111-8bdf-15d29eab3b5a",
"version": "1.0"
},
"auth": {
"specName": "OAuth generic-rest-connector",
"params": {
"accessToken": "{ACCESS_TOKEN}",
"refreshToken": "{REFRESH_TOKEN}",
"expirationDate": "{EXPIRATION_DATE}"
}
}
}'
name
description
connectionSpec.id
auth.specName
auth.params.
响应
成功的响应会返回新创建的基本连接,包括其唯一连接标识符(id
)。 在下一步中浏览源的文件结构和内容时,需要此ID。
{
"id": "70383d02-2777-4be7-a309-9dd6eea1b46d",
"etag": "\"d64c8298-add4-4667-9a49-28195b2e2a84\""
}
浏览您的源 explore
使用在上一步中生成的基本连接ID,可以通过执行GET请求来浏览文件和目录。
使用以下调用查找要导入的文件的路径 Platform:
API格式
GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&sourceParams={SOURCE_PARAMS}
执行GET请求以浏览源的文件结构和内容时,必须包括下表列出的查询参数:
{BASE_CONNECTION_ID}
objectType=rest
rest
.{OBJECT}
fileType=json
json
是唯一支持的文件类型。{PREVIEW}
{SOURCE_PARAMS}
{SOURCE_PARAMS}
,则必须对整个 list_id
base64中的字符串。 在以下示例中, "list_id": "10c097ca71"
以base64编码等于 eyJsaXN0SWQiOiIxMGMwOTdjYTcxIn0=
.请求
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/connections/70383d02-2777-4be7-a309-9dd6eea1b46d/explore?objectType=rest&object=json&fileType=json&preview=true&sourceParams=eyJsaXN0SWQiOiIxMGMwOTdjYTcxIn0=' \
-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}'
响应
成功的响应将返回查询文件的结构。
{
"data": [
{
"members": [
{
"id": "cff65fb4c5f5828666ad846443720efd",
"email_address": "roykent@gmail.com",
"unique_email_id": "72c758cbf1",
"full_name": "Roy Kent",
"web_id": 547094062,
"email_type": "html",
"status": "subscribed",
"merge_fields": {
"FNAME": "Roy",
"LNAME": "Kent",
"ADDRESS": {
"addr1": "",
"addr2": "",
"city": "Richmond",
"state": "Virginia",
"zip": "",
"country": "US"
},
"PHONE": "",
"BIRTHDAY": ""
},
"stats": {
"avg_open_rate": 0,
"avg_click_rate": 0
},
"ip_signup": "",
"timestamp_signup": "",
"ip_opt": "103.43.112.97",
"timestamp_opt": "2021-06-01T15:31:36+00:00",
"member_rating": 2,
"last_changed": "2021-06-01T15:31:36+00:00",
"language": "",
"vip": false,
"email_client": "",
"location": {
"latitude": 0,
"longitude": 0,
"gmtoff": 0,
"dstoff": 0,
"country_code": "",
"timezone": ""
},
"source": "Admin Add",
"tags_count": 0,
"tags": [
],
"list_id": "10c097ca71"
}
],
"list_id": "10c097ca71",
"total_items": 2,
"_links": [
{
"rel": "self",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members",
"method": "GET",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/CollectionResponse.json",
"schema": "https://us6.api.mailchimp.com/schema/3.0/Paths/Lists/Members/Collection.json"
},
{
"rel": "parent",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71",
"method": "GET",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json"
},
{
"rel": "create",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members",
"method": "POST",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json",
"schema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/POST.json"
}
]
}
]
}
创建源连接 source-connection
您可以通过向以下对象发出POST请求来创建源连接: Flow Service API。 源连接由连接ID、源数据文件的路径以及连接规范ID组成。
API格式
POST /sourceConnections
请求
以下请求为创建源连接 YOURSOURCE:
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": "{YOURSOURCE} Source Connection",
"description": "{YOURSOURCE} Source Connection",
"baseConnectionId": "70383d02-2777-4be7-a309-9dd6eea1b46d",
"connectionSpec": {
"id": "6360f136-5980-4111-8bdf-15d29eab3b5a",
"version": "1.0"
},
"data": {
"format": "json"
},
"params": {
"server": "us6",
"listId": "10c097ca71"
}
}'
name
description
baseConnectionId
connectionSpec.id
data.format
json
.响应
成功的响应将返回唯一标识符(id
)。 此ID是稍后步骤创建数据流所必需的。
{
"id": "246d052c-da4a-494a-937f-a0d17b1c6cf5",
"etag": "\"712a8c08-fda7-41c2-984b-187f823293d8\""
}
创建目标XDM架构 target-schema
为了在Platform中使用源数据,必须创建目标架构,以根据您的需求构建源数据。 然后,使用目标架构创建包含源数据的Platform数据集。
可以通过向以下对象执行POST请求来创建目标XDM架构 架构注册表API.
有关如何创建目标XDM架构的详细步骤,请参阅关于的教程 使用API创建架构.
创建目标数据集 target-dataset
可以通过向执行POST请求来创建目标数据集 目录服务API,在有效负载中提供目标架构的ID。
有关如何创建目标数据集的详细步骤,请参阅关于的教程 使用API创建数据集.
创建目标连接 target-connection
目标连接表示与要存储所摄取数据的目标的连接。 要创建目标连接,您必须提供与 Data Lake. 此ID为: c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
现在,您拥有目标架构、目标数据集和到以下对象的连接规范ID Data Lake. 使用这些标识符,您可以使用 Flow Service 用于指定将包含入站源数据的数据集的API。
API格式
POST /targetConnections
请求
以下请求创建目标连接 YOURSOURCE:
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": "{YOURSOURCE} Target Connection",
"description": "{YOURSOURCE} Target Connection",
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
},
"data": {
"format": "json"
},
"params": {
"dataSetId": "5ef4551c52e054191a61a99f"
}
}'
name
description
connectionSpec.id
c604ff05-7f1a-43c0-8e18-33bf874cb11c
.data.format
params.dataSetId
响应
成功的响应将返回新目标连接的唯一标识符(id
)。 此ID在后续步骤中是必需的。
{
"id": "7c96c827-3ffd-460c-a573-e9558f72f263",
"etag": "\"a196f685-f5e8-4c4c-bfbd-136141bb0c6d\""
}
创建映射 mapping
要将源数据摄取到目标数据集中,必须首先将其映射到目标数据集所遵循的目标架构。 这可以通过向以下对象执行POST请求来实现 Data Prep API 请求有效负载中定义的数据映射。
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/995dabbea86d58e346ff91bd8aa741a9f36f29b1019138d4",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "_id",
"sourceAttribute": "Id",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.firstName",
"sourceAttribute": "FirstName",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.lastName",
"sourceAttribute": "LastName",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
}
]
}'
xdmSchema
mappings.destinationXdmPath
mappings.sourceAttribute
mappings.identity
响应
成功响应将返回新创建映射的详细信息,包括其唯一标识符(id
)。 在后续步骤中需要使用此值来创建数据流。
{
"id": "bf5286a9c1ad4266baca76ba3adc9366",
"version": 0,
"createdDate": 1597784069368,
"modifiedDate": 1597784069368,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
创建流 flow
从以下来源获取数据的最后一步 YOURSOURCE 到Platform就是创建数据流。 现在,您已准备以下必需值:
数据流负责从源中计划和收集数据。 您可以通过在有效负载中提供上述值时执行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": "{YOURSOURCE} dataflow",
"description": "{YOURSOURCE} dataflow",
"flowSpec": {
"id": "6499120c-0b15-42dc-936e-847ea3c24d72",
"version": "1.0"
},
"sourceConnectionIds": [
"246d052c-da4a-494a-937f-a0d17b1c6cf5"
],
"targetConnectionIds": [
"7c96c827-3ffd-460c-a573-e9558f72f263"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "bf5286a9c1ad4266baca76ba3adc9366",
"mappingVersion": "0"
}
}
],
"scheduleParams": {
"startTime": "1625040887",
"frequency": "minute",
"interval": 15
}
}'
name
description
flowSpec.id
6499120c-0b15-42dc-936e-847ea3c24d72
.flowSpec.version
1.0
.sourceConnectionIds
targetConnectionIds
transformations
transformations.name
transformations.params.mappingId
transformations.params.mappingVersion
0
.scheduleParams.startTime
scheduleParams.frequency
once
, minute
, hour
, day
,或 week
.scheduleParams.interval
once
并且应大于或等于 15
其他频率值。响应
成功的响应会返回ID (id
)。 您可以使用此ID监视、更新或删除数据流。
{
"id": "993f908f-3342-4d9c-9f3c-5aa9a189ca1a",
"etag": "\"510bb1d4-8453-4034-b991-ab942e11dd8a\""
}
附录
以下部分提供了有关监视、更新和删除数据流的步骤的信息。
监测数据流
创建数据流后,您可以监视通过它摄取的数据,以查看有关流运行、完成状态和错误的信息。 有关完整的API示例,请阅读以下指南: 使用API监控源数据流.
更新您的数据流
通过向发出PATCH请求,更新数据流的详细信息,例如其名称和描述,以及其运行计划和关联的映射集。 /flows
端点 Flow Service API,同时提供数据流的ID。 发出PATCH请求时,必须提供数据流的唯一值 etag
在 If-Match
标题。 有关完整的API示例,请阅读以下指南: 使用API更新源数据流
更新您的帐户
PATCH通过向 Flow Service API,同时将您的基本连接ID作为查询参数提供。 发出PATCH请求时,必须提供源帐户的唯一帐户 etag
在 If-Match
标题。 有关完整的API示例,请阅读以下指南: 使用API更新源帐户.
删除您的数据流
通过向以下对象执行DELETE请求来删除您的数据流: Flow Service API,同时提供您要作为查询参数的一部分删除的数据流的ID。 有关完整的API示例,请阅读以下指南: 使用API删除数据流.
删除您的帐户
向以下网站发出DELETE请求,删除您的帐户: Flow Service API,同时提供要删除帐户的基本连接ID。 有关完整的API示例,请阅读以下指南: 使用API删除源帐户.