Enviar resultados da inspeção para o Knowledge Catalog como aspectos

Neste documento, descrevemos como inspecionar uma tabela do BigQuery em busca de dados sensíveis e enviar os resultados da inspeção ao Knowledge Catalog. Essa ação adiciona automaticamente um aspecto à entrada do Knowledge Catalog associada à tabela do BigQuery.

Este documento também fornece exemplos de consultas que podem ser usadas para encontrar dados na sua organização e em projetos com valores de aspecto específicos.

Esse recurso é útil se você quiser enriquecer seus metadados no Knowledge Catalog com classificações de dados sensíveis de jobs de inspeção da Proteção de Dados Sensíveis.

Os aspectos gerados incluem os seguintes detalhes:

• O nome do job de inspeção
• Os tipos de informação (infoTypes) detectados na tabela

Sobre o Knowledge Catalog

O Knowledge Catalog oferece um inventário unificado de Google Cloud recursos.

O Knowledge Catalog permite usar aspectos para adicionar metadados comerciais e técnicos aos seus dados para capturar o contexto e o conhecimento sobre seus recursos. Em seguida, você pode pesquisar e descobrir dados na sua organização e ativar a governança de dados nos seus recursos de dados. Para mais informações, consulte Aspectos.

Como funciona

Para criar automaticamente aspectos do Knowledge Catalog com base nos resultados do job de inspeção, siga este fluxo de trabalho de alto nível:

1. Crie ou edite um job de inspeção que inspecione uma tabela do BigQuery. Para instruções, consulte Inspecionar uma tabela do BigQuery.

2. Na etapa Adicionar ações, ative a opção Publicar no Dataplex Universal Catalog.

A Proteção de Dados Sensíveis adiciona ou atualiza o Sensitive Data Protection job result aspecto da entrada do Knowledge Catalog associada à tabela do BigQuery. Em seguida, você pode pesquisar no Knowledge Catalog todos os dados da sua organização ou projeto com valores de aspecto específicos. Para exemplos de consultas, consulte Exemplos de consultas de pesquisa neste documento.

O aspecto do Knowledge Catalog resultante é armazenado no mesmo projeto e região da tabela do BigQuery.

Campos de aspecto

O aspecto Sensitive Data Protection job result tem os seguintes campos:

Nome do job

O nome completo do recurso do job de inspeção, por exemplo, projects/example-project/locations/us/dlpJobs/i-8992079400000000000.

Contagens de InfoType

Nomes de InfoType que o job de inspeção pesquisou, conforme especificado na configuração de inspeção, e a contagem de descobertas para cada InfoType. Um InfoType que não tem descobertas tem uma contagem de 0.

Horário de término

A data e a hora em que o job de inspeção terminou.

É uma verificação completa

Indica se o job de inspeção verificou todas as linhas da tabela. Se a amostragem estiver ativada no job de inspeção, por exemplo, o valor desse campo será False.

Tem descobertas

Indica se o job de inspeção detectou algum dos InfoTypes que ele verificou.

Ativar a API Dataplex

A API Dataplex precisa ser ativada em cada projeto que contém dados para os quais você quer adicionar aspectos. Esta seção descreve como ativar a API Dataplex em um único projeto ou em todos os projetos de uma organização ou pasta.

Ativar a API Dataplex em um único projeto

1. Selecione o projeto em que você quer ativar a API Dataplex.

   Acessar o seletor de projetos

2. Ativar a API Dataplex.

   Funções necessárias para ativar APIs

   Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

   Ativar a API

Ativar a API Dataplex em todos os projetos de uma organização ou pasta

Esta seção fornece um script que pesquisa todos os projetos em uma organização ou pasta e ativa a API Dataplex em cada um deles.

Para ter as permissões necessárias para ativar a API Dataplex em todos os projetos de uma organização ou pasta, peça ao administrador para conceder a você os seguintes papéis do IAM:

• Leitor de recursos do Cloud (roles/cloudasset.viewer) na organização ou pasta
• Usuário de DLP (roles/dlp.user) em cada projeto em que você quer ativar a API Dataplex

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

Esses papéis predefinidos têm as permissões necessárias para ativar a API Dataplex em todos os projetos de uma organização ou pasta. Para acessar as permissões exatas que são necessárias, expanda a seção Permissões necessárias:

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Para ativar a API Dataplex em todos os projetos de uma organização ou pasta, siga estas etapas:

1. No Google Cloud console, ative o Cloud Shell.

   Ativar o Cloud Shell

   Na parte de baixo do Google Cloud console, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a Google Cloud CLI já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

2. Execute o script a seguir:

   #!/bin/bash
   
   RESOURCE_ID="RESOURCE_ID"
   
   gcloud asset search-all-resources \
       --scope="RESOURCE_TYPE/$RESOURCE_ID" \
       --asset-types="cloudresourcemanager.googleapis.com/Project" \
       --format="value(name)" |
       while read project_name; do
         project_id=$(echo "$project_name" | sed 's|.*/||')
         gcloud services enable "dataplex.googleapis.com" --project="$project_id"
       done
   

   Substitua:

   • RESOURCE_ID: o número da organização ou da pasta do recurso que contém os projetos
   • RESOURCE_TYPE: o tipo de recurso que contém os projetos: organizations ou folders

Funções e permissões para visualizar aspectos

Para ter as permissões necessárias para buscar aspectos associados à tabela do BigQuery, peça ao administrador para conceder a você os seguintes papéis do IAM na tabela:

