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 の競合を避けるために使用されます。 この namespace が AEP . |
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 の競合を避けるために使用されます。 この namespace が AEP .id :更新するリソースの ID。 これは、 datasetId .type :更新するリソースのタイプ。 これは常に dataset . |
labels |
データセット全体に追加するデータ使用ラベルのリストです。 |
parents |
この parents 配列には次のリストが含まれます: entityId このデータセットがラベルを継承する元の。 データセットは、スキーマやデータセットからラベルを継承できます。 |
optionalLabels |
このパラメーターは、データセットフィールドに以前適用したラベルを削除するために使用されます。 データセット内の、ラベルを削除する個々のフィールドのリストです。 この配列の各アイテムは、次のプロパティを持つ必要があります。option :フィールドの Experience Data Model(XDM)属性を含むオブジェクト。次の 3 つのプロパティが必要です。
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 でのデータセットの管理について詳しくは、データセットの概要を参照してください。