Administrar etiquetas de uso de datos para conjuntos de datos mediante API

Dataset Service API le permite aplicar y editar etiquetas de uso para conjuntos de datos. Forma parte de las funciones del catálogo de datos de Adobe Experience Platform, pero es independiente de la API Catalog Service que administra los metadatos del conjunto de datos.

Este documento explica cómo administrar etiquetas para conjuntos de datos y campos mediante Dataset Service API. Para ver los pasos sobre cómo administrar las propias etiquetas de uso de datos mediante llamadas API, consulte la guía de extremo de etiquetas para Policy Service API.

Introducción

Antes de leer esta guía, siga los pasos descritos en la sección de introducción en la guía para desarrolladores de catálogos para recopilar las credenciales necesarias para realizar llamadas a las API de Platform.

Para realizar llamadas a los extremos descritos en este documento, debe tener el valor id único para un conjunto de datos específico. Si no tiene este valor, consulte la guía en listar objetos de catálogo para encontrar los ID de los conjuntos de datos existentes.

Búsqueda de etiquetas para un conjunto de datos look-up

Puede buscar las GET de uso de datos que se han aplicado a un conjunto de datos existente realizando una solicitud a la API Dataset Service.

Formato de API

GET /datasets/{DATASET_ID}/labels

Solicitud

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}'

Respuesta

Una respuesta correcta devuelve las etiquetas de uso de datos aplicadas al conjunto de datos.

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

Aplicar etiquetas a un conjunto de datos apply

Puede aplicar un conjunto de etiquetas para un conjunto de datos completo proporcionándolas en la carga útil de una solicitud de POST o PUT a la API Dataset Service. El cuerpo de la solicitud es el mismo para ambas llamadas. No puede agregar etiquetas a campos de conjuntos de datos individuales.

Formato de API

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

Solicitud

La siguiente solicitud de POST de ejemplo actualiza todo el conjunto de datos con la etiqueta C1. Los campos proporcionados en la carga útil son los mismos que se requerirían para una solicitud de PUT.

Cuando se realizan llamadas de API que actualizan las etiquetas existentes de un conjunto de datos (PUT), se debe incluir un encabezado If-Match que indique la versión actual de la entidad dataset-label en el servicio Dataset. Para evitar conflictos de datos, el servicio solo actualizará la entidad del conjunto de datos si la cadena If-Match incluida coincide con la última etiqueta de versión generada por el sistema para ese conjunto de datos.

Para recuperar la versión más reciente de la entidad dataset-label, realice una solicitud de GET al extremo /datasets/{DATASET_ID}/labels. El valor actual se devuelve en la respuesta bajo un encabezado etag. Al actualizar las etiquetas de conjuntos de datos existentes, se recomienda realizar primero una solicitud de búsqueda para el conjunto de datos a fin de recuperar su último valor etag antes de utilizar ese valor en el encabezado If-Match de la solicitud de PUT posterior.

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": []
      } '

Respuesta

Una respuesta correcta devuelve el conjunto actualizado de etiquetas para el conjunto de datos.

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

Eliminación de etiquetas de un conjunto de datos remove

Puede quitar cualquier etiqueta de campo aplicada anteriormente actualizando los valores de optionalLabels existentes con un subconjunto de las etiquetas de campo existentes o con una lista vacía para quitarlos por completo. Realice una solicitud de PUT a la API Dataset Service para actualizar o quitar las etiquetas aplicadas anteriormente.

Formato de API

PUT /datasets/{DATASET_ID}/labels

Solicitud

El siguiente conjunto de datos en el que se aplica la operación de PUT tenía el campo C1 optionalLabel en properties/person/properties/address y el campo C1, C2 optionalLabels en /properties/person/properties/name/properties/fullName. Después de la operación de colocación, el primer campo no tendrá etiqueta (se eliminó la etiqueta C1) y el segundo campo solo tendrá etiqueta C1 (se eliminó la etiqueta C2)

En el siguiente escenario de ejemplo, se utiliza una solicitud de PUT para eliminar las etiquetas agregadas a campos individuales. Antes de realizar la solicitud, el campo fullName tenía aplicadas las etiquetas C1 y C2, y el campo address ya tenía aplicada una etiqueta C1. La solicitud de PUT reemplaza las etiquetas existentes C1, C2 del campo fullName con una etiqueta C1 que usa el parámetro optionalLabels.labels. La solicitud también invalida la etiqueta C1 del campo address con un conjunto vacío de etiquetas de campo.

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": []
          }
        ]
      }'

Respuesta

Una respuesta correcta devuelve el conjunto actualizado de etiquetas para el conjunto de datos.

{
  "parents": [
      {
        "id": "_xdm.context.identity-graph-flattened-export",
        "type": "schema",
        "namespace": "AEP"
      }
  ],
  "optionalLabels": [],
  "labels": [
      "C1"
  ],
  "code": "PES-200",
  "message": "PUT Successful"
}

Pasos siguientes

Al leer este documento, ha aprendido a administrar las etiquetas de uso de datos para conjuntos de datos y campos mediante la API Dataset Service. Ahora puede definir políticas de uso de datos y políticas de control de acceso en función de las etiquetas que haya aplicado.

Para obtener más información sobre la administración de conjuntos de datos en Experience Platform, vea la descripción general de conjuntos de datos.