Adobe Experience Platform Data Ingestion API可讓您將資料以批次檔案的形式內嵌至Platform。 所吸收的資料可以是CRM系統中平面檔案(例如Parce檔案)的描述檔資料,或符合Experience Data Model (XDM)註冊表中已知架構的資料。
資料擷取API參考提供這些API呼叫的其他資訊。
下圖概述了批處理過程:
Data Ingestion API可讓您透過三個基本步驟,將資料內嵌為批次(由一或多個要以單一單位收錄的檔案組成的資料單位)至Experience Platform:
若要上傳大於512MB的檔案,檔案必須分成較小的區塊。 有關上傳大型檔案的說明,請參閱此處。
本指南提供範例API呼叫,以示範如何格式化您的請求。 這些包括路徑、必要標題和正確格式化的請求負載。 也提供API回應中傳回的範例JSON。 如需範例API呼叫檔案中所用慣例的詳細資訊,請參閱Experience Platform疑難排解指南中如何讀取範例API呼叫一節。
若要呼叫Platform API,您必須先完成驗證教學課程。 完成驗證教學課程後,所有Experience Platform API呼叫中每個所需標題的值都會顯示在下面:
{ACCESS_TOKEN}
{API_KEY}
{IMS_ORG}
Experience Platform中的所有資源都隔離到特定的虛擬沙盒。 對Platform API的所有請求都需要一個標題,該標題指定要在中執行操作的沙盒的名稱:
{SANDBOX_NAME}
如需Platform中沙盒的詳細資訊,請參閱沙盒概述檔案。
所有包含裝載(POST、PUT、PATCH)的請求都需要額外的標題:
資料必須連結至批次,之後才會上傳至指定的資料集,才能將資料新增至資料集。
POST /batches
請求
curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
-H "Content-Type: application/json" \
-H "x-gw-ims-org-id: {IMS_ORG}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key : {API_KEY}"
-d '{
"datasetId": "{DATASET_ID}"
}'
屬性 | 說明 |
---|---|
datasetId |
上傳檔案至的資料集ID。 |
Reponse
{
"id": "{BATCH_ID}",
"imsOrg": "{IMS_ORG}",
"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」呼叫將資料連結在一起。
以下示例使用Apache Parce檔案格式。 使用JSON檔案格式的範例,請參閱批次擷取開發人員指南。
建立批次後,資料就可以上傳至預先存在的資料集。 上傳的檔案必須符合其參考的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: {IMS_ORG}" \
-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} |
要上傳至資料集的檔案路徑和檔案名稱。 |
Reponse
#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: {IMS_ORG}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"
Reponse
#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: {IMS_ORG}" \
-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} |
要上傳至資料集的檔案路徑和檔案名稱。 |
Reponse
#Status 200 OK, with empty response
將所有檔案上傳到批後,可以向批發出完成信號。 通過執行此操作,將為已完成的檔案建立Catalog DataSetFile條目,並與上面生成的批關聯。 然後,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: {IMS_ORG}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key : {API_KEY}"
Reponse
#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: {IMS_ORG}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "x-api-key: {API_KEY}"
Reponse
{
"{BATCH_ID}": {
"imsOrg": "{IMS_ORG}",
"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)。 一旦批處於「已載入」狀態,便無法中止。 |
作用中 | 批已成功升級,可用於下游衝減。 此狀態可與「成功」交替使用。 |
已刪除 | 批次的資料已完全移除。 |
已失敗 | 由錯誤配置和/或錯誤資料引起的終端狀態。 失敗批次的資料將顯示not。 此狀態可與「故障」交替使用。 |
非活動 | 批已成功升級,但已還原或已過期。 批不再可用於下游衝減。 |
已載入 | 批的資料已完成,批已準備好進行升級。 |
正在載入 | 正在上載此批的資料,且該批當前not已準備升級。 |
重試 | 正在處理此批的資料。 但是,由於系統或瞬態錯誤,批次失敗——因此,正在重試此批次。 |
已分段 | 批的升級流程的轉移階段已完成,並且已運行提取作業。 |
預備 | 正在處理批的資料。 |
停止 | 正在處理批的資料。 不過,批次促銷在多次重試後已停止。 |