Gerenciar rótulos de uso de dados para conjuntos de dados usando APIs

A variável Dataset Service API O permite aplicar e editar rótulos de uso para conjuntos de dados. Isso faz parte dos recursos do catálogo de dados da Adobe Experience Platform, mas é separado da variável Catalog Service API que gerencia metadados do conjunto de dados.

Este documento aborda como gerenciar rótulos para conjuntos de dados e campos usando o Dataset Service API. Para obter etapas sobre como gerenciar os próprios rótulos de uso de dados usando chamadas de API, consulte a seção guia de endpoint de rótulos para o Policy Service API.

Introdução

Antes de ler este guia, siga as etapas descritas na seção seção de introdução no guia do desenvolvedor do Catálogo para coletar as credenciais necessárias para fazer chamadas para Platform APIs.

Para fazer chamadas para os endpoints descritos neste documento, você deve ter o id para um conjunto de dados específico. Se você não tiver esse valor, consulte o manual sobre listando objetos do Catálogo para encontrar as IDs dos conjuntos de dados existentes.

Pesquisar rótulos para um conjunto de dados

Você pode pesquisar os rótulos de uso de dados que foram aplicados a um conjunto de dados existente fazendo uma solicitação GET para o Dataset Service API.

Formato da API

GET /datasets/{DATASET_ID}/labels
Parâmetro Descrição
{DATASET_ID} O único id valor do conjunto de dados cujos rótulos você deseja pesquisar.

Solicitação

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

Resposta

Uma resposta bem-sucedida retorna os rótulos de uso de dados aplicados ao conjunto de dados.

{
  "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" ]
      }
    ]
  }
}
Propriedade Descrição
labels Uma lista de rótulos de uso de dados que foram aplicados ao conjunto de dados.
optionalLabels Uma lista de campos individuais no conjunto de dados que têm rótulos de uso de dados aplicados a eles.

Aplicar rótulos a um conjunto de dados

Você pode aplicar um conjunto de rótulos para um conjunto de dados inteiro fornecendo-os na carga de uma solicitação POST ou PUT para o Dataset Service API. O corpo da solicitação é o mesmo para ambas as chamadas. Não é possível adicionar rótulos a campos de conjunto de dados individuais.

Formato da API

POST /datasets/{DATASET_ID}/labels
PUT /datasets/{DATASET_ID}/labels
Parâmetro Descrição
{DATASET_ID} O único id valor do conjunto de dados para o qual você está criando rótulos.

Solicitação

O exemplo de solicitação POST abaixo atualiza todo o conjunto de dados com um C1 rótulo. Os campos fornecidos na carga são os mesmos que seriam necessários para uma solicitação PUT.

OBSERVAÇÃO

Se houver rótulos para o conjunto de dados em questão, novos rótulos só poderão ser adicionados por meio de uma solicitação PUT, o que requer um If-Match cabeçalho. Depois que os rótulos forem adicionados a um conjunto de dados, uma variável etag é atribuído um valor que pode ser usado para atualizar ou remover os rótulos posteriormente.

Para recuperar a versão mais recente da entidade de rótulo do conjunto de dados, faça uma solicitação GET para o /datasets/{DATASET_ID}/labels terminal. O valor atual é retornado na resposta sob um etag cabeçalho. Ao atualizar rótulos de conjuntos de dados existentes, a prática recomendada é executar primeiro uma solicitação de pesquisa para o conjunto de dados para buscar o mais recente etag antes de usar esse valor na variável If-Match cabeçalho da solicitação PUT subsequente.

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": []
      } '
Propriedade Descrição
entityId Isso identifica a entidade do conjunto de dados específico que deve ser atualizada.
entityId.namespace Isso é usado para evitar colisões de ID. A variável namespace é AEP.
entityId.id A ID do recurso sendo atualizado. Refere-se ao datasetId.
entityId.type O tipo do recurso que está sendo atualizado. Isso sempre será dataset.
labels Uma lista de rótulos de uso de dados que você deseja adicionar ao conjunto de dados inteiro.
parents A variável parents matriz contém uma lista de entityIdpara que esse conjunto de dados herde rótulos do. Os conjuntos de dados podem herdar rótulos de esquemas e/ou conjuntos de dados.

Resposta

