文件Experience Platform分段服務指南

使用API強制區段定義的資料使用合規性

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

建立對象：

  • 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

合併原則包含其來源資料集的相關資訊，而來源資料集又包含資料使用標籤。 您可以在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會用於下一個步驟。

評估原則違規的資料集

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
陣列，列出測試行銷動作所違反的任何資料使用原則(指定於 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