检索数据摄取错误诊断

Adobe Experience Platform提供两种上传和摄取数据的方法。 您可以使用批量摄取,这允许您使用各种文件类型(如CSV)插入数据;也可以使用流式摄取,这允许您使用流式端点实时将其数据插入到Platform。

本文档提供了有关监控批次摄取、管理部分批次摄取错误的信息,以及部分批次摄取类型的参考。

快速入门

本指南要求您对 Adobe Experience Platform 的以下组件有一定了解:

正在读取示例 API 调用

本教程提供了示例API调用来演示如何格式化请求。 这些包括路径、必需的标头和格式正确的请求负载。还提供了在 API 响应中返回的示例 JSON。有关示例API调用文档中使用的约定的信息,请参阅Experience Platform疑难解答指南中有关如何读取示例API调用的部分。

收集所需标头的值

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

  • Authorization: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {ORG_ID}

Experience Platform中的所有资源(包括属于Schema Registry的资源)都被隔离到特定的虚拟沙盒中。 对Platform API的所有请求都需要一个标头,用于指定将在其中执行操作的沙盒的名称:

  • x-sandbox-name: {SANDBOX_NAME}
NOTE
有关Platform中沙盒的更多信息,请参阅沙盒概述文档

正在下载错误诊断 download-diagnostics

Adobe Experience Platform允许用户下载输入文件的错误诊断。 诊断将在Platform内保留最多30天。

列出输入文件 list-files

以下请求检索在最终确定的批次中提供的所有文件的列表。

API格式

GET /batches/{BATCH_ID}/meta?path=input_files
属性
描述
{BATCH_ID}
要查找的批次的ID。

请求

curl -X GET https://platform.adobe.io/data/foundation/export/batches/af838510-2233-11ea-acf0-f3edfcded2d2/meta?path=input_files \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

响应

成功的响应将返回JSON对象,该对象详细说明诊断的保存位置。

{
    "_page": {
        "count": 1,
        "limit": 100
    },
    "data": [
        {
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io/data/foundation/export/batches/af838510-2233-11ea-acf0-f3edfcded2d2/meta?path=input_files/fileMetaData1.json"
                }
            },
            "length": "1337",
            "name": "fileMetaData1.json"
        },
                {
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io/data/foundation/export/batches/af838510-2233-11ea-acf0-f3edfcded2d2}/meta?path=input_files/fileMetaData2.json"
                }
            },
            "length": "1042",
            "name": "fileMetaData2.json"
        }
    ]
}

检索输入文件诊断 retrieve-diagnostics

检索完所有不同输入文件的列表后,可以使用以下请求检索单个文件的诊断。

API格式

GET /batches/{BATCH_ID}/meta?path=input_files/{FILE}
属性
描述
{BATCH_ID}
要查找的批次的ID。
{FILE}
您正在访问的文件的名称。

请求

curl -X GET https://platform.adobe.io/data/foundation/export/batches/af838510-2233-11ea-acf0-f3edfcded2d2/meta?path=input_files/fileMetaData1.json \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

响应

成功的响应将返回包含path个对象的JSON对象,这些对象详细说明诊断的保存位置。 响应将返回JSON行格式的path对象。

{"path": "F1.json"}
{"path": "etc/F2.json"}

检索批次摄取错误 retrieve-errors

如果批次包含失败,您应该检索有关这些失败的错误信息,以便重新摄取数据。

检查状态 check-status

要检查摄取的批的状态,必须在GET请求路径中提供批的ID。 要了解有关使用此API调用的更多信息,请阅读目录终结点指南

API格式

GET /catalog/batches/{BATCH_ID}
GET /catalog/batches/{BATCH_ID}?{FILTER}
参数
描述
{BATCH_ID}
要检查其状态的批次的id值。
{FILTER}
用于筛选响应中返回结果的查询参数。 多个参数由&符号(&)分隔。 有关详细信息,请阅读筛选目录数据的指南。

请求

curl -X GET https://platform.adobe.io/data/foundation/catalog/batches/af838510-2233-11ea-acf0-f3edfcded2d2 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

没有错误的响应

成功的响应将返回,其中包含有关批次状态的详细信息。

{
    "af838510-2233-11ea-acf0-f3edfcded2d2": {
        "status": "success",
        "tags": {
            "acp_enableErrorDiagnostics": true,
            "acp_partialIngestionPercent": 5
        },
        "relatedObjects": [
            {
                "type": "dataSet",
                "id": "5deac2648a19d218a888d2b1"
            }
        ],
        "id": "af838510-2233-11ea-acf0-f3edfcded2d2",
        "externalId": "af838510-2233-11ea-acf0-f3edfcded2d2",
        "inputFormat": {
            "format": "parquet"
        },
        "imsOrg": "{ORG_ID}",
        "started": 1576741718543,
        "metrics": {
            "inputByteSize": 568,
            "inputFileCount": 4,
            "inputRecordCount": 519,
            "outputRecordCount": 497,
            "failedRecordCount": 0
        },
        "completed": 1576741722026,
        "created": 1576741597205,
        "createdClient": "{API_KEY}",
        "createdUser": "{USER_ID}",
        "updatedUser": "{USER_ID}",
        "updated": 1576741722644,
        "version": "1.0.5"
    }
}
属性
描述
metrics.failedRecordCount
由于解析、转换或验证而无法处理的行数。 此值可以通过从outputRecordCount中减去inputRecordCount而派生。 此值在所有批次中生成,无论是否启用了errorDiagnostics

