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 呼び出しに必要な各ヘッダーの値は認証チュートリアルで説明されています。
- Authorization: Bearer
{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
結合ポリシーにはソースデータセットに関する情報が含まれ、ソースデータセットにはデータ使用ラベルが含まれます。 結合ポリシーの詳細を検索するには、 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 を使用して、特定のマーケティングアクションに対してこれらのデータセットを評価し、データ使用ポリシー違反を確認します。
データセットを評価するには、次の例に示すように、リクエスト本文内にデータセット ID を指定しながら、POSTリクエストのパスにマーケティングアクションの名前を指定する必要があります。
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 応答で返されたデータを使用して、エクスペリエンスアプリケーション内でプロトコルを設定し、ポリシー違反が発生した場合に適切にポリシー違反を実施できます。
データフィールドをフィルタリングする
セグメント定義が評価を渡さない場合は、次の 2 つの方法のいずれかを使用して、セグメント定義に含まれるデータを調整できます。
セグメント定義の結合ポリシーを更新する
セグメント定義の結合ポリシーを更新すると、セグメントジョブの実行時に含まれるデータセットとフィールドが調整されます。詳しくは、 既存の結合ポリシーの更新 (「 API 結合ポリシーのチュートリアル」を参照)。
セグメント定義の書き出し時に特定のデータフィールドを制限する
セグメント定義をデータセットに書き出す際に、 Segmentation API では、 fields
パラメーター。 このパラメーターに追加したデータフィールドは書き出しに含まれ、その他のデータフィールドはすべて除外されます。
「A」、「B」、「C」という名前のデータフィールドを持つセグメント定義について考えます。 フィールド「C」のみを書き出す場合、fields
パラメーターにはフィールド「C」だけを指定します。これにより、セグメント定義の書き出し時に、「A」と「B」のフィールドが除外されます。
詳しくは、 セグメント定義の書き出し (セグメント化のチュートリアル)を参照してください。
次の手順
このチュートリアルでは、セグメント定義に関連付けられているデータ使用ラベルを検索し、特定のマーケティングアクションに対するポリシー違反の有無をテストしました。 でのデータガバナンスについて詳しくは、 Experience Platformの概要を参照してください。 データガバナンス.