批次擷取開發人員指南
本檔案提供使用的完整指南 批次擷取API端點 在Adobe Experience Platform中。 如需批次擷取API的概觀,包括先決條件和最佳實務,請從閱讀 批次擷取API概觀.
本檔案的附錄提供以下專案的資訊: 格式化要用於內嵌的資料,包括範例CSV和JSON資料檔案。
快速入門
本指南中使用的API端點屬於 批次擷取API. 批次擷取是透過RESTful API提供,您可以在其中對支援的物件型別執行基本CRUD操作。
內嵌JSON檔案
建立批次
首先,您需要以JSON作為輸入格式建立批次。 建立批次時,您需要提供資料集ID。 您還需要確保批次中上傳的所有檔案都符合連結到所提供資料集的XDM結構。
isMultiLineJson
需要設定標幟。 如需詳細資訊,請閱讀 批次擷取疑難排解指南.API格式
POST /batches
要求
curl -X POST https://platform.adobe.io/data/foundation/import/batches \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "json"
}
}'
{DATASET_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}"
}
{BATCH_ID}
{DATASET_ID}
上傳檔案
現在您已建立批次,您可以使用批次建立回應中的批次ID來上傳檔案至批次。 您可以將多個檔案上傳至批次。
API格式
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
要求
curl -X PUT https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.json \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'content-type: application/octet-stream' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.json"
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.json
.回應
200 OK
完成批次
完成上傳檔案的所有不同部分後,您需要指出資料已完全上傳,且批次已準備好進行升級。
API格式
POST /batches/{BATCH_ID}?action=COMPLETE
{BATCH_ID}
要求
curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
回應
200 OK
擷取Parquet檔案 ingest-parquet-files
建立批次
首先,您需要建立批次,以Parquet作為輸入格式。 建立批次時,您需要提供資料集ID。 您還需要確保批次中上傳的所有檔案都符合連結到所提供資料集的XDM結構。
要求
curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-api-key: {API_KEY}" \
-H "x-sandbox-name: {SANDBOX_NAME}"
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "parquet"
}
}'
{DATASET_ID}
回應
201 Created
{
"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}"
}
{BATCH_ID}
{DATASET_ID}
{USER_ID}
上傳檔案
現在您已建立批次,您可以使用 batchId
從之前將檔案上傳至批次。 您可以將多個檔案上傳至批次。
API格式
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
要求
curl -X PUT https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/octet-stream' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.parquet"
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.parquet
.回應
200 OK
完成批次
完成上傳檔案的所有不同部分後,您需要指出資料已完全上傳,且批次已準備好進行升級。
API格式
POST /batches/{BATCH_ID}?action=complete
{BATCH_ID}
要求
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
回應
200 OK
擷取大型Parquet檔案
建立批次
首先,您需要建立批次,以Parquet作為輸入格式。 建立批次時,您需要提供資料集ID。 您還需要確保批次中上傳的所有檔案都符合連結到所提供資料集的XDM結構。
API格式
POST /batches
要求
curl -X POST https://platform.adobe.io/data/foundation/import/batches \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "parquet"
}
}'
{DATASET_ID}
回應
201 Created
{
"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}"
}
{BATCH_ID}
{DATASET_ID}
{USER_ID}
初始化大型檔案
建立批次後,您必須先初始化大型檔案,才能將區塊上傳至批次。
API格式
POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
要求
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet?action=INITIALIZE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
回應
201 Created
上傳大型檔案區塊
現在檔案已建立,您可以透過進行重複的PATCH請求(檔案的每個區段各一個)來上傳所有後續區塊。
API格式
PATCH /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
要求
curl -X PATCH https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/octet-stream' \
-H 'Content-Range: bytes {CONTENT_RANGE}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.parquet"
{CONTENT_RANGE}
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.json
.回應
200 OK
完成大型檔案
現在您已建立批次,您可以使用 batchId
從之前將檔案上傳至批次。 您可以將多個檔案上傳至批次。
API格式
POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
要求
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet?action=COMPLETE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
回應
201 Created
完成批次
完成上傳檔案的所有不同部分後,您需要指出資料已完全上傳,且批次已準備好進行升級。
API格式
POST /batches/{BATCH_ID}?action=COMPLETE
{BATCH_ID}
要求
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
回應
200 OK
擷取CSV檔案
若要內嵌CSV檔案,您需要建立支援CSV的類別、結構描述和資料集。 如需如何建立必要類別和結構的詳細資訊,請依照 隨選結構描述建立教學課程.
建立資料集
依照上述指示建立必要的類別和結構描述後,您需要建立可支援CSV的資料集。
API格式
POST /catalog/dataSets
要求
curl -X POST https://platform.adobe.io/data/foundation/catalog/dataSets \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"name": "{DATASET_NAME}",
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed+json;version=1"
}
}'
{TENANT_ID}
{SCHEMA_ID}
建立批次
接下來,您需要以CSV作為輸入格式來建立批次。 建立批次時,您需要提供資料集ID。 您還需要確保批次中上傳的所有檔案都與連結至所提供資料集的結構描述相符。
API格式
POST /batches
要求
curl -X POST https://platform.adobe.io/data/foundation/import/batches \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "csv"
}
}'
{DATASET_ID}
回應
201 Created
{
"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}"
}
{BATCH_ID}
{DATASET_ID}
{USER_ID}
上傳檔案
現在您已建立批次,您可以使用 batchId
從之前將檔案上傳至批次。 您可以將多個檔案上傳至批次。
API格式
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
要求
curl -X PUT https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.csv \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/octet-stream' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.csv"
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.csv
.回應
200 OK
完成批次
完成上傳檔案的所有不同部分後,您需要指出資料已完全上傳,且批次已準備好進行升級。
API格式
POST /batches/{BATCH_ID}?action=COMPLETE
要求
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
回應
200 OK
取消批次
批次處理期間,仍可取消。 不過,一旦批次完成(例如成功或失敗狀態),就無法取消批次。
API格式
POST /batches/{BATCH_ID}?action=ABORT
{BATCH_ID}
要求
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=ABORT \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
回應
200 OK
刪除批次 delete-a-batch
您可以使用執行以下POST請求來刪除批次 action=REVERT
您要刪除之批次識別碼的查詢引數。 該批次被標籤為「非使用中」,因此符合垃圾收集的條件。 系統會以非同步方式收集批次,並標示為「已刪除」。
API格式
POST /batches/{BATCH_ID}?action=REVERT
{BATCH_ID}
要求
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=REVERT \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
回應
200 OK
修補批次
有時候,您可能需要更新組織設定檔存放區中的資料。 例如,您可能需要更正記錄或變更屬性值。 Adobe Experience Platform支援透過更新插入動作或「修補批次」來更新或修補設定檔存放區資料。
若要修補批次,需要下列專案:
- 已啟用設定檔和屬性更新的資料集。 這是透過資料集標籤完成的,並需要特定
isUpsert:true
標籤已新增至unifiedProfile
陣列。 如需詳細步驟,說明如何建立資料集或設定現有資料集以進行更新,請遵循的教學課程 為設定檔更新啟用資料集. - 包含要修補的欄位和設定檔的身分欄位的Parquet檔案。 修補批次的資料格式與一般批次擷取程式類似。 需要的輸入是Parquet檔案,除了要更新的欄位外,上傳的資料必須包含身分欄位,以便與設定檔存放區中的資料相符。
一旦您為Profile和upsert啟用了資料集,並且有一個Parquet檔案,其中包含您要修補的欄位以及必要的身分識別欄位,您可以遵循以下步驟 擷取Parquet檔案 以透過批次擷取完成修補程式。
重播批次
如果您想要取代已擷取的批次,可以使用「批次重播」來進行 — 此動作等同於刪除舊批次並擷取新批次。
建立批次
首先,您需要以JSON作為輸入格式建立批次。 建立批次時,您需要提供資料集ID。 您還需要確保批次中上傳的所有檔案都符合連結到所提供資料集的XDM結構。 此外,您還需要在重播區段中提供舊批次作為參考。 在下列範例中,您正在使用ID重播批次 batchIdA
和 batchIdB
.
API格式
POST /batches
要求
curl -X POST https://platform.adobe.io/data/foundation/import/batches \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "json"
},
"replay": {
"predecessors": ["${batchIdA}","${batchIdB}"],
"reason": "replace"
}
}'
{DATASET_ID}
回應
201 Created
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"replay": {
"predecessors": [
"batchIdA", "batchIdB"
],
"reason": "replace"
},
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
{BATCH_ID}
{DATASET_ID}
{USER_ID}
上傳檔案
現在您已建立批次,您可以使用 batchId
從之前將檔案上傳至批次。 您可以將多個檔案上傳至批次。
API格式
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
要求
curl -X PUT https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.json \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/octet-stream' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.json"
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.json
.回應
200 OK
完成批次
完成上傳檔案的所有不同部分後,您需要指出資料已完全上傳,且批次已準備好進行升級。
API格式
POST /batches/{BATCH_ID}?action=COMPLETE
{BATCH_ID}
要求
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
回應
200 OK
附錄
下節包含使用批次擷取以Experience Platform擷取資料的其他資訊。
批次擷取的資料轉換
為了將資料檔案擷取到 Experience Platform,檔案的階層結構必須符合 體驗資料模型(XDM) 與上傳目標資料集相關聯的結構描述。
有關如何對應CSV檔案以符合XDM結構的資訊,請參閱 範例轉換 以及正確格式化的JSON資料檔案的範例。 檔案中提供的範例檔案可在此處找到: