使用API为受众区段强制实施数据使用合规性

本教程介绍了使用API强制Real-time Customer Profile受众段符合数据使用规范的步骤。

入门指南

本教程需要对Adobe Experience Platform的以下组件有充分的了解:

  • Real-time Customer Profile: Real-time Customer Profile 是通用查找实体存储,用于管理 Experience Data Model (XDM) 中的数 Platform据用户档案将不同企业数据资产中的数据合并,并以统一的表示形式提供对该数据的访问。
    • 合并策略:用于确定 Real-time Customer Profile 在某些条件下哪些数据可以合并为统一视图的规则。可以为Data Governance目的配置合并策略。
  • Segmentation:如 Real-time Customer Profile 何将用户档案商店中所含的大量个人划分为具有相似特征并将对营销策略做出类似反应的较小群体。
  • Data Governance: Data Governance 使用以下组件为数据使用标签和执行提供基础架构:
    • 数据使用标签:用于根据处理数据集和字段各自数据的敏感程度描述数据集和字段的标签。
    • 数据使用策略:指示允许对按特定数据使用标签分类的数据执行哪些营销操作的配置。
    • 政策执行:允许您实施数据使用策略并防止构成策略违规的数据操作。
  • 沙箱: 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:{IMS_ORG}

Experience Platform中的所有资源都隔离到特定虚拟沙箱。 对Platform API的所有请求都需要一个头,该头指定操作将在中执行的沙箱的名称:

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

有关Platform中沙箱的详细信息,请参阅沙箱概述文档

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

  • 内容类型:application/json

查找区段定义的合并策略

此工作流首先访问已知的受众区段。 允许在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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

响应

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

{
    "id": "24379cae-726a-4987-b7b9-79c32cddb5c1",
    "schema": { 
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 90,
    "imsOrgId": "{IMS_ORG}",
    "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。 此操作将在下一步中使用。

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

合并策略包含有关其源数据集的信息,这些信息又包含数据使用标签。 可以通过在向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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

响应

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

{
    "id": "2b43d78d-0ad4-4c1e-ac2d-574c09b01119",
    "imsOrgId": "{IMS_ORG}",
    "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.typedataSetPrecedence,则此属性将是一个数组,包含此合并策略所使用数据集的ID。 这些ID将用于下一步。

评估数据集中的策略违规情况

注意

此步骤假定您至少有一个活动数据使用策略,该策略可阻止对包含特定标签的数据执行特定营销操作。 如果您对要评估的数据集没有任何适用的使用策略,请按照策略创建教程创建一个策略,然后继续执行此步骤。

获得合并策略的源数据集的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: {IMS_ORG}' \
  -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": "{IMS_ORG}",
  "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": "{IMS_ORG}",
      "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中Data Governance的详细信息,请阅读Data Governance的概述。

在此页面上