使用匯出資料集 Flow Service API
- 已購買Real-Time CDP Prime和Ultimate套件、Adobe Journey Optimizer或Customer Journey Analytics的客戶可使用此功能。 如需詳細資訊,請聯絡您的Adobe代表。
本文會說明使用 Flow Service API 匯出 資料集 從Adobe Experience Platform到您偏好的雲端儲存位置,例如 Amazon S3、 SFTP位置或 Google Cloud Storage.
可用於匯出的資料集 datasets-to-export
您可以匯出的資料集取決於Experience Platform應用程式(Real-Time CDP、Adobe Journey Optimizer)、階層(Prime或Ultimate)以及您購買的任何附加元件(例如:Data Distiller)。
請參閱 UI教學課程頁面上的表格 以瞭解您可以匯出哪些資料集。
支援的目的地 supported-destinations
目前,您可以將資料集匯出至熒幕擷取畫面中強調並列於下方的雲端儲存空間目的地。
快速入門 get-started
本指南需要您深入了解下列 Adobe Experience Platform 元件:
- Experience Platform datasets:所有成功內嵌至Adobe Experience Platform的資料都會儲存在 Data Lake 作為資料集。 資料集是資料集合的儲存和管理結構,通常是包含方案 (欄) 和欄位 (列) 的表格。 資料集也包含中繼資料,可說明其儲存資料的各個層面。
- Sandboxes: Experience Platform 提供分割單一區域的虛擬沙箱 Platform 將執行個體整合至個別的虛擬環境中,協助開發及改進數位體驗應用程式。
以下小節提供您必須知道的其他資訊,才能將資料集匯出到Platform中的雲端儲存空間目標。
必要權限 permissions
若要匯出資料集,您需要 檢視目的地, 檢視資料集、和 管理和啟用資料集目的地 存取控制許可權. 閱讀 存取控制總覽 或聯絡您的產品管理員以取得必要許可權。
為確保您擁有匯出資料集的必要許可權以及目的地支援匯出資料集,請瀏覽目的地目錄。 如果目的地有 啟動 或 匯出資料集 控制項,則表示您擁有適當的許可權。
讀取範例 API 呼叫 reading-sample-api-calls
本教學課程提供範例API呼叫,示範如何格式化您的請求。 這些包括路徑、必要的標頭和正確格式化的請求承載。 此外,也提供 API 回應中傳回的範例 JSON。 如需文件中用於範例 API 呼叫的慣例相關資訊,請參閱 疑難排解指南中的如何讀取範例 API 呼叫Experience Platform一節。
收集必要和選用標題的值 gather-values-headers
為了呼叫 Platform API,您必須先完成 Experience Platform驗證教學課程. 完成驗證教學課程會提供所有 Experience Platform API 呼叫中每個必要標頭的值,如下所示:
- 授權:持有人
{ACCESS_TOKEN}
- x-api-key:
{API_KEY}
- x-gw-ims-org-id:
{ORG_ID}
中的資源 Experience Platform 可隔離至特定的虛擬沙箱。 在要求給 Platform API中,您可以指定要執行作業的沙箱名稱和ID。 這些是選用引數。
- x-sandbox-name:
{SANDBOX_NAME}
包含裝載(POST、PUT、PATCH)的所有請求都需要額外的媒體型別標頭:
- Content-Type:
application/json
API參考檔案 api-reference-documentation
在本教學課程中,您可以找到所有API作業的隨附參考檔案。 請參閱 Flow Service - Adobe Developer網站上的目的地API檔案. 我們建議您同時使用本教學課程和API參考檔案。
字彙 glossary
如需在此API教學課程中遇到的術語說明,請參閱 字彙表區段 API參考檔案的底稿。
收集所需目的地的連線規格和流量規格 gather-connection-spec-flow-spec
在開始匯出資料集的工作流程之前,請確定您要將資料集匯出到的目的地的連線規格和流程規格ID。 請參考下表。
4fce964d-3f37-408f-9778-e597338a21ee
269ba276-16fc-47db-92b0-c1049a3c131f
6d6b59bf-fb58-4107-9064-4d246c0e5bb2
95bd8965-fc8a-4119-b9c3-944c2c2df6d2
be2c3209-53bc-47e7-ab25-145db8b873e1
17be2013-2549-41ce-96e7-a70363bec293
10440537-2a7b-4583-ac39-ed38d4b848e8
cd2fc47e-e838-4f38-a581-8fff2f99b63a
c5d93acb-ea8b-4b14-8f53-02138444ae99
585c15c4-6cbf-4126-8f87-e26bff78b657
36965a81-b1c6-401b-99f8-22508f1e6a26
354d6aad-4754-46e4-a576-1b384561c440
您需要這些ID來建構各種 Flow Service 實體。 您也需參考 Connection Spec 自身來設定特定圖元,以便您可以擷取 Connection Spec 從 Flow Service APIs. 請參閱以下範例,擷取表格中所有目的地的連線規格:
要求
accordion | ||
---|---|---|
擷取 connection spec 的 Amazon S3 | ||
|
回應
accordion | ||
---|---|---|
Amazon S3 — 連線規格 | ||
|
要求
accordion | ||
---|---|---|
擷取 connection spec 的 Azure Blob Storage | ||
|
回應
accordion | ||
---|---|---|
Azure Blob Storage - Connection spec | ||
|
要求
accordion | ||
---|---|---|
擷取 connection spec 的 Azure Data Lake Gen 2(ADLS Gen2) | ||
|
回應
accordion | ||
---|---|---|
Azure Data Lake Gen 2(ADLS Gen2) - Connection spec | ||
|
要求
accordion | ||
---|---|---|
擷取 connection spec 的 Data Landing Zone(DLZ) | ||
|
回應
accordion | ||
---|---|---|
Data Landing Zone(DLZ) - Connection spec | ||
|
要求
accordion | ||
---|---|---|
擷取 connection spec 的 Google Cloud Storage | ||
|
回應
accordion | ||
---|---|---|
Google Cloud Storage - Connection spec | ||
|
要求
accordion | ||
---|---|---|
擷取 connection spec 適用於SFTP | ||
|
回應
accordion | ||
---|---|---|
SFTP - Connection spec | ||
|
請依照下列步驟,將資料集資料流設定為雲端儲存空間目的地。 對於某些步驟,請求和回應會因不同的雲端儲存空間目的地而異。 在這些情況下,請使用頁面上的索引標籤,擷取您要連線並匯出資料集的目標的特定請求和回應。 請務必使用正確的 connection spec 和 flow spec ,以取得您正在設定的目的地。
擷取資料集清單 retrieve-list-of-available-datasets
若要擷取符合啟用資格的資料集清單,首先要對以下端點進行API呼叫。
要求
code language-shell |
---|
|
請注意,若要擷取合格的資料集,請 connection spec 請求URL中使用的ID必須是資料湖來源連線規格ID, 23598e46-f560-407b-88d5-ea6207e49db0
,以及兩個查詢引數 outputField=datasets
和 outputType=activationDatasets
必須指定。 所有其他查詢引數均為 目錄服務API.
回應
code language-json |
---|
|
成功的回應包含符合啟用條件的資料集清單。 這些資料集可在下一步中建構來源連線時使用。
如需每個傳回資料集的不同回應引數相關資訊,請參閱 資料集API開發人員檔案.
建立來源連線 create-source-connection
擷取您要匯出的資料集清單後,您可以使用這些資料集ID建立來源連線。
要求
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
code language-shell line-numbers data-start-1 data-line-offset-4 h-12 h-16 |
---|
|
回應
code language-json |
---|
|
成功的回應會傳回ID (id
)的來源連線,以及 etag
. 記下來源連線ID,因為稍後建立資料流時會需要它。
另請記住:
- 在此步驟中建立的來源連線需要連結至資料流,其資料集才能啟動至目的地。 請參閱 建立資料流 區段,以瞭解如何將來源連線連結至資料流的資訊。
- 來源連線的資料集ID在建立後即無法修改。 如果您需要從來源連線新增或移除資料集,則必須建立新的來源連線,並將新來源連線的ID連結至資料流。
建立(目標)基礎連線 create-base-connection
基礎連線會將認證安全地儲存到您的目的地。 根據目的地型別,針對該目的地進行驗證所需的認證可能會有所不同。 若要尋找這些驗證引數,請先擷取 connection spec 區段中說明的所需目的地 收集連線規格和流量規格 然後檢視 authSpec
回應。 請參考下列標籤 authSpec
所有支援目的地的屬性。
accordion | ||
---|---|---|
Amazon S3 - Connection spec 顯示 auth spec | ||
請注意醒目提示的行,其中含有內嵌註釋 connection spec 以下範例提供有關在何處尋找驗證引數的其他資訊 connection spec.
|
accordion | ||
---|---|---|
Azure Blob Storage - Connection spec 顯示 auth spec | ||
請注意醒目提示的行,其中含有內嵌註釋 connection spec 以下範例提供有關在何處尋找驗證引數的其他資訊 connection spec.
|
accordion | ||
---|---|---|
Azure Data Lake Gen 2(ADLS Gen2) - Connection spec 顯示 auth spec | ||
請注意醒目提示的行,其中含有內嵌註釋 connection spec 以下範例提供有關在何處尋找驗證引數的其他資訊 connection spec.
|
accordion | |||||
---|---|---|---|---|---|
Data Landing Zone(DLZ) - Connection spec 顯示 auth spec | |||||
|
accordion | ||
---|---|---|
Google Cloud Storage - Connection spec 顯示 auth spec | ||
請注意醒目提示的行,其中含有內嵌註釋 connection spec 以下範例提供有關在何處尋找驗證引數的其他資訊 connection spec.
|
accordion | |||||
---|---|---|---|---|---|
SFTP - Connection spec 顯示 auth spec | |||||
請注意醒目提示的行,其中含有內嵌註釋 connection spec 以下範例提供有關在何處尋找驗證引數的其他資訊 connection spec.
|
使用驗證規格中指定的屬性(即 authSpec
(從回應),您可以使用每個目的地型別特有的必要認證來建立基礎連線,如下列範例所示:
要求
accordion | |||||
---|---|---|---|---|---|
Amazon S3 — 基本連線要求 | |||||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
回應
accordion | ||
---|---|---|
Amazon S3 基本連線回應 | ||
|
要求
accordion | |||||
---|---|---|---|---|---|
Azure Blob Storage — 基本連線要求 | |||||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
回應
accordion | ||
---|---|---|
Azure Blob Storage — 基本連線回應 | ||
|
要求
accordion | |||||
---|---|---|---|---|---|
Azure Data Lake Gen 2(ADLS Gen2) — 基本連線要求 | |||||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
回應
accordion | ||
---|---|---|
Azure Data Lake Gen 2(ADLS Gen2) — 基本連線回應 | ||
|
要求
accordion | |||||
---|---|---|---|---|---|
Data Landing Zone(DLZ) — 基本連線要求 | |||||
|
回應
accordion | ||
---|---|---|
Data Landing Zone — 基本連線回應 | ||
|
要求
accordion | |||||
---|---|---|---|---|---|
Google Cloud Storage — 基本連線要求 | |||||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
回應
accordion | ||
---|---|---|
Google Cloud Storage — 基本連線回應 | ||
|
要求
accordion | |||||
---|---|---|---|---|---|
使用密碼的SFTP — 基本連線要求 | |||||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
accordion | |||||
---|---|---|---|---|---|
使用SSH金鑰的SFTP — 基本連線要求 | |||||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
回應
accordion | ||
---|---|---|
SFTP — 基本連線回應 | ||
|
記下回應中的連線ID。 建立目標連線時,下個步驟需要此ID。
建立目標連線 create-target-connection
接下來,您需要建立目標連線,以儲存資料集的匯出引數。 匯出引數包括位置、檔案格式、壓縮和其他細節。 請參閱 targetSpec
目的地的連線規格中提供的屬性,用於瞭解每個目的地型別的支援屬性。 請參考下列標籤 targetSpec
所有支援目的地的屬性。
accordion | ||
---|---|---|
Amazon S3 - Connection spec 顯示目標連線引數 | ||
請注意反白的行,這些行具有內嵌註解 connection spec 以下範例提供有關在何處尋找 target spec 連線規格中的引數。 您也可以在下列範例中看到目標引數為 非 適用於資料集匯出目的地。
|
accordion | ||
---|---|---|
Azure Blob Storage - Connection spec 顯示目標連線引數 | ||
請注意反白的行,這些行具有內嵌註解 connection spec 以下範例提供有關在何處尋找 target spec 連線規格中的引數。 您也可以在下列範例中看到目標引數為 非 適用於資料集匯出目的地。
|
accordion | ||
---|---|---|
Azure Data Lake Gen 2(ADLS Gen2) - Connection spec 顯示目標連線引數 | ||
請注意反白的行,這些行具有內嵌註解 connection spec 以下範例提供有關在何處尋找 target spec 連線規格中的引數。 您也可以在下列範例中看到目標引數為 非 適用於資料集匯出目的地。
|
accordion | ||
---|---|---|
Data Landing Zone(DLZ) - Connection spec 顯示目標連線引數 | ||
請注意反白的行,這些行具有內嵌註解 connection spec 以下範例提供有關在何處尋找 target spec 連線規格中的引數。 您也可以在下列範例中看到目標引數為 非 適用於資料集匯出目的地。
|
accordion | ||
---|---|---|
Google Cloud Storage - Connection spec 顯示目標連線引數 | ||
請注意反白的行,這些行具有內嵌註解 connection spec 以下範例提供有關在何處尋找 target spec 連線規格中的引數。 您也可以在下列範例中看到目標引數為 非 適用於資料集匯出目的地。
|
accordion | ||
---|---|---|
SFTP - Connection spec 顯示目標連線引數 | ||
請注意反白的行,這些行具有內嵌註解 connection spec 以下範例提供有關在何處尋找 target spec 連線規格中的引數。 您也可以在下列範例中看到目標引數為 非 適用於資料集匯出目的地。
|
透過使用上述規格,您可以建構專屬於您所需雲端儲存空間目的地的目標連線要求,如下方標籤所示。
要求
accordion | |||||
---|---|---|---|---|---|
Amazon S3 - Target連線要求 | |||||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
回應
accordion | ||
---|---|---|
目標連線 — 回應 | ||
|
要求
accordion | |||||
---|---|---|---|---|---|
Azure Blob Storage - Target連線要求 | |||||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
回應
accordion | ||
---|---|---|
目標連線 — 回應 | ||
|
要求
accordion | |||||
---|---|---|---|---|---|
Azure Blob Storage - Target連線要求 | |||||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
回應
accordion | ||
---|---|---|
目標連線 — 回應 | ||
|
要求
accordion | |||||
---|---|---|---|---|---|
Data Landing Zone - Target連線要求 | |||||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
回應
accordion | ||
---|---|---|
目標連線 — 回應 | ||
|
要求
accordion | |||||
---|---|---|---|---|---|
Google Cloud Storage - Target連線要求 | |||||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
回應
accordion | ||
---|---|---|
目標連線 — 回應 | ||
|
要求
accordion | |||||
---|---|---|---|---|---|
SFTP - Target連線要求 | |||||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
回應
accordion | ||
---|---|---|
Target連線 — 回應 | ||
|
記下回應中的Target連線ID。 建立資料流以匯出資料集時,下個步驟將需要此ID。
建立資料流 create-dataflow
目的地設定的最後一步是設定資料流。 資料流會將先前建立的實體連結在一起,並提供設定資料集匯出排程的選項。 若要建立資料流,請根據您所需的雲端儲存空間目的地,使用下列裝載,並取代先前步驟中的實體ID。
要求
accordion | ||
---|---|---|
建立資料集資料流至 Amazon S3 目的地 — 要求 | ||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
回應
accordion | ||
---|---|---|
建立資料流 — 回應 | ||
|
要求
accordion | ||
---|---|---|
建立資料集資料流至 Azure Blob Storage 目的地 — 要求 | ||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
回應
accordion | ||
---|---|---|
建立資料流 — 回應 | ||
|
要求
accordion | ||
---|---|---|
建立資料集資料流至 Azure Data Lake Gen 2(ADLS Gen2) 目的地 — 要求 | ||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
回應
accordion | ||
---|---|---|
建立資料流 — 回應 | ||
|
要求
accordion | ||
---|---|---|
建立資料集資料流至 Data Landing Zone 目的地 — 要求 | ||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
回應
accordion | ||
---|---|---|
建立資料流 — 回應 | ||
|
要求
accordion | ||
---|---|---|
建立資料集資料流至 Google Cloud Storage 目的地 — 要求 | ||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
回應
accordion | ||
---|---|---|
建立資料流 — 回應 | ||
|
要求
accordion | ||
---|---|---|
建立資料集資料流至SFTP目的地 — 請求 | ||
請注意請求範例中反白顯示內嵌註解的行,這些註解會提供額外資訊。 將請求複製貼上您選擇的終端機時,移除請求中的內嵌註解。
|
回應
accordion | ||
---|---|---|
建立資料流 — 回應 | ||
|
記下回應中的資料流ID。 擷取資料流執行以驗證成功的日期集匯出時,下個步驟將需要此ID。
取得資料流執行 get-dataflow-runs
若要檢查資料流的執行,請使用資料流執行API:
要求
在擷取資料流執行的請求中,在建立資料流時,將您在上一步驟中取得的資料流ID新增為查詢引數。
code language-shell |
---|
|
回應
code language-json |
---|
|
您可在此找到關於 資料流執行API傳回的各種引數 API參考檔案中。
驗證資料集匯出成功 verify
匯出資料集時,Experience Platform會建立 .json
或 .parquet
檔案中所指定的儲存位置。 根據您提供的匯出排程,預期會在以下時間將新檔案儲存在您的儲存位置 建立資料流.
Experience Platform會在您指定的儲存位置中建立資料夾結構,並存放匯出的資料集檔案。 每次匯出時都會建立一個新資料夾,其模式如下:
folder-name-you-provided/datasetID/exportTime=YYYYMMDDHHMM
預設檔案名稱是隨機產生的,並確保匯出的檔案名稱是唯一的。
範例資料集檔案 sample-files
這些檔案存在於您的儲存位置即表示匯出成功。 若要瞭解匯出檔案的結構,您可以下載範例 .parquet檔案 或 .json檔案.
壓縮的資料集檔案 compressed-dataset-files
在步驟至 建立目標連線,您可以選取要壓縮的匯出資料集檔案。
請注意兩種檔案型別在壓縮時的檔案格式差異:
- 匯出壓縮的JSON檔案時,匯出的檔案格式為
json.gz
- 匯出壓縮的parquet檔案時,匯出的檔案格式為
gz.parquet
API錯誤處理 api-error-handling
本教學課程中的API端點會遵循一般Experience PlatformAPI錯誤訊息原則。 請參閱 API狀態代碼 和 請求標頭錯誤 (位於平台疑難排解指南中),以取得有關解譯錯誤回應的詳細資訊。
後續步驟 next-steps
依照本教學課程中的指示,您已成功將Platform連線至您偏好的批次雲端儲存空間目的地之一,並設定資料流至個別目的地以匯出資料集。 如需詳細資訊,請參閱下列頁面,例如如何使用流量服務API編輯現有資料流: