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

O Dataset Service API permite aplicar e editar rótulos de uso para conjuntos de dados. Ela faz parte dos recursos de catálogo de dados da Adobe Experience Platform, mas é separada da API Catalog Service 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 o manual de ponto de extremidade de rótulos para o Policy Service API.

Introdução

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

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

Pesquisar rótulos para um conjunto de dados look-up

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 a API Dataset Service.

Formato da API

GET /datasets/{DATASET_ID}/labels

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

Aplicar rótulos a um conjunto de dados apply

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 a API Dataset Service. 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

Solicitação

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

Ao fazer chamadas de API que atualizam os rótulos existentes de um conjunto de dados (PUT), um cabeçalho If-Match que indica a versão atual da entidade do rótulo do conjunto de dados no Serviço de conjunto de dados deve ser incluído. Para evitar colisões de dados, o serviço só atualizará a entidade do conjunto de dados se a cadeia de caracteres If-Match incluída corresponder à marca da versão mais recente gerada pelo sistema para esse conjunto de dados.

GET Para recuperar a versão mais recente da entidade de rótulo do conjunto de dados, faça uma solicitação ao ponto de extremidade /datasets/{DATASET_ID}/labels. O valor atual é retornado na resposta sob um cabeçalho etag. 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 seu valor etag mais recente antes de usar esse valor no cabeçalho If-Match de sua 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": []
      } '

Resposta

Uma resposta bem-sucedida retorna o conjunto atualizado de rótulos para o 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 remove

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

Formato da API

PUT /datasets/{DATASET_ID}/labels

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 da solicitação ser feita, o campo fullName tinha os rótulos C1 e C2 aplicados, e o campo address já tinha um rótulo C1 aplicado. A solicitação PUT substitui rótulos C1, C2 existentes do campo fullName por um rótulo C1 usando o parâmetro optionalLabels.labels. A solicitação também substitui o rótulo C1 do campo address por 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": [
          {
            "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": []
          }
        ]
      }'

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 a API Dataset Service. 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 como gerenciar conjuntos de dados no Experience Platform, consulte a visão geral sobre conjuntos de dados.