本文档将帮助回答有关Adobe Experience PlatformAPI的常见问 Batch Data Ingestion 题。
来自 200 OK
API的响应意味着批处理已被接受——直到它过渡到其最终状态(如“活动”或“失败”)后,它才处于活动状态。
是——可以安全地重试API调用。 尽管失败,操作仍可能实际成功,批也可能成功接受。 但是,在API失败时,客户端应具有重试机制,实际上,会鼓励客户端重试。 如果操作实际成功,则API将返回成功,即使重试后也是如此。
使用“大文件上传API”的建议文件大小为256 MB或更大。 有关如何使用大文件上传API的更多信息,请在此 处找到。
如果发现大文件的块重叠或缺失,则服务器会使用HTTP 400错误请求做出响应。 之所以会出现这种情况,是因为可以上传重叠的块,因为在文件完成时,当文件块拼接在一起时,会执行范围验证。
目前,支持Parke和JSON。 旧版支持CSV —— 虽然数据将提升为主控,并将进行初步检查,但不支持转换、分区或行验证等现代功能。
应在有效负荷内的批量创建时指定输入格式。 有关如何指定批处理输入格式的示例如下所示:
curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
-H "accept: application/json" \
-H "x-gw-ims-org-id: {IMS_ORG}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key : {API_KEY}"
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "json"
}
}'
要使数据显示在数据集中,必须将批标记为完成。 必须先上传要收录的所有文件,然后才能将批标记为完成。 将批标记为完成的示例如下所示:
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: {IMS_ORG}' \
-H 'x-api-key : {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
要获取多行JSON, isMultiLineJson
需要在创建批时设置标志。 以下是此示例:
curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
-H "accept: application/json" \
-H "x-gw-ims-org-id: {IMS_ORG}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key : {API_KEY}"
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "json",
"isMultiLineJson": true
}
}'
对于JSON行,每行有一个JSON对象。 例如:
{"string":"string1","int":1,"array":[1,2,3],"dict": {"key": "value1"}}
{"string":"string2","int":2,"array":[2,4,6],"dict": {"key": "value2"}}
{"string":"string3","int":3,"array":[3,6,9],"dict": {"key": "value3", "extra_key": "extra_value3"}}
对于多行JSON,一个对象可以占用多行,而所有对象都打包在JSON数组中。 例如:
[
{"string":"string1","int":1,"array":[1,2,3],"dict": {"key": "value1"}},
{"string":"string2","int":2,"array":[2,4,6],"dict": {"key": "value2"}},
{
"string": "string3",
"int": 3,
"array": [
3,
6,
9
],
"dict": {
"key": "value3",
"extra_key": "extra_value3"
}
}
]
默认情况下, Batch Data Ingestion 使用单行JSON。
CSV摄取仅支持简单模式。 目前,不支持以CSV格式接收分层数据。
要获取所有数据获取功能,需要使用JSON或Parke格式。
对数据执行的验证有三个级别:
已摄取的批可以使用“批重播”功能替换。 有关批重播的更多信息,请 访问。
一旦向批发出批次升级信号,便可通过以下请求监控批次获取进度:
curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches/{BATCH_ID}" \
-H "x-gw-ims-org-id: {IMS_ORG}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key : {API_KEY}"
通过此请求,您将收到类似以下内容的响应:
200 OK
{
"{BATCH_ID}":{
"imsOrg":"{IMS_ORG}",
"created":1494349962314,
"createdClient":"{API_KEY}",
"createdUser":"{USER_ID}",
"updatedUser":"{USER_ID}",
"completed":1494349963467,
"externalId":"{EXTERNAL_ID}",
"status":"staging",
"errors":[],
}
}
批处理在其生命周期中可以经历以下状态:
状态 | 写入主控的数据 | 描述 |
---|---|---|
已放弃 | 客户端未能在预期时间范围内完成批处理。 | |
已中止 | 客户端已通过API显式 Batch Data Ingestion 调用指定批的中止操作。 一旦批处理处于“已加载”状态,则该批处理将无法中止。 | |
活动/成功 | x | 批已成功从阶段提升到主控,现在可用于下游消耗。 注意: “活动”和“成功”可互换使用。 |
已存档 | 批已存档为冷存储。 | |
失败/失败 | 由错误配置和/或错误数据导致的终端状态。 将记录可操作的错误以及批,以使客户端能够更正并重新提交数据。 注意: “失败”和“失败”可互换使用。 | |
非活动 | x | 批已成功提升,但已还原或已过期。 批处理将不再可用于下游消耗,但基础数据将保持主控,直到其被保留、存档或删除。 |
正在加载 | 客户端当前正在为批处理编写数据。 此时, 批 尚未准备好升级。 | |
已加载 | 客户端已完成为批处理写入数据。 批已准备好升级。 | |
保留 | 数据已从主控中取出,并存放在Adobe数据湖的指定存档中。 | |
暂存 | 客户端已成功发出批升级信号,数据正在暂存以在下游消耗。 | |
正在重试 | 客户端已发出批次升级的信号,但由于出错,批次正在由批次监视服务重试。 此状态可用于告知客户端在摄取数据时可能存在延迟。 | |
停止 | 客户端已发出批次升级的信号,但在 n 通过批次监控服务重试后,批次升级已停止。 |
当批处于“暂存”时,这意味着已成功发出批的升级信号,并且数据正在暂存以供下游消耗。
当批处于“重试”状态时,这意味着由于间歇性问题,该批的数据摄取已暂时停止。 当发生这种情况时,无需客户干预。
当批处于“停止”状态时,这意味着 Data Ingestion Services 在摄取该批时遇到困难,并且所有重试都已用尽。
当批处于“正在加载”中时,这意味着尚未调用CompleteBatch API来提升批。
一旦批状态为“活动”,批便被成功摄取。 要查找批的状态,请按照之前详细介绍的步 骤操作。
当批处理失败时,其失败的原因可以在有效负荷的 errors
部分中确定。 错误示例如下:
"errors":[
{
"code":"106",
"description":"Dataset file is empty. Please upload file with data.",
"rows":[]
},
{
"code":"118",
"description":"CSV file contains empty header row.",
"rows":[]
}
]
更正错误后,可以重新上传批。
批应使用以下任一方 Catalog法删除,而不是直接从中删除:
在“活动/成功”状态中,批可使用以下批级度量:
量度 | 描述 |
---|---|
inputByteSize | 要处理的暂存字节 Data Ingestion Services 总数。 |
inputRecordSize | 要处理的暂存行 Data Ingestion Services 总数。 |
outputByteSize | 输出到的字节 Data Ingestion Services 总数 Data Lake。 |
outputRecordSize | 输出到的总行 Data Ingestion Services 数 Data Lake。 |
partitionCount | 写入的分区总数 Data Lake。 |
量度可能无法在您的批中使用有两个原因:
状态代码 | 描述 |
---|---|
106 | 数据集文件为空。 |
118 | CSV文件包含空标题行。 |
200 | 批已接受处理,并将过渡到最终状态,如“活动”或“失败”。 提交后,可以使用端点监视批 GetBatch 处理。 |
400 | 错误请求. 如果批处理中缺少块或重叠块,则返回。 |