Uma resposta bem-sucedida retorna o conjunto atualizado de rótulos para o conjunto de dados.

IMPORTANTE

A variável optionalLabels A propriedade foi descontinuada para uso com solicitações POST. Não é mais possível adicionar rótulos de dados a campos de conjunto de dados. Uma operação POST emitirá um erro se uma optionalLabel valor está presente. No entanto, é possível excluir rótulos de campos individuais usando uma solicitação PUT e a variável optionalLabels propriedade. Para obter mais informações, consulte a seção sobre remoção de rótulos de um conjunto de dados.

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

Remover rótulos de um conjunto de dados

Você pode remover qualquer rótulo de campo aplicado anteriormente atualizando o existente optionalLabels valor(es) com um subconjunto dos rótulos de campo existentes ou uma lista vazia para removê-los totalmente. Faça uma solicitação PUT para o Dataset Service API para atualizar ou remover rótulos aplicados anteriormente.

Formato da API

PUT /datasets/{DATASET_ID}/labels
Parâmetro Descrição
{DATASET_ID} O único id valor do conjunto de dados para o qual você está criando rótulos.

Solicitação

O conjunto de dados abaixo no qual a operação PUT é aplicada tinha C1 optionalLabel no campo properties/person/properties/address e C1, C2 optionalLabels no campo /properties/person/properties/name/properties/fullName. Após a operação put, o primeiro campo não terá rótulo (o rótulo C1 foi removido) e o segundo campo terá apenas o rótulo C1 (o rótulo C2 foi removido)

No exemplo de cenário abaixo, uma solicitação PUT é usada para remover rótulos adicionados a campos individuais. Antes de o pedido ser apresentado, a fullName o campo tinha o C1 e C2 rótulos aplicados e a variável address o campo já tinha um C1 rótulo aplicado. A solicitação PUT substitui os rótulos existentes C1, C2 rótulos do fullName campo com um C1 rótulo usando o optionalLabels.labels parâmetro. A solicitação também substitui a variável C1 rótulo do address com um conjunto vazio de rótulos 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": [],
        "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": []
          }
        ]
      }'
Parâmetro Descrição
entityId Isso identifica a entidade do conjunto de dados específico que deve ser atualizada. A variável entityId deve incluir os três valores a seguir:

namespace: é usado para evitar colisões de ID. A variável namespace é AEP.
id: a ID do recurso que está sendo atualizado. Refere-se ao datasetId.
type: o tipo de recurso que está sendo atualizado. Isso sempre será dataset.
labels Uma lista de rótulos de uso de dados que você deseja adicionar ao conjunto de dados inteiro.
parents A variável parents matriz contém uma lista de entityIdpara que esse conjunto de dados herde rótulos do. Os conjuntos de dados podem herdar rótulos de esquemas e/ou conjuntos de dados.
optionalLabels Esse parâmetro é usado para remover rótulos aplicados anteriormente a um campo de conjunto de dados. Uma lista de campos individuais no conjunto de dados do qual você deseja remover os rótulos. Cada item nesta matriz deve ter as seguintes propriedades:

option: um objeto que contém a variável Experience Data Model Atributos de (XDM) do campo. As três propriedades a seguir são obrigatórias:
  • id: a $id de URI valor do schema associado ao campo.
  • contentType: O tipo de conteúdo e o número da versão do esquema. Esta deve assumir a forma de um dos Aceitar cabeçalhos para uma solicitação de pesquisa XDM.
  • schemaPath: O caminho para o campo no esquema do conjunto de dados.
labels: esse valor deve conter um subconjunto dos rótulos de campo existentes aplicados ou estar vazio para remover todos os rótulos de campo existentes. Os métodos PUT ou POST agora retornam um erro se a variável optionalLabels O campo tem rótulos novos ou modificados.

Resposta

Uma resposta bem-sucedida retorna o conjunto atualizado de rótulos para o conjunto de dados.

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

Próximas etapas

Ao ler este documento, você aprendeu a gerenciar rótulos de uso de dados para conjuntos de dados e campos usando o Dataset Service API. Agora você pode definir políticas de uso de dados e políticas de controle de acesso com base nos rótulos aplicados.

Para obter mais informações sobre o gerenciamento de conjuntos de dados no Experience Platform, consulte o visão geral dos conjuntos de dados.

Nesta página