使用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
合併原則包含其來源資料集的相關資訊,而來源資料集又包含資料使用標籤。 您可以在GET要求中提供合併原則ID,查詢合併原則的詳細資料 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
,依序輸入。要求
以下請求會測試 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,請閱讀 資料控管.