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

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

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

快速入门

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

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

查找数据集的标签

您可以通过对以下项发出GET请求，查找已应用于现有数据集的数据使用标签： Dataset Service API。

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 以后更新或删除标签时需要值。

要检索最新版本的dataset-label实体，请将 GET请求到 /datasets/{DATASET_ID}/labels 端点。当前值在响应中返回，位于 etag 标头。更新现有数据集标签时，最佳实践是首先执行数据集的查找请求，以获取其最新数据 etag 值之前，该值的使用范围 If-Match 后续PUT请求的标头。

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标签被移除），而第二字段将只有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` 必须包括以下三个值： `namespace`：用于避免ID冲突。此 `namespace` 是 `AEP`. `id`：要更新的资源的ID。此名称是指 `datasetId`. `type`：正在更新的资源的类型。这将始终是 `dataset`.
`labels`	要添加到整个数据集的数据使用标签列表。
`parents`	此 `parents` 数组包含列表 `entityId`此数据集将从中继承标签的位置。数据集可以从架构和/或数据集继承标签。
`optionalLabels`	此参数用于移除先前应用于数据集字段的标签。数据集内要从中删除标签的任何单独字段的列表。此数组中的每一项都必须具有以下属性： `option`：包含 Experience Data Model (XDM)字段的属性。需要以下三个属性： id：URI $id 与字段关联的架构的值。内容类型：架构的内容类型和版本号。这应该采用有效的形式之一接受标头 XDM查找请求。 schema路径：数据集架构中字段的路径。 `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，请参见数据集概述.

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

快速入门

查找数据集的标签

将标签应用于数据集

从数据集中删除标签

后续步骤

Business.Adobe.com 资源

在此页面上

查看下一个：

学习

文档

社区

技术支持

资源

Adobe 帐户

Adobe