文档 Experience Platform Segmentation Service 指南

使用API强制实施区段定义的数据使用合规性

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

主题：
Segments

创建对象：

User

本教程介绍了使用API为区段定义强制实施数据使用合规性的步骤。

快速入门

本教程需要对以下组件有一定的了解 Adobe Experience Platform：

Real-Time Customer Profile： Real-Time Customer Profile 是一个通用查找实体存储，用于管理 Experience Data Model (XDM) 数据范围 Platform. 配置文件跨各种企业数据资产合并数据，并以统一的呈现方式提供对这些数据的访问。
- 合并策略：使用的规则 Real-Time Customer Profile 以确定在特定条件下可以将哪些数据合并到统一视图中。可以为数据管理目的配置合并策略。
Segmentation：方法 Real-Time Customer Profile 将个人资料存储中包含的大量个人划分为较小的组，这些组具有相似的特征，并且对营销策略的响应也类似。
数据管理：数据管理使用以下组件提供用于标记和执行数据使用的基础架构：
- 数据使用情况标签：用于根据处理数据集和字段各自数据的敏感度级别描述数据集和字段的标签。
- 数据使用策略：指示允许对按特定数据使用标签分类的数据执行哪些营销操作的配置。
- 策略实施：用于强制实施数据使用策略并阻止构成策略违规的数据操作。
沙盒： Experience Platform 提供对单个文件夹进行分区的虚拟沙盒 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}

NOTE

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

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

Content-Type： application/json

查找区段定义的合并策略 merge-policy

此工作流从访问已知的区段定义开始。已启用以便在中使用的区段定义 Real-Time Customer Profile 在其区段定义中包含合并策略ID。此合并策略包含有关哪些数据集将包含在区段定义中的信息，这些数据集又包含任何适用的数据使用标签。

使用 Segmentation API时，您可以按其ID查找区段定义，以查找与其关联的合并策略。

API格式

GET /segment/definitions/{SEGMENT_DEFINITION_ID}

属性

描述

{SEGMENT_DEFINITION_ID}

要查找的区段定义的ID。

请求

curl -X GET \
  https://platform.adobe.io/data/core/ups/segment/definitions/24379cae-726a-4987-b7b9-79c32cddb5c1 \
  -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}'

响应

成功的响应将返回区段定义的详细信息。

{
    "id": "24379cae-726a-4987-b7b9-79c32cddb5c1",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 90,
    "imsOrgId": "{ORG_ID}",
    "name": "Cart abandons in CA",
    "description": "",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "homeAddress.countryISO = 'US'"
    },
    "mergePolicyId": "2b43d78d-0ad4-4c1e-ac2d-574c09b01119",
    "evaluationInfo": {
        "batch": {
            "enabled": true
        },
        "continuous": {
            "enabled": false
        },
        "synchronous": {
            "enabled": false
        }
    },
    "creationTime": 1556094486000,
    "updateEpoch": 1556094486000,
    "updateTime": 1556094486000
  }
}

属性

描述

mergePolicyId

用于区段定义的合并策略的ID。这将在下一步中使用。

从合并策略中查找源数据集 datasets

合并策略包含有关其源数据集的信息，而这些源数据集又包含数据使用标签。您可以通过在向提供的合并策略ID请求中提供GET，查找合并策略的详细信息。 Profile API。有关合并策略的更多信息，请参阅合并策略端点指南.

API格式

GET /config/mergePolicies/{MERGE_POLICY_ID}

属性

描述

{MERGE_POLICY_ID}

在中获取的合并策略的ID 上一步.

请求

curl -X GET \
  https://platform.adobe.io/data/core/ups/config/mergePolicies/2b43d78d-0ad4-4c1e-ac2d-574c09b01119 \
  -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}'

响应

成功的响应将返回合并策略的详细信息。

{
    "id": "2b43d78d-0ad4-4c1e-ac2d-574c09b01119",
    "imsOrgId": "{ORG_ID}",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "version": 1,
    "identityGraph": {
        "type": "none"
    },
    "attributeMerge": {
        "type":"dataSetPrecedence",
        "data": {
            "order": ["5b95b155419ec801e6eee780", "5b7c86968f7b6501e21ba9df"]
        }
    },
    "default": false,
    "updateEpoch": 1551127597
}

属性

描述

schema.name

与合并策略关联的架构的名称。

attributeMerge.type

合并策略的数据优先配置类型。如果值为 dataSetPrecedence，则与此合并策略关联的数据集将列在 attributeMerge > data > order. 如果值为 timestampOrdered，则与中引用的架构关联的所有数据集 schema.name 由合并策略使用。

attributeMerge.data.order

如果 attributeMerge.type 是 dataSetPrecedence，则此属性将是一个数组，其中包含此合并策略所使用的数据集的ID。这些ID将在下一步中使用。

评估策略违规的数据集

NOTE

此步骤假定您至少有一个有效的数据使用策略，该策略阻止对包含特定标签的数据执行特定营销操作。如果您没有适用于所评估的数据集的使用策略，请遵循策略创建教程以创建一个工作流，然后再继续此步骤。

获取合并策略的源数据集的ID后，您可以使用策略服务API 根据特定营销操作评估这些数据集，以检查是否存在数据使用策略违规。

要评估数据集，您必须在POST请求的路径中提供营销操作的名称，同时在请求正文中提供数据集ID，如以下示例所示。

API格式

