ドキュメント Experience Platform セグメント化サービスガイド

APIを使用して、セグメント定義のデータ使用コンプライアンスを適用する

最終更新日： 2026年5月24日

トピック：
Segments

作成対象：

User

このチュートリアルでは、APIを使用してセグメント定義のデータ使用コンプライアンスを適用する手順について説明します。

はじめに

このチュートリアルでは、Adobe Experience Platform の次のコンポーネントに関する十分な知識が必要です。

Real-Time Customer Profile: Real-Time Customer Profileは汎用ルックアップエンティティストアであり、Experience Platform内のExperience Data Model (XDM) データの管理に使用されます。プロファイルでは、様々な企業データアセットのデータが結合され、統合されたプレゼンテーションでそのデータにアクセスできます。
- 結合ポリシー: Real-Time Customer Profileが特定の条件で統合ビューに結合できるデータを決定するために使用するルール。結合ポリシーは、データガバナンスの目的で設定できます。
Segmentation: プロファイルストアに含まれる多数の個人を、類似した特性を共有し、マーケティング戦略に類似して対応する小さなグループにReal-Time Customer Profileがどのように分割するか。
データガバナンス : データガバナンスは、次のコンポーネントを使用して、データ使用のラベル付けと適用のためのインフラストラクチャを提供します。
- データ使用ラベル：データセットとフィールドを、それぞれのデータを処理する際に適用する機密性のレベルの観点から説明する際に使用されるラベルです。
- データ使用ポリシー：特定のデータ使用ラベルで分類されたデータで、どのマーケティングアクションが許可されるかを示す設定です。
- ポリシーの適用: データ使用ポリシーを適用し、ポリシー違反を構成するデータ操作を防止できます。
サンドボックス：Experience Platform には、単一の Experience Platform インスタンスを別個の仮想環境に分割してデジタルエクスペリエンスアプリケーションの開発と発展を支援する仮想サンドボックスが用意されています。

次の節では、Experience Platform APIを正常に呼び出すために知っておく必要がある追加情報を示します。

API 呼び出し例の読み取り

このチュートリアルでは、API 呼び出しの例を提供し、リクエストの形式を設定する方法を示します。これには、パス、必須ヘッダー、適切な形式のリクエストペイロードが含まれます。また、API レスポンスで返されるサンプル JSON も示されています。ドキュメントで使用される API 呼び出し例の表記について詳しくは、トラブルシューテングガイドのAPI 呼び出し例の読み方に関する節を参照してくださいExperience Platform。

必須ヘッダーの値の収集

Experience Platform API を呼び出すには、まず認証チュートリアルを完了する必要があります。次に示すように、すべての Experience Platform API 呼び出しに必要な各ヘッダーの値は認証チュートリアルで説明されています。

Authorization: Bearer {ACCESS_TOKEN}
x-api-key： {API_KEY}
x-gw-ims-org-id: {ORG_ID}

Experience Platform のすべてのリソースは、特定の仮想サンドボックスに分離されています。 Experience Platform API へのすべてのリクエストには、操作がおこなわれるサンドボックスの名前を指定するヘッダーが必要です。

x-sandbox-name：{SANDBOX_NAME}

NOTE

Experience 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"
    },
    "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 リクエストでProfile APIに結合ポリシー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: {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

この手順では、特定のラベルを含むデータに対して特定のマーケティングアクションを実行できないように、少なくとも1つのアクティブなデータ使用ポリシーがあることを前提としています。評価するデータセットに適用できる使用ポリシーがない場合は、この手順を続行する前に、ポリシー作成チュートリアルに従って作成してください。

結合ポリシーのソースデータセットの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

指定されたduleLabelsに対してマーケティングアクション（marketingActionRefで指定）をテストすることで違反したデータ使用ポリシーを一覧表示する配列。

API応答で返されるデータを使用して、エクスペリエンスアプリケーション内でプロトコルを設定し、ポリシー違反が発生したときに適切にポリシー違反を適用できます。

データフィールドをフィルタリングする

セグメント定義が評価に合格しない場合は、次に説明する2つの方法のいずれかを使用して、セグメント定義に含まれるデータを調整できます。

セグメント定義の結合ポリシーを更新する

セグメント定義の結合ポリシーを更新すると、セグメントジョブの実行時に含まれるデータセットとフィールドが調整されます。詳しくは、API結合ポリシーチュートリアルの既存の結合ポリシーの更新の節を参照してください。

セグメント定義の書き出し時に特定のデータフィールドを制限する

Segmentation APIを使用してセグメント定義をデータセットに書き出す場合、fields パラメーターを使用して、書き出しに含まれるデータをフィルタリングできます。このパラメーターに追加したデータフィールドは書き出しに含まれ、その他のデータフィールドはすべて除外されます。

「A」、「B」、「C」という名前のデータフィールドを持つセグメント定義を考えてみましょう。フィールド「C」のみを書き出す場合、fields パラメーターにはフィールド「C」だけを指定します。これにより、セグメント定義を書き出す際に、「A」フィールドと「B」フィールドが除外されます。

詳しくは、セグメント化チュートリアルの「セグメント定義の書き出し」の節を参照してください。

次の手順

このチュートリアルでは、セグメント定義に関連付けられているデータ使用ラベルを検索し、特定のマーケティングアクションに対するポリシー違反をテストしました。 Experience Platformのデータガバナンスについて詳しくは、データガバナンスの概要をお読みください。

recommendation-more-help

experience-platform-help-segmentation