使用API强制实施区段定义的数据使用合规性
本教程介绍了使用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}
包含负载 (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}
请求
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
从合并策略中查找源数据集 datasets
合并策略包含有关其源数据集的信息,而这些源数据集又包含数据使用标签。 您可以通过在向提供的合并策略ID请求中提供GET,查找合并策略的详细信息。 Profile API。 有关合并策略的更多信息,请参阅 合并策略端点指南.
API格式
GET /config/mergePolicies/{MERGE_POLICY_ID}
{MERGE_POLICY_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将在下一步中使用。评估策略违规的数据集
获取合并策略的源数据集的ID后,您可以使用 策略服务API 根据特定营销操作评估这些数据集,以检查是否存在数据使用策略违规。
要评估数据集,您必须在POST请求的路径中提供营销操作的名称,同时在请求正文中提供数据集ID,如以下示例所示。
API格式
POST /marketingActions/core/{MARKETING_ACTION_NAME}/constraints
POST /marketingActions/custom/{MARKETING_ACTION_NAME}/constraints
{MARKETING_ACTION_NAME}
/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
entityID
响应
成功的响应将返回营销操作的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,请阅读 数据管理.