API Batch Ingestion 允许您将数据作为批处理文件引入Adobe Experience Platform。 所摄取的用户档案可以是CRM系统中的平面文件(如拼花文件)中的模式数据,或符合(XDM)注册表中的已知的 Experience Data Model 数据。
数据 摄取API参考 ,提供了有关这些API调用的其他信息。
下图概述了批摄取过程:
API Data Ingestion 允许您通过以下三个基本步骤将数据作为批处理(由一个或多个要作为单个单元摄取的文件组成的数 Experience Platform 据单元)进行:
要上传大于512MB的文件,需要将文件分为较小的块。 此处可找到上传大型文件的 说明。
本指南提供示例API调用,以演示如何格式化请求。 这包括路径、必需的标头和格式正确的请求负载。 还提供API响应中返回的示例JSON。 有关示例API调用文档中使用的惯例的信息,请参阅疑难解答 指南中有关如何阅读示例API调 用 Experience Platform 一节。
要调用API,您必 Platform 须先完成身份验证 教程。 完成身份验证教程可为所有API调用中的每个所需 Experience Platform 标头提供值,如下所示:
{ACCESS_TOKEN}
{API_KEY}
{IMS_ORG}
中的所有资源 Experience Platform 都与特定虚拟沙箱隔离。 对API的 Platform 所有请求都需要一个标头,它指定操作将在中进行的沙箱的名称:
{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。 |
响应
{
"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”调用将数据拼接到一起。
创建批后,数据即可上传到预先存在的数据集。 要上传的文件必须与其引用的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} |
要上载到数据集中的文件的路径和文件名。 |
响应
#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}"
响应
#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} |
要上载到数据集中的文件的路径和文件名。 |
响应
#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}"
响应
#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}"
响应
{
"{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"
段显示请求的批的当前状态。 这些批可以具有以下状态之一:
状态 | 描述 |
---|---|
已放弃 | 批未在预期时间范围内完成。 |
已中止 | 已为指定 批 显式调用(通过Batch Ingest API)中止操作。 批处理处于“已加载”状态后,将无法中止它。 |
活动 | 批已成功提升,可用于下游冲减。 此状态可与“成功”交替使用。 |
已删除 | 批处理数据已完全删除。 |
失败 | 由错误配置和/或错误数据导致的终端状态。 失败批处理的数 据将 不显示。 此状态可与“Failure”(故障)交替使用。 |
非活动 | 批已成功提升,但已还原或已过期。 该批不再可用于下游冲减。 |
已加载 | 批处理数据已完成,批处理已准备好进行升级。 |
正在加载 | 正在上传此批的数据,且该批当前 未 准备提升。 |
正在重试 | 正在处理此批的数据。 但是,由于系统或临时错误,批处理失败——因此,正在重试此批处理。 |
已暂存 | 批处理的升级过程的阶段阶段已完成,并且已运行摄取作业。 |
暂存 | 正在处理批的数据。 |
停止 | 正在处理批处理的数据。 但是,批次促销已在多个重试后停止。 |