带有错误的响应

如果批次具有一个或多个错误并启用了错误诊断,则响应将返回有关错误的更多信息,这些信息既存在于有效负荷中,也存在于可下载的错误文件中。 请注意,包含错误的批次的状态可能仍具有成功状态。

{
    "01E8043CY305K2MTV5ANH9G1GC": {
        "status": "success",
        "tags": {
            "acp_enableErrorDiagnostics": true,
            "acp_partialIngestionPercent": 5
        },
        "relatedObjects": [
            {
                "type": "dataSet",
                "id": "5deac2648a19d218a888d2b1"
            }
        ],
        "id": "01E8043CY305K2MTV5ANH9G1GC",
        "externalId": "01E8043CY305K2MTV5ANH9G1GC",
        "inputFormat": {
            "format": "parquet"
        },
        "imsOrg": "{ORG_ID}",
        "started": 1576741718543,
        "metrics": {
            "inputByteSize": 568,
            "inputFileCount": 4,
            "inputRecordCount": 519,
            "outputRecordCount": 514,
            "failedRecordCount": 5
        },
        "completed": 1576741722026,
        "created": 1576741597205,
        "createdClient": "{API_KEY}",
        "createdUser": "{USER_ID}",
        "updatedUser": "{USER_ID}",
        "updated": 1576741722644,
        "version": "1.0.5",
        "errors": [
           {
             "code": "INGEST-1212-400",
             "description": "Encountered 5 errors in the data. Successfully ingested 514 rows. Please review the associated diagnostic files for more details."
           },
           {
             "code": "INGEST-1401-400",
             "description": "The row has corrupted data and cannot be read or parsed. Fix the corrupted data and try again.",
             "recordCount": 2
           },
           {
             "code": "INGEST-1555-400",
             "description": "A required field is either missing or has a value of null. Add the required field to the input row and try again.",
             "recordCount": 3
           }
        ]
    }
}
属性
描述
metrics.failedRecordCount
由于解析、转换或验证而无法处理的行数。 此值可以通过从outputRecordCount中减去inputRecordCount而派生。 此值在所有批次中生成,无论是否启用了errorDiagnostics
errors.recordCount
因指定的错误代码而失败的行数。 如果启用了errorDiagnostics,则只生成​ 1}值。
NOTE
如果错误诊断不可用,则会显示以下错误消息:
code language-json
{
       "errors": [{
               "code": "INGEST-1211-400",
               "description": "Encountered errors while parsing, converting or otherwise validating the data. Please resend the data with error diagnostics enabled to collect additional information on failure types"
       }]
}

后续步骤 next-steps

本教程介绍了如何监测部分批次摄取错误。 有关批量摄取的更多信息,请阅读批量摄取开发人员指南

附录 appendix

本节提供有关摄取错误类型的补充信息。

部分批次摄取错误类型 partial-ingestion-types

摄取数据时,部分批次摄取具有三种不同的错误类型:

无法读取的文件 unreadable

如果摄取的批次具有不可读的文件,则批次的错误将附加到批次本身。 有关检索失败的批次的详细信息,请参阅检索失败的批次指南

架构或标头无效 schemas-headers

如果摄取的批次具有无效架构或无效标头,则批次的错误将附加到批次本身。 有关检索失败的批次的详细信息,请参阅检索失败的批次指南

无法分析的行 unparsable

如果您摄取的批处理包含不可分析的行,则可以使用以下请求查看包含错误的文件列表。

API格式

GET /export/batches/{BATCH_ID}/meta?path=row_errors
参数
描述
{BATCH_ID}
正在从中检索错误信息的批次的id值。

请求

curl -X GET https://platform.adobe.io/data/foundation/export/batches/01EFZ7W203PEKSAMVJC3X99VHQ/meta?path=row_errors \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

响应

成功的响应会返回包含错误的文件列表。

{
    "data": [
        {
            "name": "conversion_errors_0.json",
            "length": "1162",
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io:443/data/foundation/export/batches/01EFZ7W203PEKSAMVJC3X99VHQ/meta?path=row_errors%2Fconversion_errors_0.json"
                }
            }
        },
        {
            "name": "parsing_errors_0.json",
            "length": "153",
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io:443/data/foundation/export/batches/01EFZ7W203PEKSAMVJC3X99VHQ/meta?path=row_errors%2Fparsing_errors_0.json"
                }
            }
        }
    ],
    "_page": {
        "limit": 100,
        "count": 2
    }
}

然后,可以使用诊断检索终结点检索有关错误的详细信息。

检索错误文件的示例响应如下所示:

{
    "_corrupt_record": "{missingQuotes: 'v1'}",
    "_errors": [{
        "code": "1401",
        "message": "Row is corrupted and cannot be read, please fix and resend."
    }],
    "_filename": "parsing_errors_0.json"
}
recommendation-more-help
2ee14710-6ba4-4feb-9f79-0aad73102a9a