Adobe Experience Platform資料接收API允許您將資料作為批處理檔案接收到平台。 所攝取的資料可以是來自平面檔案(如Parke檔案)的配置檔案資料,也可以是符合該檔案中已知模式的資料 Experience Data Model (XDM)註冊表。
的 資料接收API參考 提供了有關這些API調用的其他資訊。
下圖概述了批處理接收過程:
本指南中使用的API端點是 資料接收API。 在繼續之前,請查看 入門指南 有關相關文檔的連結、閱讀本文檔中示例API調用的指南,以及有關成功調用任何Experience PlatformAPI所需標頭的重要資訊。
批處理資料接收存在一些限制:
要上載大於512MB的檔案,需要將檔案分成較小的塊。 有關上載大檔案的說明,請參見 此文檔的大檔案上載部分。
在接收資料時,瞭解如何 Experience Data Model (XDM)架構有效。 有關XDM欄位類型如何映射到不同格式的詳細資訊,請閱讀 架構註冊表開發人員指南。
在接收資料時具有一定的靈活性 — 如果類型與目標架構中的類型不匹配,則資料將轉換為表示的目標類型。 如果無法,則將用 TypeCompatibilityException
。
例如,JSON和CSV都沒有 date
或 date-time
的雙曲餘切值。 因此,這些值使用 ISO 8061格式化字串 (「2018-07-10T15:05:59.000-08:00")或Unix時間(以毫秒為單位)格式化,並在接收時轉換為目標XDM類型。
下表顯示了在接收資料時支援的轉換。
入站(行)與目標(列) | 字串 | 位元組 | 短 | 整數 | 龍 | 雙倍 | 日期 | 日期 — 時間 | 物件 | 地圖 |
---|---|---|---|---|---|---|---|---|---|---|
字串 | X | X | X | X | X | X | X | X | ||
位元組 | X | X | X | X | X | X | ||||
短 | X | X | X | X | X | X | ||||
整數 | X | X | X | X | X | X | ||||
龍 | X | X | X | X | X | X | X | X | ||
雙倍 | X | X | X | X | X | X | ||||
日期 | X | |||||||||
日期 — 時間 | X | |||||||||
物件 | X | X | ||||||||
地圖 | X | X |
布爾值和陣列不能轉換為其他類型。
的 Data Ingestion API允許您將資料作為批(資料單元,由一個或多個要作為單個單元被接收的檔案組成)接收到 Experience Platform 分三個基本步驟:
在將資料添加到資料集之前,必須將其連結到批處理,該批處理稍後將上載到指定的資料集。
POST /batches
要求
curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
-H "Content-Type: application/json" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"
-d '{
"datasetId": "{DATASET_ID}"
}'
屬性 | 說明 |
---|---|
datasetId |
要將檔案上載到的資料集的ID。 |
雷龐塞
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
屬性 | 說明 |
---|---|
id |
剛建立的批的ID(用於後續請求)。 |
relatedObjects.id |
要將檔案上載到的資料集的ID。 |
成功建立新批以進行上載後,可以將檔案上載到特定資料集。
可以使用「小檔案上載API」上載檔案。 但是,如果檔案太大且超出網關限制(如延長超時、超出正文大小的請求以及其他限制),則可以切換到「大檔案上載API」。 此API以塊形式上載檔案,並使用「大檔案上載完成API」調用將資料縫合在一起。
一旦建立了批處理,就可以將資料上載到預先存在的資料集。 正在上載的檔案必須與其引用的XDM架構匹配。
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
屬性 | 說明 |
---|---|
{BATCH_ID} |
批的ID。 |
{DATASET_ID} |
要上載檔案的資料集的ID。 |
{FILE_NAME} |
在資料集中看到的檔案的名稱。 |
要求
curl -X PUT "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet" \
-H "content-type: application/octet-stream" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}" \
--data-binary "@{FILE_PATH_AND_NAME}.parquet"
屬性 | 說明 |
---|---|
{FILE_PATH_AND_NAME} |
要上載到資料集中的檔案的路徑和檔案名。 |
雷龐塞
#Status 200 OK, with empty response body
要上載大檔案,必須將檔案拆分為較小的塊,並一次上載一個。
POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}?action=initialize
屬性 | 說明 |
---|---|
{BATCH_ID} |
批的ID。 |
{DATASET_ID} |
正在接收檔案的資料集的ID。 |
{FILE_NAME} |
在資料集中看到的檔案的名稱。 |
要求
curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/part1=a/part2=b/{FILE_NAME}.parquet?action=initialize" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"
雷龐塞
#Status 201 CREATED, with empty response body
建立檔案後,可以通過重複的PATCH請求來上載所有後續的區塊,這對檔案的每個部分都是一個請求。
PATCH /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
屬性 | 說明 |
---|---|
{BATCH_ID} |
批的ID。 |
{DATASET_ID} |
要將檔案上載到的資料集的ID。 |
{FILE_NAME} |
在資料集中看到的檔案的名稱。 |
要求
curl -X PATCH "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/part1=a/part2=b/{FILE_NAME}.parquet" \
-H "content-type: application/octet-stream" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}" \
-H "Content-Range: bytes {CONTENT_RANGE}" \
--data-binary "@{FILE_PATH_AND_NAME}.parquet"
屬性 | 說明 |
---|---|
{FILE_PATH_AND_NAME} |
要上載到資料集中的檔案的路徑和檔案名。 |
雷龐塞
#Status 200 OK, with empty response
在所有檔案都上載到批後,可以發出批完成的信號。 通過這樣, Catalog 為已完成的檔案建立資料集檔案條目,並與上面生成的批關聯。 的 Catalog 然後將批處理標籤為成功,這將觸發下游流以接收可用資料。
要求
POST /batches/{BATCH_ID}?action=COMPLETE
屬性 | 說明 |
---|---|
{BATCH_ID} |
要上載到資料集的批的ID。 |
curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"
雷龐塞
#Status 200 OK, with empty response
等待檔案上載到批時,可以檢查批的狀態以查看其進度。
API格式
GET /batch/{BATCH_ID}
屬性 | 說明 |
---|---|
{BATCH_ID} |
正在檢查的批的ID。 |
要求
curl GET "https://platform.adobe.io/data/foundation/catalog/batch/{BATCH_ID}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "x-api-key: {API_KEY}"
雷龐塞
{
"{BATCH_ID}": {
"imsOrg": "{ORG_ID}",
"created": 1494349962314,
"createdClient": "MCDPCatalogService",
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}",
"updated": 1494349963467,
"externalId": "{EXTERNAL_ID}",
"status": "success",
"errors": [
{
"code": "err-1494349963436"
}
],
"version": "1.0.3",
"availableDates": {
"startDate": 1337,
"endDate": 4000
},
"relatedObjects": [
{
"type": "batch",
"id": "foo_batch"
},
{
"type": "connection",
"id": "foo_connection"
},
{
"type": "connector",
"id": "foo_connector"
},
{
"type": "dataSet",
"id": "foo_dataSet"
},
{
"type": "dataSetView",
"id": "foo_dataSetView"
},
{
"type": "dataSetFile",
"id": "foo_dataSetFile"
},
{
"type": "expressionBlock",
"id": "foo_expressionBlock"
},
{
"type": "service",
"id": "foo_service"
},
{
"type": "serviceDefinition",
"id": "foo_serviceDefinition"
}
],
"metrics": {
"foo": 1337
},
"tags": {
"foo_bar": [
"stuff"
],
"bar_foo": [
"woo",
"baz"
],
"foo/bar/foo-bar": [
"weehaw",
"wee:haw"
]
},
"inputFormat": {
"format": "parquet",
"delimiter": ".",
"quote": "`",
"escape": "\\",
"nullMarker": "",
"header": "true",
"charset": "UTF-8"
}
}
}
屬性 | 說明 |
---|---|
{USER_ID} |
建立或更新批的用戶的ID。 |
的 "status"
欄位顯示請求的批的當前狀態。 批可具有以下狀態之一:
狀態 | 說明 |
---|---|
已放棄 | 批未在預期時間範圍內完成。 |
中止 | 中止操作已 明確 已調用(通過批接收API)指定批。 一旦批處於「已載入」狀態,則無法中止該批。 |
作用中 | 批已成功升級,可用於下游衝減。 此狀態可與「成功」互換使用。 |
已刪除 | 批的資料已完全刪除。 |
已失敗 | 由錯誤配置和/或錯誤資料導致的終端狀態。 失敗批處理的資料將 不 出現。 此狀態可與「失敗」互換使用。 |
非活動 | 批已成功升級,但已還原或已過期。 批不再可用於下游衝減。 |
已載入 | 批的資料已完成,批已準備好進行升級。 |
正在載入 | 正在上載此批的資料,且該批當前正在 不 準備升職。 |
正在重試 | 正在處理此批的資料。 但是,由於系統或暫時性錯誤,批失敗 — 因此,將重試此批。 |
已轉移 | 批的升級進程的暫存階段已完成,並且已運行接收作業。 |
預備 | 正在處理批的資料。 |
停止 | 正在處理批的資料。 但是,批升級在多次重試後已停止。 |