Usar domínios de dados

Os domínios de dados no Knowledge Catalog (antigo Dataplex Universal Catalog) permitem restringir os resultados da pesquisa a contextos de negócios específicos e descobrir metadados dentro de limites definidos. Como usuário do domínio de dados, é possível navegar pela hierarquia do domínio, pesquisar recursos do domínio e recuperar o contexto do domínio para embasar agentes de IA.

Antes de começar

Antes de realizar uma pesquisa por domínio, verifique se você tem os papéis e as APIs necessários ativados.

Ativar APIs

Ative a API Dataplex, se ainda não tiver feito isso.

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar a API

Funções exigidas

Para receber as permissões necessárias para pesquisar e descobrir metadados usando domínios de dados, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto ou domínio de dados:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Navegar pela hierarquia de domínios

Para mais informações sobre como navegar na hierarquia de domínios, consulte Ver domínios e subdomínios de dados em um local.

Encontrar recursos em um domínio de dados

É possível pesquisar em um domínio de dados para encontrar recursos como conjuntos de dados, tabelas e produtos de dados do BigQuery e visualizar os metadados deles. Para pesquisar recursos em um domínio, siga estas etapas:

Console

  1. No console do Google Cloud , acesse a página Knowledge Catalog > Pesquisa.

    Acesse Pesquisar

  2. Clique em Testar a pesquisa natural para ativar o recurso de pesquisa natural.

  3. Clique em Filtros.

  4. No campo Escopo, selecione Domínio na lista.

  5. No campo Selecionar domínio, selecione o domínio para restringir os resultados. Adicione outros filtros, se necessário.

Como alternativa, use a opção de menu Pesquisar no domínio para encontrar recursos no domínio:

  1. No console do Google Cloud , acesse a página Domínios de dados.

    Acesse "Domínios de dados"

  2. Selecione Pesquisar no domínio no menu . Essa ação abre automaticamente uma janela de pesquisa com o filtro domain aplicado.

  3. Use o campo de pesquisa para encontrar recursos no domínio.

REST

Para pesquisar entradas com escopo em um domínio de dados, use o método projects.locations.searchEntries e forneça o caminho do domínio no parâmetro contexts.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • LOCATION_ID: a região da consulta de pesquisa (ou global).
  • QUERY: a string de consulta de pesquisa.
  • DOMAIN_ID: o identificador exclusivo do domínio de dados que define o contexto do escopo de pesquisa.

Método HTTP e URL: 

POST https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID:searchEntries

Corpo JSON da solicitação:

{
  "query": "QUERY",
  "contexts": [ "projects/PROJECT_ID/locations/LOCATION_ID/dataDomains/DOMAIN_ID" ],
  "semantic_search": true,
  "page_size": 100
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.

Recuperar contexto para domínios de dados

Use o método lookupContext para embasar os agentes de IA no contexto de negócios capturado pelos seus domínios de dados. O método lookupContext é compatível com domínios de dados das seguintes maneiras:

  • Contexto de um domínio de dados. É possível transmitir a entrada que representa um domínio de dados na lista resources. A resposta contém os metadados do domínio de dados, como a descrição e os domínios de dados pai na hierarquia de domínios.
  • Associação de domínio de dados de recursos de dados. Ao recuperar o contexto de um recurso de dados incluído em um ou mais domínios de dados, a resposta contém um campo dataDomains que lista os domínios de dados aos quais o recurso pertence, começando pelo domínio mais específico e subindo até o domínio de nível superior.

Para recuperar o contexto de um domínio de dados, envie a seguinte solicitação:

curl --request POST \
  'https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext' \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H 'Content-Type: application/json' \
  -d '{
    "resources": [
      "projects/PROJECT_ID/locations/LOCATION/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION/dataDomains/DATA_DOMAIN_ID"
    ],
    "options": {
      "format": "yaml"
    }
  }'

Substitua:

  • PROJECT_ID: o ID do projeto que contém o domínio de dados.
  • PROJECT_NUMBER: o número do projeto que contém o domínio de dados.
  • LOCATION: o local do domínio de dados.
  • DATA_DOMAIN_ID: o ID do domínio de dados.

Para mais informações sobre o método lookupContext, consulte Recuperar contexto para recursos de dados.

Limitações

Quando você pesquisa recursos fora do contexto do domínio, por exemplo, ao usar uma pesquisa global, as permissões de descoberta do domínio não se aplicam. Você só vê os recursos que pode acessar no sistema, como o BigQuery.

Suponha que um conjunto de dados do BigQuery esteja incluído em um domínio de dados. Você tem o papel Dataplex Data Domain Entry Reader no domínio, mas não tem permissão direta para visualizar o conjunto de dados no BigQuery:

  • Pesquisa no domínio:o conjunto de dados aparece nos resultados da pesquisa porque as permissões do domínio são aplicáveis.
  • Pesquisa fora do domínio:o conjunto de dados não aparece nos resultados da pesquisa. Em uma pesquisa genérica, as permissões de domínio não se aplicam e você não tem acesso direto no BigQuery.

A seguir