Batch Ingestion概述

API Batch Ingestion 允许您将数据作为批处理文件引入Adobe Experience Platform。所摄取的用户档案可以是CRM系统中的平面文件（如拼花文件）中的模式数据，或符合(XDM)注册表中的已知的 Experience Data Model 数据。

数据摄取API参考，提供了有关这些API调用的其他信息。

下图概述了批摄取过程：

使用API

API Data Ingestion 允许您通过以下三个基本步骤将数据作为批处理(由一个或多个要作为单个单元摄取的文件组成的数 Experience Platform 据单元)进行：

创建新批。
将文件上传到与数据的XDM模式匹配的指定数据集。
发出批次结束的信号。

Data Ingestion 先决条件

要上传的数据必须采用Parke或JSON格式。
在中创建的数据集 Catalog services。
拼花文件的内容必须与要上传到的数据集的模式的子集匹配。
在验证后拥有您的独特访问令牌。

批摄取最佳实践

建议的批处理大小介于256 MB和100 GB之间。
每个批次最多应包含1500个文件。

要上传大于512MB的文件，需要将文件分为较小的块。此处可找到上传大型文件的说明。

读取示例API调用

本指南提供示例API调用，以演示如何格式化请求。这包括路径、必需的标头和格式正确的请求负载。还提供API响应中返回的示例JSON。有关示例API调用文档中使用的惯例的信息，请参阅疑难解答指南中有关如何阅读示例API调用 Experience Platform 一节。

收集所需标题的值

要调用API，您必 Platform 须先完成身份验证教程。完成身份验证教程可为所有API调用中的每个所需 Experience Platform 标头提供值，如下所示：

授权：承载者 {ACCESS_TOKEN}
x-api-key: {API_KEY}
x-gw-ims-org-id: {IMS_ORG}

中的所有资源 Experience Platform 都与特定虚拟沙箱隔离。对API的 Platform 所有请求都需要一个标头，它指定操作将在中进行的沙箱的名称：

x-sandbox-name: {SANDBOX_NAME}

注意

有关中沙箱的详细信 Platform息，请参阅沙箱概述文档。

所有包含有效负荷(POST、PUT、PATCH)的请求都需要附加标头：

内容类型：application/json

创建批

在将数据添加到数据集之前，必须先将其链接到批，然后再将其上传到指定的数据集。

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”调用将数据拼接到一起。

注意

以下示例使用镶木地板文件格式。使用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}`	要上载到数据集中的文件的路径和文件名。

响应

#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”（故障）交替使用。
非活动	批已成功提升，但已还原或已过期。该批不再可用于下游冲减。
已加载	批处理数据已完成，批处理已准备好进行升级。
正在加载	正在上传此批的数据，且该批当前未准备提升。
正在重试	正在处理此批的数据。但是，由于系统或临时错误，批处理失败——因此，正在重试此批处理。
已暂存	批处理的升级过程的阶段阶段已完成，并且已运行摄取作业。
暂存	正在处理批的数据。
停止	正在处理批处理的数据。但是，批次促销已在多个重试后停止。

adobe.com 上的资源

Version History Content Management Triggered Emails Lookalike Modeling Data Ingestion Cohort Analysis