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
パラメーター 説明
{DATASET_ID} 検索するラベルのデータセットの一意の id 値。

リクエスト

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" ]
      }
    ]
  }
}
プロパティ 説明
labels データセットに適用されたデータ使用ラベルのリスト。
optionalLabels データ使用ラベルが適用されたデータセット内の個々のフィールドのリスト。

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

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

API 形式

POST /datasets/{DATASET_ID}/labels
PUT /datasets/{DATASET_ID}/labels
パラメーター 説明
{DATASET_ID} ラベルを作成するデータセットの一意の id 値。

リクエスト

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

メモ

現在、問題のデータセットにラベルが存在する場合、新しいラベルは、PUTリクエスト ( If-Match ヘッダー。 データセットにラベルが追加されると、最新の etag 後でラベルを更新または削除するには、値が必要です。

データセットラベルエンティティの最新バージョンを取得するには、/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": []
      } '
プロパティ 説明
entityId 更新する特定のデータセットエンティティを識別します。
entityId.namespace これは、ID の競合を避けるために使用されます。 この namespaceAEP.
entityId.id 更新するリソースの ID。 これは、 datasetId.
entityId.type 更新するリソースのタイプ。 これは常に dataset.
labels データセット全体に追加するデータ使用ラベルのリストです。
parents この parents 配列には次のリストが含まれます: entityIdこのデータセットがラベルを継承する元の。 データセットは、スキーマやデータセットからラベルを継承できます。

応答

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

重要

この optionalLabels プロパティは、POSTリクエストで使用するため非推奨になりました。 データセットフィールドにデータラベルを追加できなくなりました。 POST操作は、 optionalLabel 値が存在する。 ただし、個々のフィールドからラベルを削除する場合は、PUTリクエストを使用し、 optionalLabels プロパティ。 詳しくは、 データセットからラベルを削除する.

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

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

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

API 形式

PUT /datasets/{DATASET_ID}/labels
パラメーター 説明
{DATASET_ID} ラベルを作成するデータセットの一意の id 値。

リクエスト

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要求は、既存のラベルを上書きします C1, C2 ラベル fullName フィールドに C1 ラベル optionalLabels.labels パラメーター。 また、このリクエストは C1 ラベル address フィールドには、空のフィールドラベルのセットが含まれます。

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": [],
        "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": []
          }
        ]
      }'
パラメーター 説明
entityId 更新する特定のデータセットエンティティを識別します。 この entityId には、次の 3 つの値を含める必要があります。

namespace:これは、ID の競合を避けるために使用されます。 この namespaceAEP.
id:更新するリソースの ID。 これは、 datasetId.
type:更新するリソースのタイプ。 これは常に dataset.
labels データセット全体に追加するデータ使用ラベルのリストです。
parents この parents 配列には次のリストが含まれます: entityIdこのデータセットがラベルを継承する元の。 データセットは、スキーマやデータセットからラベルを継承できます。
optionalLabels このパラメーターは、データセットフィールドに以前適用したラベルを削除するために使用されます。 データセット内の、ラベルを削除する個々のフィールドのリストです。 この配列の各アイテムは、次のプロパティを持つ必要があります。

option:フィールドの Experience Data Model(XDM)属性を含むオブジェクト。次の 3 つのプロパティが必要です。
  • id:フィールドに関連付けられているスキーマのURI $id値。
  • contentType:スキーマのコンテンツタイプとバージョン番号。XDM ルックアップリクエストに対しては、有効な Accept ヘッダーのいずれかの形式でおこなう必要があります。
  • schemaPath:データセットのスキーマ内のフィールドへのパス。
labels:この値は、適用される既存のフィールドラベルのサブセットを含むか、空にして既存のフィールドラベルをすべて削除する必要があります。 PUTまたはPOSTメソッドで、 optionalLabels フィールドに新しいラベルまたは変更されたラベルが含まれています。

応答

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

{
  "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 でのデータセットの管理について詳しくは、データセットの概要を参照してください。

このページ