API を使用したデータセットのデータ使用ラベルの管理

Dataset Service API では、データセットの使用ラベルを適用および編集できます。これは Adobe Experience Platform のデータカタログ機能の一部ですが、データセットメタデータを管理する Catalog Service API とは別のものです。

このドキュメントでは、Dataset Service API を使用してデータセットとフィールドのラベルを管理する方法を説明します。API 呼び出しを使用してデータ使用ラベル自体を管理する手順については、Policy Service API のラベルエンドポイントガイドを参照してください。

はじめに

このガイドを読む前に、カタログ開発者ガイドの「はじめに」で説明されている手順に従って、Platform API を呼び出すために必要な資格情報を収集します。

このドキュメントで説明しているエンドポイントを呼び出すには、特定のデータセットに対して一意の id 値を持つ必要があります。この値がない場合は、カタログオブジェクトのリストに関するガイドを参照し、既存のデータセットの ID を確認してください。

データセットのラベルの検索

Dataset Service API に GET リクエストをおこなうことで、既存のデータセットに適用されているデータ使用ラベルを調べることができます。

API 形式

GET /datasets/{DATASET_ID}/labels

リクエスト

curl -X GET \
  'https://platform.adobe.io/data/foundation/dataset/datasets/5abd49645591445e1ba04f87/labels' \
  -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}'

応答

成功した応答は、データセットに適用されたデータ使用ラベルを返します。

{
  "AEP:dataset:5abd49645591445e1ba04f87": {
    "imsOrg": "{ORG_ID}",
    "labels": [ "C1", "C2", "C3", "I1", "I2" ],
    "optionalLabels": [
      {
        "option": {
          "id": "https://ns.adobe.com/{TENANT_ID}/schemas/c6b1b09bc3f2ad2627c1ecc719826836",
          "contentType": "application/vnd.adobe.xed-full+json;version=1",
          "schemaPath": "/properties/repositoryCreatedBy"
        },
        "labels": [ "S1", "S2" ]
      }
    ]
  }
}

データセットにラベルを適用する

Dataset Service API への POST または PUT リクエストのペイロードにラベルのセットを指定することで、データセット全体にラベルのセットを適用できます。リクエスト本文は、両方の呼び出しで同じです。個々のデータセットフィールドにラベルを追加することはできません。

API 形式

POST /datasets/{DATASET_ID}/labels
PUT /datasets/{DATASET_ID}/labels

リクエスト

以下の POST リクエストの例では、データセット全体を C1 ラベルで更新します。ペイロードに指定されるフィールドは、PUT リクエストに必要なフィールドと同じです。

データセット（PUT）の既存のラベルを更新する API 呼び出しを行う場合、データセットサービスのデータセットラベルエンティティの現在のバージョンを示す If-Match ヘッダーを含める必要があります。データの競合を防ぐため、含まれる If-Match 文字列が、そのデータセットのシステムで生成される最新のバージョンタグと一致する場合にのみ、データセットエンティティが更新されます。

データセットラベルエンティティの最新バージョンを取得するには、/datasets/{DATASET_ID}/labels エンドポイントに対して GET リクエストを実行します。現在の値は、応答の etag ヘッダーの下で返されます。既存のデータセットラベルを更新する場合、ベストプラクティスは、最新の etag 値を取得するために、最初にデータセットのルックアップリクエストを実行してから、後続の PUT リクエストの If-Match ヘッダーでその値を使用することです。

curl -X POST \
  'https://platform.adobe.io/data/foundation/dataset/datasets/5abd49645591445e1ba04f87/labels' \
  -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 '{
        "entityId": {
          "namespace": "AEP",
          "id": "test-ds-id",
          "type": "dataset"
        },
        "labels": [
          "C1"
        ],
        "parents": []
      } '

応答

応答が成功すると、データセットの更新されたラベルのセットが返されます。

{
  "parents": [
      {
        "id": "_ddgduleint.schemas.4a95cdba7d560e3bca7d8c5c7b58f00ca543e2bb1e4137d6",
        "type": "schema",
        "namespace": "AEP"
      }
  ],
  "optionalLabels": [],
  "labels": [
      "C1"
  ],
  "code": "PES-201",
  "message": "POST Successful"
}

データセットからラベルを削除する

以前に適用されたフィールドラベルを削除するには、既存のフィールドラベルのサブセットで既存の optionalLabels 値を更新するか、空のリストを更新して完全に削除します。Dataset Service API に PUT リクエストを送信して、以前に適用されたラベルを更新または削除します。

API 形式

PUT /datasets/{DATASET_ID}/labels

リクエスト

PUT 操作が適用される以下のデータセットには、properties/person/properties/address フィールドに C1 optionalLabel があり、/properties/person/properties/name/properties/fullName フィールドに C1、C2 optionalLabels がありました。PUT 操作の後、最初のフィールドにはラベルがなくなり（C1 ラベルが削除されました）、2 番目のフィールドには C1 ラベルのみが含まれます（C2 ラベルが削除されました）。

以下のサンプルシナリオでは、PUT リクエストを使用して、個々のフィールドに追加されたラベルを削除します。リクエストを行う前に、fullName フィールドには C1 および C2 ラベルが適用され、address フィールドには既に C1 ラベルが適用されていました。PUT リクエストは、optionalLabels.labels パラメーターを使用して、fullName フィールドの既存のラベルである C1, C2 ラベルを C1 ラベルで上書きします。また、このリクエストは、address フィールドの C1 ラベルを空のフィールドラベルのセットで上書きします。

curl -X PUT \
  'https://platform.adobe.io/data/foundation/dataset/datasets/5abd49645591445e1ba04f87/labels' \
  -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' \
  -H 'If-Match: 8f00d38e-0000-0200-0000-5ef4fc6d0000' \
  -d '{
        "entityId": {
          "namespace": "AEP",
          "id": "646b814d52e1691c07b41032",
          "type": "dataset"
        },
        "labels": [
          "C1"
        ],
        "parents": [
          {
            "id": "_xdm.context.identity-graph-flattened-export",
            "type": "schema",
            "namespace": "AEP"
          }
        ],
        "optionalLabels": [
          {
            "option": {
              "id": "https://ns.adobe.com/xdm/context/identity-graph-flattened-export",
              "contentType": "application/vnd.adobe.xed-full+json;version=1",
              "schemaPath": "/properties/person/properties/name/properties/fullName"
            },
            "labels": [
              "C1"
            ]
          },
          {
            "option": {
              "id": "https://ns.adobe.com/xdm/context/identity-graph-flattened-export",
              "contentType": "application/vnd.adobe.xed-full+json;version=1",
              "schemaPath": "/properties/person/properties/address"
            },
            "labels": []
          }
        ]
      }'

応答

応答が成功すると、データセットの更新されたラベルのセットが返されます。

{
  "parents": [
      {
        "id": "_xdm.context.identity-graph-flattened-export",
        "type": "schema",
        "namespace": "AEP"
      }
  ],
  "optionalLabels": [],
  "labels": [
      "C1"
  ],
  "code": "PES-200",
  "message": "PUT Successful"
}

次の手順

このドキュメントでは、Dataset Service APIを使用してデータセットとフィールドのデータ使用ラベルを管理する方法について説明しました。適用したラベルに基づいて、データ使用ポリシーとアクセス制御ポリシーを定義できるようになりました。

Experience Platform でのデータセットの管理について詳しくは、データセットの概要を参照してください。