Enviar resultados da inspeção para o Dataplex Universal 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 para o Universal Catalog do Dataplex. Essa ação adiciona automaticamente um aspecto à entrada do Catálogo Universal do Dataplex associada à sua tabela do BigQuery.

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

Esse recurso é útil se você quiser enriquecer seus metadados no Dataplex Universal 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ções (infoTypes) detectados na tabela.

Sobre o Dataplex Universal Catalog

O Dataplex Universal Catalog fornece um inventário unificado de recursos do Google Cloud .

Com o Dataplex Universal Catalog, é possível usar aspectos para adicionar metadados comerciais e técnicos aos seus dados e capturar contexto e conhecimento sobre seus recursos. Em seguida, você pode pesquisar e descobrir dados em toda a organização e ativar a governança de dados nos seus recursos. Para mais informações, consulte Aspectos.

Importante: o Dataplex Universal Catalog, que usa aspectos, não é o mesmo que o Data Catalog, que usa tags. O Data Catalog foi descontinuado. O recurso da Proteção de dados sensíveis que permite enviar resultados de inspeção para o Data Catalog também foi descontinuado.

Como funciona

Para criar automaticamente aspectos do Dataplex Universal 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 Publicar no Dataplex Universal Catalog.

A proteção de dados sensíveis adiciona ou atualiza o aspecto Sensitive Data Protection job result da entrada do Dataplex Universal Catalog associada à tabela do BigQuery. Em seguida, pesquise no Dataplex Universal Catalog todos os dados da sua organização ou projeto com valores de aspecto específicos. Para conferir exemplos de consultas, consulte Exemplos de consultas de pesquisa neste documento.

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

Observação: quando você ativa a ação Publicar no Dataplex Universal Catalog em um gatilho de job atual, a Proteção de Dados Sensíveis aplica essa ação apenas aos novos jobs de inspeção do gatilho de job, não aos jobs de inspeção anteriores.

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 procurou, conforme especificado na configuração de inspeção, e a contagem de descobertas para cada infoType. Um infoType sem descobertas tem uma contagem de 0.

Horário de término

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

Is Full Scan

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

Se o job de inspeção detectou algum dos infoTypes que ele verificou.

Ativar a API Dataplex

A API Dataplex precisa estar ativada em cada projeto que contém dados para os quais você quer adicionar aspectos. Nesta seção, descrevemos 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. Enable the Dataplex API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the 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 receber 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:

• Visualizador de recursos do Cloud (roles/cloudasset.viewer) na organização ou pasta
• Usuário da 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 contê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 necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para ativar a API Dataplex em todos os projetos de uma organização ou pasta:

• Para pesquisar todos os projetos em uma organização ou pasta: cloudasset.assets.searchAllResources na organização ou pasta
• Para ativar a API Dataplex: serviceusage.services.use em cada projeto em que você quer ativar a API Dataplex

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. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

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.

Papéis e permissões para visualizar aspectos

Para conseguir as permissões necessárias para pesquisar aspectos associados à sua 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 contêm as permissões necessárias para pesquisar aspectos associados à sua tabela do BigQuery. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para pesquisar aspectos associados à sua tabela do BigQuery:

• Ver entradas do Dataplex Universal Catalog:
  • dataplex.entries.list
  • dataplex.entries.get
• Ver conjuntos de dados e tabelas do BigQuery:
  • bigquery.datasets.get
  • bigquery.tables.get

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 o Dataplex Universal Catalog, consulte Permissões do IAM do Dataplex Universal 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 console do Google Cloud ou a API DLP.

Console

1. No console Google Cloud , acesse a página Criar job ou gatilho de jobs.

   Acesse Criar job ou gatilho de jobs.

2. Selecione o projeto.
3. Insira os detalhes necessários do job de inspeção e da tabela do BigQuery que você quer inspecionar. Para instruções, consulte Inspecionar uma tabela do BigQuery. Para uma lista completa dos tipos de informações que a Proteção de dados confidenciais pode inspecionar, consulte Referência do detector de infoType.
4. Em Adicionar ações, ative Publicar no Dataplex Universal Catalog.
5. Clique em Criar. O job é executado imediatamente.

REST

O exemplo a seguir envia uma solicitação projects.locations.dlpJobs.create para inspecionar uma tabela do BigQuery e enviar os resultados ao Dataplex Universal Catalog.

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

• PROJECT_ID: o ID do projeto Google Cloud . Os IDs do projeto são strings alfanuméricas
• LOCATION: a região ou multirregião em que você quer processar a solicitação, por exemplo, europe-west1 ou us. Para saber quais locais estão disponíveis, consulte Locais da Proteção de dados sensíveis.
• BIGQUERY_DATASET_NAME: nome do conjunto de dados do BigQuery que contém a tabela a ser inspecionada
• BIGQUERY_TABLE_NAME: nome da tabela do BigQuery a ser inspecionada

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

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

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome inspect-request.json e execute o comando a seguir:

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"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome inspect-request.json e execute o comando a seguir:

$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

Você receberá uma resposta JSON semelhante a esta:

{
  "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 Dataplex Universal Catalog para encontrar dados na sua organização ou projeto com valores de aspecto específicos.

Você só encontra 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.

Você pode inserir essas consultas de exemplo no campo Pesquisar na página Pesquisar do Dataplex Universal Catalog.

Acesse Pesquisar

Para saber como formar as consultas, consulte Sintaxe de pesquisa do Dataplex Universal 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 das 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