• Leitor do catálogo do Dataplex (roles/dataplex.catalogViewer)
• Visualizador de dados do BigQuery (roles/bigquery.dataViewer)

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

Esses papéis predefinidos têm as permissões necessárias para pesquisar aspectos associados à tabela do BigQuery. Para acessar as permissões exatas que são necessárias, expanda a seção Permissões necessárias:

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Para mais informações sobre as permissões necessárias para usar Knowledge Catalog, consulte Permissões do IAM do Knowledge Catalog.

Configurar e executar um job de inspeção da Proteção de Dados Sensíveis

É possível configurar e executar um job de inspeção da Proteção de Dados Sensíveis usando o Google Cloud console ou a API DLP.

POST https://dlp.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/dlpJobs

{
              "inspectJob":
              {
                "storageConfig":
                {
                  "bigQueryOptions":
                  {
                    "tableReference":
                    {
                      "projectId": "PROJECT_ID",
                      "datasetId": "BIGQUERY_DATASET_NAME",
                      "tableId": "BIGQUERY_TABLE_NAME"
                    }
                  }
                },
                "inspectConfig":
                {
                  "infoTypes":
                  [
                    {
                      "name": "EMAIL_ADDRESS"
                    },
                    {
                      "name": "PERSON_NAME"
                    },
                    {
                      "name": "US_SOCIAL_SECURITY_NUMBER"
                    },
                    {
                      "name": "PHONE_NUMBER"
                    }
                  ],
                  "includeQuote": true,
                  "minLikelihood": "UNLIKELY",
                  "limits":
                  {
                    "maxFindingsPerRequest": 100
                  }
                },
                "actions":
                [
                  {
                    "publishFindingsToDataplexCatalog": {}
                  }
                ]
              }
            }

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @inspect-request.json \
     "https://dlp.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/dlpJobs"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile inspect-request.json `
    -Uri "https://dlp.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/dlpJobs" | Select-Object -Expand Content

{
  "name": "projects/PROJECT_ID/locations/LOCATION/dlpJobs/JOB_ID",
  "type": "INSPECT_JOB",
  "state": "PENDING",
  "inspectDetails": {
    "requestedOptions": {
      "snapshotInspectTemplate": {},
      "jobConfig": {
        "storageConfig": {
          "bigQueryOptions": {
            "tableReference": {
              "projectId": "PROJECT_ID",
              "datasetId": "BIGQUERY_DATASET_NAME",
              "tableId": "BIGQUERY_TABLE_NAME"
            }
          }
        },
        "inspectConfig": {
          "infoTypes": [
            {
              "name": "EMAIL_ADDRESS"
            },
            {
              "name": "PERSON_NAME"
            },
            {
              "name": "US_SOCIAL_SECURITY_NUMBER"
            },
            {
              "name": "PHONE_NUMBER"
            }
          ],
          "minLikelihood": "UNLIKELY",
          "limits": {
            "maxFindingsPerRequest": 100
          },
          "includeQuote": true
        },
        "actions": [
          {
            "publishFindingsToDataplexCatalog": {}
          }
        ]
      }
    },
    "result": {}
  },
  "createTime": "2025-09-09T00:29:55.951374Z",
  "lastModified": "2025-09-09T00:29:58.022967Z"
}

Para informações sobre como receber os resultados do job de inspeção usando a API DLP, consulte Receber um job.

Exemplo de consultas de pesquisa

Esta seção fornece exemplos de consultas de pesquisa que podem ser usadas no Knowledge Catalog para encontrar dados na sua organização ou projeto com valores de aspecto específicos.

Você só pode encontrar os dados a que tem acesso. O acesso aos dados é controlado por permissões do IAM. Para mais informações, consulte Funções e permissões para visualizar aspectos neste documento.

É possível inserir esses exemplos de consultas no campo Pesquisar na página Pesquisa do Knowledge Catalog.

Acesse Pesquisar

Para informações sobre como formar as consultas, consulte Sintaxe de pesquisa do Knowledge Catalog.

Encontrar as entradas de todas as tabelas que têm o aspecto de resultado do job da Proteção de Dados Sensíveis

aspect:sensitive-data-protection-job-result

Encontrar as entradas de tabelas inspecionadas que têm descobertas

aspect:sensitive-data-protection-job-result.hasFindings=True

Encontrar as entradas de tabelas inspecionadas que não têm descobertas

aspect:sensitive-data-protection-job-result.hasFindings=False

Encontrar as entradas de tabelas que foram totalmente inspecionadas

A consulta a seguir retorna as entradas de tabelas que a Proteção de Dados Sensíveis inspecionou linha por linha.

aspect:sensitive-data-protection-job-result.isFullScan=True

Encontrar as entradas de tabelas que não foram totalmente inspecionadas

A consulta a seguir retorna as entradas de tabelas que a Proteção de Dados Sensíveis inspecionou por amostragem.

aspect:sensitive-data-protection-job-result.isFullScan=False

Migrar para a ação "Publicar no Dataplex Universal Catalog"

Para migrar um gatilho de job configurado para usar a ação descontinuada Publicar no Data Catalog, siga estas etapas:

1. Edite o gatilho de job configurado para publicar resultados de inspeção no Data Catalog. Para informações sobre como abrir e editar um gatilho de job, consulte Atualizar um gatilho de job atual.
2. Na seção Ações, desative a opção Publicar no Data Catalog.
3. Ative a opção Publicar no Dataplex Universal Catalog.
4. Clique em Salvar.