POST /marketingActions/core/{MARKETING_ACTION_NAME}/constraints
POST /marketingActions/custom/{MARKETING_ACTION_NAME}/constraints

参数

描述

{MARKETING_ACTION_NAME}

与用于评估数据集的数据使用策略关联的营销操作的名称。根据策略是由Adobe还是贵组织定义的，您必须使用 /marketingActions/core 或 /marketingActions/custom、ID名称和ID名称等。

请求

以下请求将测试 exportToThirdParty 针对中获取的数据集执行营销操作上一步. 请求有效负载是一个数组，包含每个数据集的ID。

curl -X POST \
  https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty/constraints
  -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}' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "entityType": "dataSet",
      "entityId": "5b95b155419ec801e6eee780"
    },
    {
      "entityType": "dataSet",
      "entityId": "5b7c86968f7b6501e21ba9df"
    }
  ]'

属性

描述

entityType

有效负载数组中的每一项都必须指示所定义的实体类型。对于此用例，值将始终为“dataSet”。

entityID

有效负载数组中的每一项都必须提供数据集的唯一ID。

响应

成功的响应将返回营销操作的URI、从提供的数据集中收集的数据使用标签，以及由于针对这些标签测试操作而违反的任何数据使用策略的列表。在此示例中，“将数据导出到第三方”策略显示在 violatedPolicies 数组，指示营销操作触发了策略冲突。

{
  "timestamp": 1556324277895,
  "clientId": "{CLIENT_ID}",
  "userId": "{USER_ID}",
  "imsOrg": "{ORG_ID}",
  "marketingActionRef": "https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty",
  "duleLabels": [
    "C1",
    "C2",
    "C4",
    "C5"
  ],
  "discoveredLabels": [
    {
      "entityType": "dataSet",
      "entityId": "5b95b155419ec801e6eee780",
      "dataSetLabels": {
        "connection": {
          "labels": []
        },
        "dataSet": {
          "labels": [
            "C5"
          ]
        },
        "fields": [
          {
            "labels": [
              "C2",
            ],
            "path": "/properties/_customer"
          },
          {
            "labels": [
              "C5"
            ],
            "path": "/properties/geoUnit"
          },
          {
            "labels": [
              "C1"
            ],
            "path": "/properties/identityMap"
          }
        ]
      }
    },
    {
      "entityType": "dataSet",
      "entityId": "5b7c86968f7b6501e21ba9df",
      "dataSetLabels": {
        "connection": {
          "labels": []
        },
        "dataSet": {
          "labels": [
            "C5"
          ]
        },
        "fields": [
          {
            "labels": [
              "C5"
            ],
            "path": "/properties/createdByBatchID"
          },
          {
            "labels": [
              "C5"
            ],
            "path": "/properties/faxPhone"
          }
        ]
      }
    }
  ],
  "violatedPolicies": [
    {
      "name": "Export Data to Third Party",
      "status": "ENABLED",
      "marketingActionRefs": [
        "https://platform-stage.adobe.io:443/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty"
      ],
      "description": "Conditions under which data cannot be exported to a third party",
      "deny": {
        "operator": "OR",
        "operands": [
          {
            "label": "C1"
          },
          {
            "operator": "AND",
            "operands": [
              {
                "label": "C3"
              },
              {
                "label": "C7"
              }
            ]
          }
        ]
      },
      "imsOrg": "{ORG_ID}",
      "created": 1565651746693,
      "createdClient": "{CREATED_CLIENT}",
      "createdUser": "{CREATED_USER",
      "updated": 1565723012139,
      "updatedClient": "{UPDATED_CLIENT}",
      "updatedUser": "{UPDATED_USER}",
      "_links": {
        "self": {
          "href": "https://platform-stage.adobe.io/data/foundation/dulepolicy/policies/custom/5d51f322e553c814e67af1a3"
        }
      },
      "id": "5d51f322e553c814e67af1a3"
    }
  ]
}

属性

描述

duleLabels

从提供的数据集中提取的数据使用标签列表。

discoveredLabels

在请求有效负载中提供的数据集列表，其中显示了在每个数据集中找到的数据集级别和字段级别标签。

violatedPolicies

一个数组，列出了通过测试营销操作(在 marketingActionRef)根据提供的 duleLabels.

使用API响应中返回的数据，您可以在体验应用程序中设置协议，以在发生策略违规时适当地实施这些违规。

筛选数据字段

如果区段定义未通过评估，则可通过下面列出的两种方法之一调整区段定义中包含的数据。

更新区段定义的合并策略

更新区段定义的合并策略将调整运行区段作业时将包含的数据集和字段。请参阅以下部分更新现有合并策略有关更多信息，请参阅API合并策略教程。

导出区段定义时限制特定数据字段

使用将区段定义导出到数据集时 Segmentation API中，您可以使用来过滤导出中包含的数据 fields 参数。添加到此参数的任何数据字段都将包含在导出中，而所有其他数据字段将被排除。

考虑具有名为“A”、“B”和“C”的数据字段的区段定义。如果您只想导出字段“C”，则 fields 参数将仅包含字段“C”。这样，在导出区段定义时将排除字段“A”和“B”。

请参阅以下部分导出区段定义有关更多信息，请参阅分段教程。

后续步骤

通过学习本教程，您已查找与区段定义关联的数据使用标签，并测试它们是否违反了针对特定营销操作的策略。有关“数据管理”的详细信息，请参阅 Experience Platform，请阅读数据管理.

recommendation-more-help

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