文档 Experience Platform Segmentation Service 指南

评估和访问区段定义结果

Last update: Tue Nov 14 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

主题：
Segments

创建对象：

User

本文档提供了一个教程，用于评估区段定义并使用访问这些结果。 Segmentation API.

快速入门

本教程需要对各种 Adobe Experience Platform 创建受众时涉及的服务。在开始本教程之前，请查看以下服务的文档：

Real-Time Customer Profile：根据来自多个来源的汇总数据，实时提供统一的客户个人资料。
Adobe Experience Platform Segmentation Service：允许您从构建受众 Real-Time Customer Profile 数据。
Experience Data Model (XDM)：Platform用于组织客户体验数据的标准化框架。为了更好地利用分段，请确保您的数据被作为配置文件和事件摄取，并根据数据建模的最佳实践.
沙盒： Experience Platform 提供对单个文件夹进行分区的虚拟沙盒 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}

NOTE

有关中沙箱的详细信息 Platform，请参见沙盒概述文档.

所有POST、PUT和PATCH请求都需要额外的标头：

Content-Type： application/json

评估区段定义 evaluate-a-segment

开发、测试和保存区段定义后，您可以通过计划评估或按需评估来评估区段定义。

计划的评估（也称为“计划分段”）允许您为在特定时间运行导出作业创建定期计划，而按需评估涉及创建区段作业以立即构建受众。下面概述了每种方法的步骤。

如果您尚未完成使用分段API创建区段定义教程或创建区段定义，使用区段生成器，请先执行该操作，然后再继续学习本教程。

计划的评估 scheduled-evaluation

通过计划的评估，您的组织可以创建定期计划以自动运行导出作业。

NOTE

可以为最多具有五(5)个合并策略的沙盒启用计划评估。 XDM Individual Profile. 如果贵组织的合并策略超过5个，则 XDM Individual Profile 在单个沙盒环境中，您将无法使用计划的评估。

创建计划

向发出POST请求 /config/schedules 端点，您可以创建一个计划并包括应触发该计划的特定时间。

有关使用此端点的更多详细信息，请参阅计划端点指南

启用计划

默认情况下，创建计划时处于不活动状态，除非 state 属性设置为 active (POST)请求正文中的。您可以启用计划(设置 state 到 active)，向发出PATCH请求 /config/schedules 端点并在路径中包含计划的ID。

有关使用此端点的更多详细信息，请参阅计划端点指南

更新计划时间

可以通过向以下网站发出PATCH请求来更新时间表计时 /config/schedules 端点并在路径中包含计划的ID。

有关使用此端点的更多详细信息，请参阅计划端点指南

按需评估

按需评估允许您创建区段作业，以便在需要时生成受众。与计划的评估不同，仅在请求时才会发生此情况，并且不会重复发生。

创建区段作业

区段作业是一个异步过程，可按需创建受众区段。它引用区段定义，以及控制其方式的任何合并策略 Real-Time Customer Profile 合并配置文件片段中的重叠属性。成功完成区段作业后，您可以收集有关区段定义的各种信息，例如处理期间可能发生的任何错误以及最终的受众规模。每次要刷新区段定义当前符合条件的受众时，都需要运行区段作业。

您可以通过向以下对象发出POST请求来创建新的区段作业： /segment/jobs 中的端点 Real-Time Customer Profile API。

有关使用此端点的更多详细信息，请参阅区段作业端点指南

查找区段作业状态

您可以使用 id 特定区段作业来执行查找请求(GET)，以查看该作业的当前状态。

有关使用此端点的更多详细信息，请参阅区段作业端点指南

解释区段作业结果

成功运行区段作业后， segmentMembership 区段定义中包含的每个配置文件都会更新映射。 segmentMembership 还会存储任何被引入的预评估受众 Platform，允许与其他解决方案集成，例如 Adobe Audience Manager.

以下示例显示了 segmentMembership 每个个人资料记录的属性如下所示：

{
  "segmentMembership": {
    "UPS": {
      "04a81716-43d6-4e7a-a49c-f1d8b3129ba9": {
        "timestamp": "2018-04-26T15:52:25+00:00",
        "status": "realized"
      },
      "53cba6b2-a23b-454a-8069-fc41308f1c0f": {
        "lastQualificationTime": "2018-04-26T15:52:25+00:00",
        "status": "realized"
      }
    },
    "Email": {
      "abcd@adobe.com": {
        "lastQualificationTime": "2017-09-26T15:52:25+00:00",
        "status": "exited"
      }
    }
  }
}

