建立資料流以將資料從CRM擷取到Experience Platform
閱讀本指南，瞭解如何使用Flow Service API建立資料流並將資料擷取到Adobe Experience Platform。
快速入門
本指南需要您深入瞭解下列Experience Platform元件：
使用Experience Platform API
如需如何成功呼叫Experience Platform API的詳細資訊，請閱讀Experience Platform API快速入門的指南。
建立基礎連線 base
若要為來源建立資料流，您需要已完整驗證的來源帳戶及其對應的基本連線ID。 如果您沒有此ID，請造訪來源目錄，尋找您可建立基礎連線的來源清單。
建立目標XDM結構描述 target-schema
Experience Data Model (XDM)結構描述提供一種標準化方式，可在Experience Platform中組織和描述客戶體驗資料。 若要將來源資料內嵌至Experience Platform，您必須先建立目標XDM結構描述，定義您要內嵌的資料結構和型別。 此結構描述可作為您擷取之資料將存放的Experience Platform資料集的藍圖。
可透過對結構描述登入API執行POST要求來建立目標XDM結構描述。 如需如何建立目標XDM架構的詳細步驟，請閱讀以下指南：
建立後，稍後將需要目標XDM結構描述$id以用於您的目標資料集和對應。
建立目標資料集 target-dataset
資料集是資料集合的儲存和管理結構，通常會像有欄（結構描述）和列（欄位）的表格一樣結構。 成功擷取至Experience Platform的資料會以資料集的形式儲存在資料湖中。 在此步驟中，您可以建立新資料集或使用現有資料集。
您可以對目錄服務API發出POST要求，同時在承載中提供目標結構描述的ID，藉此建立目標資料集。 如需如何建立目標資料集的詳細步驟，請參閱使用API建立資料集的指南。
TIP
如果您想要將資料內嵌至即時客戶設定檔，則必須確保已為設定檔啟用目標XDM結構描述和目標資料集。
選取以檢視範例
API格式
| code language-http |
|---|
|
要求
以下範例說明如何建立已啟用即時客戶設定檔擷取的目標資料集。 在此請求中，unifiedProfile屬性設定為true （在tags物件下），以告知Experience Platform將資料集納入即時客戶設定檔中。
| code language-shell |
|---|
|
| table 0-row-2 1-row-2 2-row-2 3-row-2 | |
|---|---|
| 屬性 | 說明 |
name |
目標資料集的描述性名稱。 使用清晰且唯一的名稱，以便在未來操作中更容易識別和管理您的資料集。 |
schemaRef.id |
目標XDM結構描述的ID。 |
tags.unifiedProfile |
布林值，通知Experience Platform資料是否應擷取到即時客戶個人檔案中。 |
回應
成功回應會傳回目標資料集的ID。 稍後建立目標連線時需要此ID。
| code language-json |
|---|
|
建立來源連線 source
來源連線會定義如何將資料從外部來源帶入Experience Platform。 它同時指定來源系統和傳入資料的格式，並且會參考包含驗證詳細資訊的基礎連線。 每個來源連線都是您組織專屬的。
- 對於檔案型來源（例如雲端儲存空間），來源連線可以包含欄分隔符號、編碼型別、壓縮型別、檔案選取的規則運算式，以及是否要以遞回方式擷取檔案等設定。
- 對於以表格為基礎的來源（例如資料庫、CRM和行銷自動化提供者），來源連線可以指定詳細資訊，例如表格名稱和欄對應。
若要建立來源連線，請向/sourceConnections API的Flow Service端點發出POST要求，並提供您的基本連線ID、連線規格ID以及來源資料檔案的路徑。
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": "ACME source connection",
"description": "A source connection for ACME contact data",
"baseConnectionId": "6990abad-977d-41b9-a85d-17ea8cf1c0e4",
"data": {
"format": "tabular"
},
"params": {
"tableName": "Contact",
"columns": [
{
"name": "TestID",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Name",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Datefield",
"type": "string",
"meta:xdmType": "date-time",
"xdm": {
"type": "string",
"format": "date-time"
}
}
]
},
"connectionSpec": {
"id": "cfc0fee1-7dc0-40ef-b73e-d8b134c436f5",
"version": "1.0"
}
}'
屬性
說明
name來源連線的描述性名稱。 使用清晰且唯一的名稱，以便在未來操作中更容易識別和管理您的連線。
description選用的說明，您可以新增此說明，以提供來源連線的其他資訊。
baseConnectionId您的基礎連線的
id。 您可以使用Flow Service API向Experience Platform驗證您的來源以擷取此ID。data.format資料的格式。 針對以資料表為基礎的來源（例如資料庫、CRM和行銷自動化提供者），將此值設定為
tabular。params.tableName來源帳戶中您要擷取至Experience Platform的表格名稱。
params.columns您要擷取至Experience Platform的特定資料表欄。
connectionSpec.id您使用之來源的連線規格ID。
回應
成功的回應會傳回來源連線的ID。 需要此ID才能建立資料流並內嵌您的資料。
{
"id": "b7581b59-c603-4df1-a689-d23d7ac440f3",
"etag": "\"ef05d265-0000-0200-0000-6019e0080000\""
}
建立目標連線 target
目標連線代表與擷取資料著陸目的地之間的連線。 若要建立目標連線，您必須提供與Data Lake關聯的固定連線規格ID。 此連線規格識別碼為： c604ff05-7f1a-43c0-8e18-33bf874cb11c。
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": "ACME target connection",
"description": "ACME target connection",
"data": {
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/52b59140414aa6a370ef5e21155fd7a686744b8739ecc168",
"version": "application/vnd.adobe.xed-full+json;version=1"
}
},
"params": {
"dataSetId": "6889f4f89b982b2b90bc1207"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
屬性
說明
name目標連線的描述性名稱。 使用清晰且唯一的名稱，以便在未來操作中更容易識別和管理您的連線。
description選用的說明，您可將其新增以提供目標連線的其他資訊。
data.schema.id目標XDM結構描述的ID。
params.dataSetId目標資料集的ID。
connectionSpec.id資料湖的連線規格ID。 此ID已修正：
c604ff05-7f1a-43c0-8e18-33bf874cb11c。對應 mapping
接著，將來源資料對應至目標資料集所固定的目標結構描述。 若要建立對應，請對mappingSetsAPIData Prep 的端點提出POST要求。 包含您的目標XDM結構描述ID和您要建立之對應集的詳細資訊。
API格式
POST /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/52b59140414aa6a370ef5e21155fd7a686744b8739ecc168",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "_id",
"sourceAttribute": "TestID",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.fullName",
"sourceAttribute": "Name",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.birthDate",
"sourceAttribute": "Datefield",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
}
]
}'
屬性
說明
xdmSchema目標XDM結構的
$id。回應
成功的回應會傳回新建立的對應詳細資料，包括其唯一識別碼(id)。 在後續步驟中需要此ID才能建立資料流。
{
"id": "93ddfa69c4864d978832b1e5ef6ec3b9",
"version": 0,
"createdDate": 1612309018666,
"modifiedDate": 1612309018666,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
擷取資料流規格 flow-specs
建立資料流之前，必須先擷取與來源對應的資料流規格。 若要擷取此資訊，請向/flowSpecs API的Flow Service端點提出GET要求。
API格式
GET /flowSpecs?property=name=="{NAME}"
查詢引數
說明
property=name=="{NAME}"資料流規格的名稱。
- 針對檔案型來源（例如雲端儲存空間），將此值設定為
CloudStorageToAEP。 - 對於以資料表為基礎的來源（例如資料庫、CRM和行銷自動化提供者），請將此值設定為
CRMToAEP。
要求
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/flowSpecs?property=name=="CRMToAEP"' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
回應
成功的回應會傳回負責將資料從來源帶入Experience Platform的資料流規格的詳細資料。 回應包含建立新資料流所需的唯一流程規格id。
為確保您使用正確的資料流規格，請檢查回應中的items.sourceConnectionSpecIds陣列。 確認您來源的連線規格ID已包含在此清單中。
選取以檢視
| code language-json |
|---|
|
建立資料流 dataflow
資料流是已設定的管道，可跨Experience Platform服務傳輸資料。 它定義如何從外部來源（例如資料庫、雲端儲存空間或API）擷取、處理資料，以及將其路由到目標資料集。 然後，身分服務、即時客戶個人檔案和目的地等服務會使用這些資料集來啟用和分析。
若要建立資料流，您必須提供下列專案的值：
在此步驟中，您可以在scheduleParams中使用下列引數來設定資料流程的擷取排程：
排程引數
說明
startTime資料流應該開始的Epoch時間（以秒為單位）。
frequency擷取頻率。 設定頻率以指出資料流執行的頻率。 您可以將頻率設為：
once：將頻率設為once以建立一次性內嵌。 間隔和回填設定不適用於一次性內嵌工作。 依預設，排程頻率會設定為一次。minute：將頻率設為minute，排程您的資料流以每分鐘擷取資料。hour：將頻率設為hour，排程您的資料流以每小時擷取資料。day：將頻率設為day，排程您的資料流每天擷取資料。week：將頻率設為week，排程資料流每週擷取資料。
interval連續內嵌之間的間隔（除once外的所有頻率均需要）。 設定間隔設定，以建立每次擷取之間的時間範圍。 例如，如果您的頻率設定為天，間隔為15，則資料流將每15天執行一次。 您不能將間隔設定為零。 每個頻率的最小接受間隔值如下：
once：不適用minute： 15hour: 1day: 1week: 1
backfill指示是否要擷取
startTime之前的歷史資料。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": "ACME Contact Dataflow",
"description": "A dataflow for ACME contact data",
"flowSpec": {
"id": "14518937-270c-4525-bdec-c2ba7cce3860",
"version": "1.0"
},
"sourceConnectionIds": [
"b7581b59-c603-4df1-a689-d23d7ac440f3"
],
"targetConnectionIds": [
"320f119a-5ac1-4ab1-88ea-eb19e674ea2e"
],
"transformations": [
{
"name": "Copy",
"params": {
"deltaColumn": {
"name": "Datefield",
"dateFormat": "YYYY-MM-DD",
"timezone": "UTC"
}
}
},
{
"name": "Mapping",
"params": {
"mappingId": "93ddfa69c4864d978832b1e5ef6ec3b9",
"mappingVersion": 0
}
}
],
"scheduleParams": {
"startTime": "1612310466",
"frequency":"minute",
"interval":"15",
"backfill": "true"
}
}'
屬性
說明
name資料流程的描述性名稱。 使用清楚且獨一無二的名稱，以便日後作業中更輕鬆地識別及管理您的資料流。
description選擇性說明，您可新增以提供其他資訊給資料流。
flowSpec.id與來源對應的流程規格ID。
sourceConnectionIds先前步驟中產生的來源連線ID。
targetConnectionIds先前步驟中產生的目標連線ID。
transformations.params.deltaColum用來區分新資料和現有資料的指定欄。 將根據所選欄的時間戳記擷取增量資料。
deltaColumn支援的格式為yyyy-MM-dd HH:mm:ss。 對於Microsoft Dynamics，deltaColumn支援的格式為yyyy-MM-ddTHH:mm:ssZ。transformations.params.deltaColumn.dateFormat差異欄要遵循的日期格式。
transformations.params.deltaColumn.timeZone解譯delta欄中的值時要使用的時區。
transformations.params.mappingId在先前步驟中產生的對應ID。
scheduleParams.startTime資料流的開始時間（以Epoch時間表示） （自Unix Epoch以來的秒數）。 決定資料流何時開始其首次執行。
scheduleParams.frequency資料流執行的頻率。 可接受的值包括：
once、minute、hour、day或week。scheduleParams.interval根據選取的頻率，連續資料流執行之間的間隔。 必須是非零整數。 例如，如果您的頻率設定為分鐘，而間隔為15，則資料流將每15分鐘執行一次。
scheduleParams.backfill布林值（
true或false），可決定是否要在首次建立資料流時擷取歷史資料（回填）。回應
成功的回應會傳回新建立的資料流識別碼(id)。
{
"id": "ae0a9777-b322-4ac1-b0ed-48ae9e497c7e",
"etag": "\"770029f8-0000-0200-0000-6019e7d40000\""
}
使用UI驗證API工作流程 validate-in-ui
您可以使用Experience Platform使用者介面來驗證資料流的建立。 導覽至Experience Platform UI中的 來源 目錄，然後從標題標籤中選取 資料流程。 接下來，使用資料流名稱欄，並找出您使用Flow Service API建立的資料流。
您可以透過資料流活動介面進一步驗證資料流。 使用右邊欄檢視資料流的API使用狀況資訊。 此區段會顯示在Flow Service中資料流建立程式期間產生的相同資料流ID、資料集ID和對應ID。
後續步驟
本教學課程將引導您完成使用Flow Service API在Experience Platform中建立資料流的程式。 您已瞭解如何建立及設定必要的元件，包括目標XDM結構、資料集、來源連線、目標連線和資料流本身。 按照這些步驟，您可以將來自外部來源的資料擷取到Experience Platform中自動化，讓下游服務（例如即時客戶個人資料和目的地）將擷取的資料用於進階使用案例。
監視資料流
建立資料流後，您可以直接在Experience Platform UI中監視其效能。 這包括追蹤擷取率、成功量度和發生的任何錯誤。 如需如何監視資料流的詳細資訊，請瀏覽有關監視帳戶和資料流的教學課程。
更新您的資料流
若要更新資料流排程、對應或一般資訊的設定，請瀏覽有關更新來源資料流的教學課程。
刪除您的資料流
您可以刪除不再需要的資料流，或使用 資料流 工作區中可用的 刪除 功能建立錯誤的資料流。 如需有關如何刪除資料流程的詳細資訊，請瀏覽有關刪除資料流程的教學課程。
recommendation-more-help
337b99bb-92fb-42ae-b6b7-c7042161d089