文档Experience PlatformSegmentation Service 指南

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

Last update: Mon Aug 05 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主题：

创建对象：

  • 用户

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

快速入门

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

  • Real-Time Customer Profile： Real-Time Customer Profile是通用查找实体存储，用于管理Platform中的Experience Data Model (XDM)数据。 配置文件跨各种企业数据资产合并数据，并以统一的呈现方式提供对这些数据的访问。

    • 合并策略： Real-Time Customer Profile用于确定在特定条件下可以将哪些数据合并到统一视图的规则。 可以为数据管理目的配置合并策略。

  • Segmentation： Real-Time Customer Profile如何将个人资料存储区中包含的大量个人分组为具有相似特征且响应方式相似的较小组。

  • 数据管理：“数据管理”使用以下组件提供用于标记和实施数据使用的基础结构：

    • 数据使用标签：用于根据处理数据集和字段各自数据的敏感度级别描述数据集和字段的标签。
    • 数据使用策略：指示允许对按特定数据使用标签分类的数据执行哪些营销操作的配置。
    • 策略实施：允许您实施数据使用策略并阻止构成策略违规的数据操作。

  • 沙盒： Experience Platform提供将单个Platform实例划分为单独虚拟环境的虚拟沙盒，以帮助开发和改进数字体验应用程序。

以下部分提供了成功调用Platform API所需了解的其他信息。

正在读取示例 API 调用

本教程提供了示例API调用来演示如何格式化请求。 这些包括路径、必需的标头和格式正确的请求负载。还提供了在 API 响应中返回的示例 JSON。有关示例API调用文档中使用的约定的信息，请参阅Experience Platform疑难解答指南中有关如何读取示例API调用的部分。

收集所需标头的值

要调用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"
    },
    "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

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

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。

请求

以下请求针对在上一步中获取的数据集测试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
一个数组，列出了通过针对提供的duleLabels测试营销操作（在marketingActionRef中指定）而违反的任何数据使用策略。

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

筛选数据字段

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

更新区段定义的合并策略

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

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

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

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

有关详细信息，请参阅分段教程中有关导出区段定义的部分。

后续步骤

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

recommendation-more-help
770bc05d-534a-48a7-9f07-017ec1e14871