流式摄取验证

流式摄取允许您使用流式端点实时将数据上传到Adobe Experience Platform。 流摄取API支持两种验证模式 — 同步和异步。

快速入门

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

• Experience Data Model (XDM) System:用于组织客户体验数 Experience Platform 据的标准化框架。
• Streaming Ingestion:将数据发送到的方法之 Experience Platform一。

读取示例API调用

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

收集所需标题的值

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

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

Experience Platform中的所有资源（包括属于Schema Registry的资源）都与特定虚拟沙箱隔离。 对Platform API的所有请求都需要一个标头来指定操作将在其中进行的沙盒的名称：

• x-sandbox-name: {SANDBOX_NAME}

所有包含有效负载(POST、PUT、PATCH)的请求都需要额外的标头：

• Content-Type: application/json

验证范围

Streaming Validation Service 涵盖以下方面的验证：

• Range
• 存在
• 枚举
• 图案
• 类型
• 格式

同步验证

同步验证是一种验证方法，可提供有关摄取失败原因的即时反馈。 但是，失败时，验证失败的记录会被丢弃，并阻止下游发送。 因此，只应在开发过程中使用同步验证。 进行同步验证时，将通知呼叫者XDM验证的结果，如果验证失败，则还将告知失败原因。

默认情况下，不会打开同步验证。 要启用此函数，在进行API调用时必须传入可选查询参数syncValidation=true。 此外，当前，仅当流端点位于VA7数据中心时，才可使用同步验证。

如果消息在同步验证期间失败，则消息将不会写入输出队列，从而为用户提供即时反馈。

API格式

POST /collection/{CONNECTION_ID}?syncValidation=true

请求

提交以下请求以通过同步验证将数据摄取到数据入口：

curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID}?syncValidation=true \
  -H "Content-Type: application/json" \
  -d '{JSON_PAYLOAD}'

响应

启用同步验证后，成功响应的有效负载中包含遇到的任何验证错误：

{
    "type": "http://ns.adobe.com/adobecloud/problem/data-collection-service/inlet",
    "status": 400,
    "title": "Invalid XDM Message Format",
    "report": {
        "message": "inletId: [6aca7aa2d87ebd6b2780ca5724d94324a14475f140a2b69373dd5c714430dfd4] imsOrgId: [7BF122A65C5B3FE40A494026@AdobeOrg] Message is invalid",
        "cause": {
            "_streamingValidation": [
                {
                    "schemaLocation": "#",
                    "pointerToViolation": "#",
                    "causingExceptions": [
                        {
                            "schemaLocation": "#",
                            "pointerToViolation": "#",
                            "causingExceptions": [],
                            "keyword": "additionalProperties",
                            "message": "extraneous key [workEmail] is not permitted"
                        },
                        {
                            "schemaLocation": "#",
                            "pointerToViolation": "#",
                            "causingExceptions": [],
                            "keyword": "additionalProperties",
                            "message": "extraneous key [person] is not permitted"
                        },
                        {
                            "schemaLocation": "#/properties/_id",
                            "pointerToViolation": "#/_id",
                            "causingExceptions": [],
                            "keyword": "type",
                            "message": "expected type: String, found: Long"
                        }
                    ],
                    "message": "3 schema violations found"
                }
            ]
        }
    }
}

上述响应列出了发现的架构违规数量以及违规的数量。 例如，此响应声明未在架构中定义键workEmail和person，因此不允许使用。 它还会将_id的值标记为不正确，因为架构应为string，而是插入了long。 请注意，在遇到五个错误后，验证服务将​停止​处理该消息。 但是，其他消息将继续进行解析。

异步验证

异步验证是一种不提供即时反馈的验证方法。 相反，会将数据发送到Data Lake中的失败批次，以防止数据丢失。 稍后可以检索此失败数据，以便进一步分析和重播。 此方法应用于生产中。 除非另有请求，否则流摄取在异步验证模式下运行。

API格式

POST /collection/{CONNECTION_ID}

请求

通过异步验证提交以下请求，将数据摄取到数据入口：

curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID} \
  -H "Content-Type: application/json" \
  -d '{JSON_PAYLOAD}'

响应

启用异步验证后，成功的响应会返回以下内容：

{
    "inletId": "f6ca9706d61de3b78be69e2673ad68ab9fb2cece0c1e1afc071718a0033e6877",
    "xactionId": "1555445493896:8600:8",
    "receivedTimeMs": 1555445493932,
    "syncValidation": {
        "skipped": true
    }
}

请注意响应如何声明已跳过同步验证，因为尚未明确请求同步验证。

附录

本节包含有关各种状态代码对于摄取数据的响应意味着什么的信息。

状态代码