Show Menu
TÓPICOS×

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 Catalog Service API que gerencia os 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 guia de ponto de extremidade de rótulos do Policy Service API.

Introdução

Antes de ler este guia, siga as etapas descritas na seção Catalog Service guia do desenvolvedor 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 pontos de extremidade contornados neste documento, é necessário ter o id valor exclusivo para um conjunto de dados específico. Se você não tiver esse valor, consulte o guia na listagem de objetos de Catálogo para localizar as IDs de seus conjuntos de dados existentes.

Procurar 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 de GET para a Dataset Service API.
Formato da API
GET /datasets/{DATASET_ID}/labels

Parâmetro
Descrição
{DATASET_ID}
O id valor exclusivo 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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta
Uma resposta bem-sucedida retorna os rótulos de uso de dados que foram aplicados ao conjunto de dados.
{
  "AEP:dataset:5abd49645591445e1ba04f87": {
    "imsOrg": "{IMS_ORG}",
    "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 criar um conjunto de rótulos para um conjunto de dados, fornecendo-os na carga de uma solicitação de POST ou PUT para a Dataset Service API. O uso de qualquer um desses métodos substitui quaisquer rótulos existentes e os substitui pelos fornecidos na carga.
Formato da API
POST /datasets/{DATASET_ID}/labels
PUT /datasets/{DATASET_ID}/labels

Parâmetro
Descrição
{DATASET_ID}
O id valor exclusivo do conjunto de dados para o qual você está criando rótulos.
Solicitação
A solicitação de PUT a seguir atualiza os rótulos existentes para um conjunto de dados, bem como um campo específico nesse conjunto de dados. Os campos fornecidos na carga são os mesmos que seriam necessários para uma solicitação de POST.
Um cabeçalho If-Match válido deve ser fornecido ao fazer solicitações de PUT ao ponto de /datasets/{DATASET_ID}/labels extremidade. Consulte a seção do apêndice para obter mais informações sobre como usar o cabeçalho necessário.
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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: 8f00d38e-0000-0200-0000-5ef4fc6d0000' \
  -d '{
        "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 você deseja adicionar ao conjunto de dados.
optionalLabels
Uma lista de qualquer campo individual no conjunto de dados ao qual você deseja adicionar rótulos. Cada item nesta matriz deve ter as seguintes propriedades:
option : Um objeto que contém os atributos Experience Data Model (XDM) do campo. As três propriedades a seguir são obrigatórias:
  • id: O valor URI $id do schema associado ao campo.
  • contentType: O tipo de conteúdo e o número da versão do schema. Isso deve assumir a forma de um dos cabeçalhos Pesquisar um recurso Accept válidos para uma solicitação de pesquisa XDM.
  • schemaPath: O caminho para o campo dentro do schema do conjunto de dados.
labels : Uma lista de rótulos de uso de dados que você deseja adicionar ao campo.
Resposta
Uma resposta bem-sucedida retorna os rótulos que foram adicionados ao conjunto de dados.
{
  "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" ]
    }
  ]
}

Remover rótulos de um conjunto de dados

Você pode remover os rótulos aplicados a um conjunto de dados, fazendo uma solicitação DELETE para a Dataset Service API.
Formato da API
DELETE /datasets/{DATASET_ID}/labels

Parâmetro
Descrição
{DATASET_ID}
O id valor exclusivo do conjunto de dados cujos rótulos você deseja remover.
Solicitação
A solicitação a seguir remove os rótulos do conjunto de dados especificado no caminho.
Um cabeçalho If-Match válido deve ser fornecido ao fazer solicitações de DELETE ao ponto de /datasets/{DATASET_ID}/labels extremidade. Consulte a seção do apêndice para obter mais informações sobre como usar o cabeçalho necessário.
curl -X DELETE \
  '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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'If-Match: 8f00d38e-0000-0200-0000-5ef4fc6d0000'

Resposta
Uma resposta com êxito HTTP status 200 (OK), indicando que os rótulos foram removidos. Você pode procurar os rótulos existentes para o conjunto de dados em uma chamada separada para confirmar isso.

Próximas etapas

Ao ler esse documento, você aprendeu a gerenciar rótulos de uso de dados para conjuntos de dados e campos usando a Dataset Service API.
Depois de adicionar rótulos de uso de dados no nível do conjunto de dados e do campo, você pode começar a assimilar dados em Experience Platform. Para saber mais, leia a documentação de ingestão de dados em start.
Agora você também pode definir políticas de uso de dados com base nos rótulos aplicados. Para obter mais informações, consulte a visão geral das políticas de uso de dados.
Para obter mais informações sobre como gerenciar conjuntos de dados em Experience Platform, consulte a visão geral Visão geral dos conjuntos de dados dos conjuntos de dados.

Apêndice

A seção a seguir contém informações adicionais sobre como trabalhar com rótulos usando a API de Serviço de Conjunto de Dados.

If-Match header

Ao fazer chamadas de API que atualizam os rótulos existentes de um conjunto de dados (PUT e DELETE), um If-Match cabeçalho que indica a versão atual da entidade dataset-label 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 string incluída corresponder à tag da versão mais recente gerada pelo sistema para esse conjunto de dados. If-Match
Se não houver etiquetas para o conjunto de dados em questão, as novas etiquetas só poderão ser adicionadas por meio de uma solicitação POST, o que não requer um If-Match cabeçalho. Depois que os rótulos forem adicionados a um conjunto de dados, um etag valor será atribuído e poderá 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 de GET para o /datasets/{DATASET_ID}/labels ponto de extremidade. O valor atual é retornado na resposta em um etag cabeçalho. Ao atualizar rótulos de conjunto de dados existentes, a prática recomendada é executar primeiro uma solicitação de pesquisa para o conjunto de dados para obter o etag valor mais recente antes de usar esse valor no cabeçalho If-Match da solicitação PUT ou DELETE subsequente.