评估和访问区段结果

本文档提供了有关使用Segmentation API评估区段和访问区段结果的教程。

快速入门

本教程需要对创建受众区段时涉及的各种Adobe Experience Platform服务有一定的了解。 在开始本教程之前,请查阅以下服务的文档:

必需标题

本教程还要求您完成身份验证教程,才能成功调用Platform API。 完成身份验证教程可为所有Experience Platform API调用中每个所需标头的值,如下所示:

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

Experience Platform中的所有资源均与特定虚拟沙箱隔离。 对Platform API的请求需要一个标头来指定操作将在其中进行的沙盒的名称:

  • x-sandbox-name: {SANDBOX_NAME}
注意

有关Platform中沙箱的更多信息,请参阅沙盒概述文档

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

  • Content-Type:application/json

评估区段

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

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

如果您尚未使用分段API🔗教程完成创建区段,或者使用区段生成器创建区段定义,请在继续阅读本教程之前执行此操作。

计划评估

通过计划评估,您的IMS组织可以创建循环计划以自动运行导出作业。

注意

对于XDM Individual Profile最多包含五(5)个合并策略的沙箱,可启用计划评估。 如果贵组织在单个沙盒环境中有五个以上的XDM Individual Profile合并策略,您将无法使用计划评估。

创建计划

通过向/config/schedules端点发出POST请求,可以创建调度并包含应触发该调度的特定时间。

有关使用此端点的详细信息,请参阅计划终结点指南

启用计划

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

有关使用此端点的详细信息,请参阅计划终结点指南

更新计划时间

通过向/config/schedules端点发出PATCH请求并在路径中包含调度的ID,可以更新调度时间。

有关使用此端点的详细信息,请参阅计划终结点指南

按需评估

按需评估允许您创建区段作业,以便根据需要生成受众区段。 与计划评估不同,只有在请求时才会执行此操作,而不会重复执行。

创建区段作业

区段作业是创建新受众区段的异步过程。 它引用了区段定义以及任何合并策略,这些策略控制Real-time Customer Profile如何在配置文件片段中合并重叠属性。 成功完成区段作业后,您可以收集有关该区段的各种信息,例如处理过程中可能发生的任何错误以及受众的最终大小。

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

有关使用此端点的详细信息,请参阅segment jobs端点指南

查找区段作业状态

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

有关使用此端点的详细信息,请参阅segment jobs端点指南

解释区段结果

成功运行区段作业时,会为区段中包含的每个配置文件更新segmentMembership映射。 segmentMembership 此外,还会存储被摄取到中的任何预评估受众区段, Platform以便与其他解决方案(如)集 Adobe Audience Manager成。

以下示例显示了每个配置文件记录的segmentMembership属性的外观:

{
  "segmentMembership": {
    "UPS": {
      "04a81716-43d6-4e7a-a49c-f1d8b3129ba9": {
        "timestamp": "2018-04-26T15:52:25+00:00",
        "status": "existing"
      },
      "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 作为当前请求一部分的区段参与状态。 必须等于以下已知值之一:
  • existing:实体继续在分部中。
  • realized:实体正在输入区段。
  • exited:实体正在退出区段。

访问区段结果

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

以下各节将更详细地介绍这些选项。

查找用户档案

如果您知道要访问的特定配置文件,可以使用Real-time Customer Profile API执行此操作。 使用配置文件API教程访问实时客户配置文件数据中提供了访问各个配置文件的完整步骤。

导出区段

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

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

创建目标数据集

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

其中一个关键注意事项是数据集所基于的架构(在下面的API示例请求中为schemaRef.id)。 要导出区段,数据集必须基于XDM Individual Profile Union Schema (https://ns.adobe.com/xdm/context/profile__union)。 并集架构是系统生成的只读架构,用于聚合共享相同类的架构的字段(在本例中为XDM Indivial Profile类)。 有关并集视图架构的更多信息,请参阅架构注册开发人员指南🔗的实时客户配置文件部分。

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

  • 使用API: 本教程中遵循的步骤将简要介绍如何使用API创建引 XDM Individual Profile Union Schema 用的 Catalog 数据集。
  • 使用UI: 要使用用 Adobe Experience Platform 户界面创建引用并集架构的数据集,请按照UI教程中的步骤操作,然后返回本教程,以继续执行生成受众配置文 件的步骤 🔗

如果您已经有一个兼容的数据集并且知道其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: {IMS_ORG}' \
  -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"
] 

为受众成员生成用户档案

拥有并集持久保留的数据集后,您可以创建一个导出作业,以将受众成员保留到数据集,方法是向Real-time Customer Profile API的/export/jobs端点发出POST请求,并提供要导出的区段的数据集ID和区段信息。

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

监视导出进度

在导出作业进程中,您可以通过向/export/jobs端点发出GET请求并在路径中包含导出作业的id来监视其状态。 status字段返回值“SUCCEEDED”后,导出作业即完成。

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

后续步骤

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

有关如何使用Data Access API访问和下载批处理文件的分步说明,请参阅数据访问教程

您还可以使用Adobe Experience Platform Query Service访问已成功导出的区段数据。 Query Service使用UI或RESTful API,可以对Data Lake中的数据写入、验证和运行查询。

有关如何查询受众数据的更多信息,请查阅Query Service上的文档。

在此页面上