流式摄取验证
流式摄取允许您使用流式端点实时将数据上传到Adobe Experience Platform。 流式引入API支持两种验证模式 — 同步和异步。
快速入门
本指南要求您对Adobe Experience Platform的以下组件有一定的了解:
- Experience Data Model (XDM) System:用于实现此目标的标准化框架 Experience Platform 组织客户体验数据。
- Streaming Ingestion:将数据发送到的方法之一 Experience Platform.
正在读取示例API调用
本教程提供了示例API调用来演示如何设置请求的格式。 这些资源包括路径、必需的标头和格式正确的请求负载。 此外,还提供了在API响应中返回的示例JSON。 有关示例API调用文档中使用的约定的信息,请参阅以下章节: 如何读取示例API调用 在 Experience Platform 疑难解答指南。
收集所需标题的值
为了调用 Platform API,您必须先完成 身份验证教程. 完成身份验证教程将提供所有中所有所需标头的值 Experience Platform API调用,如下所示:
- 授权:持有者
{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}
包含有效负载(POST、PUT、PATCH)的所有请求都需要额外的标头:
- Content-Type:
application/json
验证范围
Streaming Validation Service 包括以下方面的验证:
- Range
- 存在
- 枚举
- 图案
- 类型
- 格式
同步验证
同步验证是一种验证方法,可立即反馈引入失败的原因。 但是,失败时,将丢弃验证失败的记录并阻止将其发送到下游。 因此,应仅在开发过程中使用同步验证。 在执行同步验证时,会向调用方通知XDM验证的结果,如果验证失败,还会告知失败的原因。
默认情况下,不会启用同步验证。 要启用此功能,您必须传入可选查询参数 syncValidation=true
进行API调用时。 此外,当前仅当您的流端点位于VA7数据中心上时,同步验证才可用。
syncValidation
查询参数仅适用于单个消息端点,不能用于批处理端点。如果消息在同步验证过程中失败,则不会将该消息写入输出队列,这会立即向用户提供反馈。
API格式
POST /collection/{CONNECTION_ID}?syncValidation=true
{CONNECTION_ID}
id
之前创建的流连接的值。请求
提交以下请求,通过同步验证将数据摄取到数据入口:
curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID}?syncValidation=true \
-H "Content-Type: application/json" \
-d '{JSON_PAYLOAD}'
{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}
{CONNECTION_ID}
id
之前创建的流连接的值。请求
提交以下请求,通过异步验证将数据摄取到您的数据入口:
curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID} \
-H "Content-Type: application/json" \
-d '{JSON_PAYLOAD}'
{JSON_PAYLOAD}
响应
启用异步验证后,成功响应将返回以下内容:
{
"inletId": "f6ca9706d61de3b78be69e2673ad68ab9fb2cece0c1e1afc071718a0033e6877",
"xactionId": "1555445493896:8600:8",
"receivedTimeMs": 1555445493932,
"syncValidation": {
"skipped": true
}
}
请注意,响应中如何声明已跳过同步验证,因为未明确请求同步验证。
附录
本节包含有关各种状态代码对摄取数据的响应有何含义的信息。