文档Experience PlatformData Governance 指南

使用API管理数据集的数据使用标签

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主题：

创建对象：

  • undefined
  • undefined
  • undefined

Dataset Service API允许您应用和编辑数据集的使用标签。 它是Adobe Experience Platform数据目录功能的一部分，但与管理数据集元数据的Catalog Service API不同。

IMPORTANT
仅数据管理用例支持在数据集级别应用标签。 如果尝试创建数据的访问策略，则必须将标签应用于数据集所基于的架构。 有关详细信息，请参阅基于属性的访问控制的概述。

本文档介绍如何使用Dataset Service API管理数据集和字段的标签。 有关如何使用API调用管理数据使用标签本身的步骤，请参阅Policy Service API的标签端点指南。

快速入门

在阅读本指南之前，请按照《目录开发人员指南》的入门部分中所述的步骤来收集调用Platform API所需的凭据。

要调用本文档中概述的端点，您必须具有特定数据集的唯一id值。 如果没有此值，请参阅列出目录对象上的指南以查找现有数据集的ID。

查找数据集的标签 look-up

通过向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
数据集内已应用数据使用标签的单独字段列表。

将标签应用于数据集 apply

通过在POST或PUT请求的有效负荷中向Dataset Service API提供一组标签，您可以为整个数据集应用一组标签。 两个调用的请求正文相同。 您无法将标签添加到单独的数据集字段。

API格式

POST /datasets/{DATASET_ID}/labels
PUT /datasets/{DATASET_ID}/labels
参数
描述
{DATASET_ID}
您为其创建标签的数据集的唯一id值。

请求

下面的示例POST请求使用C1标签更新整个数据集。 有效负载中提供的字段与PUT请求所需的字段相同。

当进行API调用以更新数据集(PUT)的现有标签时，必须包括一个If-Match标头，以指示数据集服务中dataset-label实体的当前版本。 为避免数据冲突，仅当包含的If-Match字符串与系统为该数据集生成的最新版本标记匹配时，服务才会更新数据集实体。

NOTE
如果相关数据集当前存在标签，则只能通过PUT请求添加新标签，该请求需要If-Match标头。 将标签添加到数据集后，以后需要最新的etag值来更新或删除标签
在执行PUT方法之前，必须对数据集标签执行GET请求。 确保仅更新请求中要修改的特定字段，而其余字段保持不变。 此外，确保PUT调用维护与GET调用相同的父实体。 任何差异都会导致客户出错。

要检索最新版本的dataset-label实体，请向/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的列表。 数据集可以从架构和/或数据集继承标签。

响应

成功的响应将返回数据集的更新标签集。

IMPORTANT
已弃用optionalLabels属性以用于POST请求。 无法再将数据标签添加到数据集字段。 如果存在optionalLabel值，则POST操作将引发错误。 但是，您可以使用PUT请求和optionalLabels属性从单个字段删除标签。 有关详细信息，请参阅从数据集中删除标签一节。
{
  "parents": [
      {
        "id": "_ddgduleint.schemas.4a95cdba7d560e3bca7d8c5c7b58f00ca543e2bb1e4137d6",
        "type": "schema",
        "namespace": "AEP"
      }
  ],
  "optionalLabels": [],
  "labels": [
      "C1"
  ],
  "code": "PES-201",
  "message": "POST Successful"
}

从数据集中删除标签 remove

您可以通过更新具有现有字段标签子集的现有optionalLabels值，或通过使用空列表完全删除它们，来删除任何以前应用的字段标签。 向Dataset Service API发出PUT请求以更新或删除以前应用的标签。

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标签被删除），而第二字段将只有C1标签（C2标签被删除）

在下面的示例场景中，PUT请求用于移除添加到单个字段的标签。 在发出请求之前，fullName字段已应用C1和C2标签，并且address字段已应用C1标签。 PUT请求使用optionalLabels.labels参数覆盖具有C1标签的fullName字段中的现有标签C1, C2标签。 该请求还会使用一组空的字段标签覆盖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": []
          }
        ]
      }'
参数
描述
entityId
这将标识要更新的特定数据集实体。 entityId必须包括以下三个值：

namespace：用于避免ID冲突。 namespace是AEP。
id：正在更新的资源的ID。 这是对datasetId的引用。
type：正在更新的资源的类型。 这将始终为dataset。
labels
要添加到整个数据集的数据使用标签列表。
parents
parents数组包含此数据集将继承其标签的entityId的列表。 数据集可以从架构和/或数据集继承标签。
optionalLabels

此参数用于移除先前应用于数据集字段的标签。 数据集中要从中删除标签的任何单独字段的列表。 此数组中的每个项都必须具有以下属性：

option：包含字段的Experience Data Model (XDM)属性的对象。 需要以下三个属性：

  • id： URI $id 与字段关联的架构的值。
  • 内容类型：架构的内容类型和版本号。 这应该采用XDM查找请求的有效接受标头的形式。
  • 架构路径：数据集架构中字段的路径。

labels：此值必须包含应用的现有字段标签的子集，或者为空以删除所有现有字段标签。 如果optionalLabels字段具有任何新标签或修改的标签，则PUT或POST方法现在会返回错误。

响应

成功的响应将返回数据集的更新标签集。

{
  "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中数据集的详细信息，请参阅数据集概述。

recommendation-more-help
834e0cae-2761-454a-be4d-62f0fd4b4456