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" ]
      }
    ]
  }
}

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

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

API 形式

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

リクエスト

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

データセットラベルエンティティの最新バージョンを取得するには、/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 値を持つ既存のフィールドラベルのサブセット、または完全に削除する空のリスト。 へのPUTリクエスト Dataset Service 以前に適用したラベルを更新または削除する API。

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要求は、既存のラベルを上書きします 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": []
          }
        ]
      }'

応答

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

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

Business.Adobe.com リソース