属性

描述

lastQualificationTime

进行区段成员资格断言以及用户档案输入或退出区段定义时的时间戳。

status

作为当前请求一部分的区段定义的参与状态。必须等于以下已知值之一：

realized：实体符合区段定义的条件。
exited：实体正在退出区段定义。

NOTE

位于以下位置的任何区段成员资格： exited 超过30天的状态，根据 lastQualificationTime，将被删除。

访问区段作业结果

可以通过以下两种方式之一访问区段作业的结果：访问各个用户档案或将整个受众导出到数据集。

以下各节更详细地概述了这些选项。

查找配置文件

如果您知道要访问的特定用户档案，可以使用 Real-Time Customer Profile API。有关访问各个用户档案的完整步骤，请参阅使用配置文件API访问实时客户配置文件数据教程。

导出区段 export

成功完成分段作业后( status 属性为“SUCCEEDED”)，您可以将受众导出到可在其中进行访问和操作的数据集。

导出受众需要执行以下步骤：

创建目标数据集 — 创建数据集以包含受众成员。
在数据集中生成受众配置文件 — 根据区段作业的结果，使用XDM个人资料填充数据集。
监控导出进度 — 检查导出过程的当前进度。
读取受众数据 — 检索生成的代表受众成员的XDM个人配置文件。

创建目标数据集 create-dataset

导出受众时，必须首先创建目标数据集。请务必正确配置数据集以确保成功导出。

关键注意事项之一是数据集所基于的架构(schemaRef.id （在下面的API示例请求中）。要导出区段定义，数据集必须基于 XDM Individual Profile Union Schema (https://ns.adobe.com/xdm/context/profile__union)。合并架构是一个系统生成的只读架构，它聚合了共享同一类（在本例中是XDM个人资料类）的架构字段。有关合并视图架构的更多信息，请参阅 Schema Registry开发人员指南的Real-time Customer Profile部分.

有两种方法可创建必要的数据集：

使用API： 本教程中接下来的步骤概述了如何创建引用 XDM Individual Profile Union Schema 使用 Catalog API。
使用UI： 要使用 Adobe Experience Platform 要创建引用合并架构的数据集，请按照用户界面教程然后返回本教程以继续执行相关步骤生成受众配置文件.

如果您已经具有兼容的数据集并且知道其ID，则可以直接继续执行步骤生成受众配置文件.

API格式

POST /dataSets

请求

以下请求创建一个新数据集，在有效负载中提供配置参数。

curl -X POST \
  https://platform.adobe.io/data/foundation/catalog/dataSets \
  -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": "Segment Export",
    "schemaRef": {
        "id": "https://ns.adobe.com/xdm/context/profile__union",
        "contentType": "application/vnd.adobe.xed+json;version=1"
    }
}'

属性

描述

name

数据集的描述性名称。

schemaRef.id

数据集将关联的合并视图（架构）的ID。

响应

成功的响应会返回一个数组，其中包含新创建的数据集的系统生成的只读ID。需要正确配置的数据集ID才能成功导出受众成员。

[
  "@/datasets/5b020a27e7040801dedba61b"
]

为受众成员生成配置文件 generate-profiles

POST拥有合并持久化数据集后，您可以创建导出作业，通过对 /export/jobs 中的端点 Real-Time Customer Profile API并提供要导出的区段定义的数据集ID和区段定义信息。

有关使用此端点的更多详细信息，请参阅导出作业端点指南

监控导出进度

导出作业处理时，您可以通过向以下对象发出GET请求来监控其状态： /export/jobs 端点并包括 id 路径中导出作业的位置。导出作业在 status 字段返回值“SUCCEEDED”。

有关使用此端点的更多详细信息，请参阅导出作业端点指南

后续步骤

成功完成导出后，您的数据即可用于 Data Lake 在 Experience Platform. 然后，您可以使用 Data Access API 以使用访问数据 batchId 与导出关联。根据区段定义的大小，数据可能以块为单位，并且批处理可能包含多个文件。

有关如何使用 Data Access 访问和下载批处理文件的API，请按照数据访问教程.

您还可以使用以下方式访问成功导出的区段定义数据 Adobe Experience Platform Query Service. 使用UI或RESTful API， Query Service 允许您编写、验证和运行 Data Lake.

有关如何查询受众数据的更多信息，请参阅以下文档： Query Service.

recommendation-more-help

770bc05d-534a-48a7-9f07-017ec1e14871