通过流式分段近乎实时地评估事件
流式分段于 Adobe Experience Platform 允许客户近乎实时地执行分段,同时专注于数据丰富度。 借助流式分段,现在当流式数据进入时,就会进行区段鉴别 Platform,从而无需安排和运行分段作业。 借助此功能,现在可以在将数据传递到时评估大多数区段规则 Platform,这意味着区段会员资格将保持最新,而无需运行计划的分段作业。
快速入门
本开发人员指南要求您实际了解各种 Adobe Experience Platform 流分段涉及的服务。 在开始本教程之前,请查看以下服务的文档:
- Real-Time Customer Profile:根据来自多个源的汇总数据,实时提供统一的用户配置文件。
- Segmentation:提供使用区段定义和其他外部源从创建受众的功能 Real-Time Customer Profile 数据。
- Experience Data Model (XDM):用于实现此目标的标准化框架 Platform 组织客户体验数据。
以下部分提供成功调用时需要了解的其他信息 Platform API。
正在读取示例 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 被隔离到特定的虚拟沙盒中。 所有请求 Platform API需要一个标头,该标头应指定将在其中执行操作的沙盒的名称:
- x-sandbox-name:
{SANDBOX_NAME}
包含负载 (POST、PUT、PATCH) 的所有请求都需要额外的标头:
- Content-Type: application/json
可能需要其他标头才能完成特定请求。 正确的标题显示在本文档的每个示例中。 请特别注意示例请求,以确保包括所有必需的标头。
支持流式分段的查询类型 query-types
为了使用流式分段评估区段定义,查询必须符合以下准则。
区段定义将 非 在以下场景中启用流式分段:
- 区段定义包括Adobe Audience Manager (AAM)区段或特征。
- 区段定义包括多个实体(多实体查询)。
- 区段定义包括单个事件和
inSegment
事件。- 然而,倘分部包含在
inSegment
事件仅用于配置文件,区段定义 将 启用流式客户细分。
- 然而,倘分部包含在
请注意,在进行流式分段时适用以下准则:
- 回看窗口限制为 一天.
- 严格的时间排序条件 必须 存在于事件之间。
- 支持至少具有一个否定事件的查询。 但是,整个事件 无法 是一种否定。
如果修改了区段定义以使其不再满足流式分段标准,则区段定义将自动从“流式处理”切换到“批处理”。
此外,区段取消资格(与区段资格类似)是实时发生的。 因此,如果配置文件不再符合区段定义的条件,它将被立即取消资格。 例如,如果区段定义要求“过去三小时内购买红鞋的所有用户”,则在三小时后,最初符合区段定义条件的所有用户档案都将被取消资格。
检索为流式分段启用的所有区段定义
您可以通过对以下网站发出GET请求,检索您的组织中启用流式分段的所有区段定义的列表: /segment/definitions
端点。
API格式
要检索启用流的区段定义,必须包含查询参数 evaluationInfo.continuous.enabled=true
在请求路径中。
GET /segment/definitions?evaluationInfo.continuous.enabled=true
请求
curl -X GET \
'https://platform.adobe.io/data/core/ups/segment/definitions?evaluationInfo.continuous.enabled=true' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
响应
成功的响应会返回组织中启用流式分段的一系列区段定义。
{
"segments": [
{
"id": "15063cb-2da8-4851-a2e2-bf59ddd2f004",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 30,
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "",
"sandboxName": "",
"type": "production",
"default": true
},
"name": " People who are NOT on their homepage ",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = false"
},
"evaluationInfo": {
"batch": {
"enabled": false
},
"continuous": {
"enabled": true
},
"synchronous": {
"enabled": false
}
},
"creationTime": 1572029711000,
"updateEpoch": 1572029712000,
"updateTime": 1572029712000
},
{
"id": "f15063cb-2da8-4851-a2e2-bf59ddd2f004",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 30,
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "",
"sandboxName": "",
"type": "production",
"default": true
},
"name": "Homepage_continuous",
"description": "People who are on their homepage - continuous",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
},
"evaluationInfo": {
"batch": {
"enabled": true
},
"continuous": {
"enabled": true
},
"synchronous": {
"enabled": false
}
},
"creationTime": 1572021085000,
"updateEpoch": 1572021086000,
"updateTime": 1572021086000
}
],
"page": {
"totalCount": 2,
"totalPages": 1,
"sortField": "creationTime",
"sort": "desc",
"pageSize": 2,
"limit": 100
},
"link": {}
}
创建支持流的区段定义
如果区段定义与以下项之一匹配,则该区段定义将自动启用流式处理: 上面列出的流式分段类型.
API格式
POST /segment/definitions
请求
curl -X POST \
https://platform.adobe.io/data/core/ups/segment/definitions \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 30,
"name": "Homepage_continuous",
"description": "People who are on their homepage - continuous",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
},
"evaluationInfo": {
"batch": {
"enabled": false
},
"continuous": {
"enabled": true
},
"synchronous": {
"enabled": false
}
}
}'
响应
成功的响应会返回新创建的启用流的区段定义的详细信息。
{
"id": "f15063cb-2da8-4851-a2e2-bf59ddd2f004",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 30,
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "{SANDBOX_ID}",
"sandboxName": "{SANDBOX_NAME}",
"type": "production",
"default": true
},
"name": "Homepage_continuous",
"description": "People who are on their homepage - continuous",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
},
"evaluationInfo": {
"batch": {
"enabled": false
},
"continuous": {
"enabled": true,
},
"synchronous": {
"enabled": false
}
},
"creationTime": 1572021085000,
"updateEpoch": 1572021086000,
"updateTime": 1572021086000
}
启用计划评估 enable-scheduled-segmentation
启用流式评估后,必须创建基线(此后,区段定义将始终保持最新)。 必须首先启用计划评估(也称为计划分段),系统才能自动执行基线化。 利用计划的分段,您的组织可以遵循定期计划来自动运行导出作业以评估区段定义。
创建计划
向发出POST请求 /config/schedules
端点,您可以创建一个计划并包括应触发该计划的特定时间。
API格式
POST /config/schedules
请求
以下请求基于有效负荷中提供的规范创建新计划。
curl -X POST \
https://platform.adobe.io/data/core/ups/config/schedules \
-H 'Content-Type: application/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}' \
-d '{
"name": "{SCHEDULE_NAME}",
"type": "batch_segmentation",
"properties": {
"segments": ["*"]
},
"schedule": "0 0 1 * * ?",
"state": "inactive"
}'
name
type
batch_segmentation
和 export
.properties
properties.segments
type
等于 batch_segmentation
) 使用 ["*"]
确保包括所有区段定义。schedule
0 0 1 * * ?
)表示作业每天在1触发:00:00 UTC. 欲知更多信息,请参见 cron表达式格式 在文档中查看分段内的计划。state
active
和 inactive
. 默认值为 inactive
. 组织只能创建一个计划。 本教程稍后会介绍更新计划的步骤。响应
成功的响应将返回新创建计划的详细信息。
{
"id": "cd585edf-962d-420d-94ad-3be03e619ac2",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "e7e17720-c5bb-11e9-aafb-87c71c35cac8",
"sandboxName": "prod",
"type": "production",
"default": true
},
"name": "{SCHEDULE_NAME}",
"state": "inactive",
"type": "batch_segmentation",
"schedule": "0 0 1 * * ?",
"properties": {
"segments": [
"*"
]
},
"createEpoch": 1568267948,
"updateEpoch": 1568267948
}
启用计划
默认情况下,创建计划时处于不活动状态,除非 state
属性设置为 active
(POST)请求正文中的。 您可以启用计划(设置 state
到 active
),向发出PATCH请求 /config/schedules
端点并在路径中包含计划的ID。
API格式
POST /config/schedules/{SCHEDULE_ID}
请求
以下请求使用 JSON修补程序格式 以更新 state
的日程安排 active
.
curl -X POST \
https://platform.adobe.io/data/core/ups/config/schedules/cd585edf-962d-420d-94ad-3be03e619ac2 \
-H 'Content-Type: application/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}' \
-d '[
{
"op": "add",
"path": "/state",
"value": "active"
}
]'
响应
成功更新将返回空的响应正文和HTTP状态204(无内容)。
可使用同一操作通过将上一个请求中的“值”替换为“非活动”来禁用计划。
后续步骤
现在,您已为流式分段启用新的和现有的区段定义,并启用了计划分段来开发基线和执行定期评估,您可以开始为组织创建支持流式处理的区段定义。
要了解如何使用Adobe Experience Platform用户界面执行类似操作和使用区段定义,请访问 区段生成器用户指南.
附录
以下部分列出了有关流式客户细分的常见问题解答:
流式客户细分“不合格”是否也会实时发生?
在大多数情况下,流式分段取消资格会实时发生。 但是,使用区段的流区段定义会 非 实时取消资格,而不是在24小时后取消资格。
流式分段处理哪些数据?
流式分段适用于使用流式源摄取的所有数据。 使用基于批次的源摄取的区段将在夜间进行评估,即使它符合流式分段条件。 时间戳超过24小时且流式传输到系统中的事件将在后续批处理作业中进行处理。
区段定义是如何定义为批处理或流式分段的?
区段定义定义为基于查询类型和事件历史记录持续时间的组合的批处理或流式分段。 将作为流区段评估的区段定义的列表,请参见 流式分段查询类型部分.
请注意,如果区段包含 两者 一个 inSegment
表达式和直接单事件链,则不符合流式分段条件。 如果要使此区段定义符合流式分段条件,则应将直接单事件链设置为它自己的区段定义。
为什么“符合条件的总数”区段定义数量持续增加,而“最近X天”下的数量在区段定义详细信息部分中保持为零?
符合条件的区段定义总数源自每日分段作业,其中包括同时符合批量定义和流式区段定义的受众。 此值对于批次和流区段定义均显示。
“最近X天”下的数字 仅限 包括符合流式分段条件的受众,以及 仅限 如果已将数据流式传输到系统中,它会增加,并且它计入该流式定义。 此值为 仅限 显示流区段定义。 因此,此值 五月 批处理客户细分定义显示为0。
因此,如果您看到“最近X天”下的数字为零,并且折线图也报告零,则您会 非 已将符合该区段定义的任何配置文件流式传输到系统中。
区段定义需要多久才能可用?
区段定义最多需要一小时才能可用。