使用為電子商務來源建立資料流 Flow Service API
本教學課程涵蓋從電子商務來源擷取資料，並使用將其帶至Platform的步驟 Flow Service API.
NOTE
- 為了建立資料流，您必須擁有包含電子商務來源的有效基底連線ID。 如果您沒有此ID，請參閱 來源概觀 如需可建立基礎連線的電子商務來源清單。
- 為了讓Experience Platform擷取資料，所有以表格為基礎的批次來源的時區都必須設定為UTC。
快速入門
本教學課程需要您實際瞭解下列Adobe Experience Platform元件：
-
Experience Data Model (XDM) System：Experience Platform組織客戶體驗資料的標準化架構。
- 結構描述組合基本概念：瞭解XDM結構描述的基本建置區塊，包括結構描述組合中的關鍵原則和最佳實務。
- 結構描述登入API：瞭解如何成功執行對結構描述登入API的呼叫。 這包括您的
{TENANT_ID}、「容器」的概念，以及發出請求所需的標頭（請特別注意Accept標頭及其可能的值）。
-
Catalog Service：目錄是內資料位置和譜系的記錄系統 Experience Platform.
-
Batch ingestion：批次擷取API可讓您將資料擷取到 Experience Platform 作為批次檔案。
-
Sandboxes： Experience Platform 提供分割單一區域的虛擬沙箱 Platform 將執行個體整合至個別的虛擬環境中，協助開發及改進數位體驗應用程式。
使用平台API
如需如何成功呼叫Platform API的詳細資訊，請參閱以下指南： Platform API快速入門.
建立來源連線 source
您可以透過向以下發出POST請求來建立來源連線： Flow Service API。 來源連線由連線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": "Shopify source connection",
"baseConnectionId": "582f4f8d-71e9-4a5c-a164-9d2056318d6c",
"description": "Shopify source connection",
"data": {
"format": "tabular"
},
"params": {
"tableName": "Shopify.Orders",
"columns": [
{
"name": "Email",
"type": "string"
},
{
"name": "Phone",
"type": "string"
},
]
},
"connectionSpec": {
"id": "4f63aa36-bd48-4e33-bb83-49fbcd11c708",
"version": "1.0"
}
}'
屬性
說明
baseConnectionId您的電子商務來源的連線ID。
params.path來源檔案的路徑。
connectionSpec.id您的電子商務來源的連線規格ID。
回應
成功的回應會傳回唯一識別碼(id)。 在後續步驟中，建立目標連線時需要此ID。
{
"id": "c278ab14-acdf-440b-b67f-1265d15a7655",
"etag": "\"10007c3f-0000-0200-0000-5fa9be720000\""
}
建立目標XDM結構描述 target-schema
為了在Platform中使用來源資料，必須建立目標結構描述，以根據您的需求來建構來源資料。 然後目標結構描述會用來建立包含來源資料的Platform資料集。
您可以透過對以下對象執行POST請求來建立目標XDM結構描述： 結構描述登入API.
如需如何建立目標XDM結構的詳細步驟，請參閱以下教學課程： 使用API建立結構描述.
建立目標資料集 target-dataset
您可以透過對執行POST請求來建立目標資料集 目錄服務API，在裝載中提供目標結構描述的ID。
如需如何建立目標資料集的詳細步驟，請參閱教學課程，位於 使用API建立資料集.
建立目標連線 target-connection
目標連線代表與擷取資料著陸目的地之間的連線。 若要建立目標連線，您必須提供與Data Lake相關聯的固定連線規格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": "Shopify target connection",
"description": "Shopify target connection",
"data": {
"format": "parquet_xdm",
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/854ddc36ad2c7bd001f66a4392575ed4004f81883328772f",
"version": "application/vnd.adobe.xed-full-notext+json; version=1"
}
},
"params": {
"dataSetId": "5fa9c083de62e418dd170b42"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
屬性
說明
data.schema.id此
$id 目標XDM結構描述的。data.schema.version結構描述的版本。 此值必須設定
application/vnd.adobe.xed-full+json;version=1，會傳回結構描述的最新次要版本。params.dataSetId上一步中產生的目標資料集的ID。 注意：建立目標連線時，您必須提供有效的資料集ID。 無效的資料集ID將會導致錯誤。
connectionSpec.id用來連線至Data Lake的連線規格ID。 此ID為：
c604ff05-7f1a-43c0-8e18-33bf874cb11c.回應
成功回應會傳回新目標連線的唯一識別碼(id)。 在後續步驟中需要此值，才能建立資料流。
{
"id": "6c0ba537-a96b-4d74-8c95-450eb88baee8",
"etag": "\"00005506-0000-0200-0000-5fa9c13c0000\""
}
建立對應 mapping
為了將來源資料擷取到目標資料集中，必須首先將其對應到目標資料集所堅持的目標結構描述。
若要建立對應集，請向以下發出POST請求： mappingSets 的端點 Data Prep API 提供您的目標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/854ddc36ad2c7bd001f66a4392575ed4004f81883328772f",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "personalEmail.address",
"sourceAttribute": "Email",
"identity": false,
"version": 0
},
{
"destinationXdmPath": "mobilePhone.number",
"sourceAttribute": "Shipping_Address_Phone",
"identity": false,
"version": 0
}
]
}'
屬性
說明
xdmSchema此
$id 目標XDM結構描述的。回應
成功的回應會傳回新建立的對應詳細資訊，包括其唯一識別碼(id)。 在後續步驟中需要此ID才能建立資料流。
{
"id": "22922102bffd4369b6209c102a604062",
"version": 0,
"createdDate": 1604960750613,
"modifiedDate": 1604960750613,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
查詢資料流規格 specs
資料流負責從來源收集資料並將收集到的資料匯入 Platform. 若要建立資料流，您必須先透過對以下專案執行GET要求來取得資料流規格： Flow Service API。 資料流規格負責從電子商務來源收集資料。
API格式
GET /flowSpecs?property=name=="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}'
回應
成功的回應會傳回負責將資料從來源帶入Platform的資料流規格的詳細資料。 回應包含唯一的流量規格 id 建立新資料流時需要。
NOTE
為了簡單起見，會隱藏下列JSON回應裝載。 選取「裝載」以檢視回應裝載。
檢視裝載
| code language-json |
|---|
|
建立資料流
收集資料的最後一步是建立資料流。 此時，您應該已準備下列必要值：
資料流負責從來源排程及收集資料。 您可以執行POST要求，同時在要求裝載中提供先前提到的值，藉此建立資料流。
若要排程內嵌，您必須先將開始時間值設為以秒為單位的epoch時間。 然後，您必須將頻率值設為五個選項之一： 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": "Test Shopify dataflow",
"description": "Shopify With mapping ingestion",
"flowSpec": {
"id": "14518937-270c-4525-bdec-c2ba7cce3860",
"version": "1.0"
},
"sourceConnectionIds": [
"c278ab14-acdf-440b-b67f-1265d15a7655"
],
"targetConnectionIds": [
"6c0ba537-a96b-4d74-8c95-450eb88baee8"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "22922102bffd4369b6209c102a604062",
"mappingVersion": 0
}
}
],
"scheduleParams": {
"startTime": "1604961070",
"frequency": "once"
}
}'
屬性
說明
flowSpec.id此 流程規格ID 已在上一步驟中擷取。
sourceConnectionIds此 來源連線ID 已在先前步驟中擷取。
targetConnectionIds此 目標連線ID 已在先前步驟中擷取。
transformations.params.mappingId此 對應ID 已在先前步驟中擷取。
transformations.params.mappingId與您的電子商務來源相關聯的對應ID。
scheduleParams.startTime資料流的開始時間（以Epoch時間計）。
scheduleParams.frequency此
frequency 資料流將收集資料的位置。 可接受的值包括： once， minute， hour， day，或 week.scheduleParams.interval間隔會指定兩個連續資料流執行之間的期間。 間隔的值應為非零整數。 在以下情況下不需要間隔：
frequency 設為 once 且應大於或等於 15 針對其他 frequency 值。回應
成功的回應會傳回ID id 建立資料流的URL名稱。
{
"id": "20c115bc-46e3-40f3-bfe9-fb25abe4ba76",
"etag": "\"030018cb-0000-0200-0000-5fa9c31a0000\""
}
監視資料流
建立資料流後，您可以監視透過該資料流擷取的資料，以檢視有關資料流執行、完成狀態和錯誤的資訊。 如需如何監視資料流的詳細資訊，請參閱以下教學課程： 監視API中的資料流
後續步驟
依照本教學課程中的指示，您已建立來源聯結器，以依排程收集資料電子商務。 下游現在可以使用傳入的資料 Platform 服務，例如 Real-Time Customer Profile 和 Data Science Workspace. 如需更多詳細資訊，請參閱下列檔案：
recommendation-more-help
337b99bb-92fb-42ae-b6b7-c7042161d089