Usar a verificação de descoberta para dados não estruturados

As verificações de perfil de dados para dados não estruturados usam modelos do Gemini 2.5 Pro da Vertex AI durante uma verificação de descoberta do Cloud Storage para transformar arquivos brutos e não estruturados no Cloud Storage (como PDFs) em recursos estruturados e consultáveis no BigQuery. Esse fluxo de trabalho automatizado foi projetado para usuários que começam com arquivos brutos no Cloud Storage. Se você já tiver tabelas de objetos do BigQuery ou quiser orientar a extração usando um comando personalizado, consulte Usar o perfil de dados para dados não estruturados.

Este documento descreve como configurar as permissões necessárias, preparar seus arquivos não estruturados, criar uma verificação de descoberta do Cloud Storage com inferência semântica ativada usando a API REST, visualizar os insights gerados, organizar perfis de gráficos e extrair os dados para o BigQuery.

Antes de começar

Antes de criar uma verificação de descoberta, verifique se você tem as permissões necessárias e as APIs ativadas.

Ativar APIs

Ativar as APIs a seguir no projeto:

  • dataplex.googleapis.com
  • bigquery.googleapis.com
  • aiplatform.googleapis.com (Vertex AI)

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 as APIs

Papéis e permissões necessárias

Para configurar e executar verificações de perfil de dados em dados não estruturados, você precisa atender às permissões básicas de uma verificação de descoberta e conceder outros papéis para inferência semântica em vários agentes de serviço.

Papéis de verificação de descobertas de valor de referência

Verifique se você e as contas de serviço usadas pelo Knowledge Catalog têm as permissões básicas necessárias para uma verificação de descoberta padrão. Para uma lista completa, consulte Descobrir e catalogar dados do Cloud Storage.

Outros papéis para inferência semântica

Além dos papéis básicos de descoberta, verifique se você e as contas de serviço têm os seguintes papéis adicionais do Identity and Access Management (IAM).

Resumo de outras identidades e papéis

Tipo de identidade Formato principal típico Papéis necessários do IAM Propósito principal
Usuário final Sua conta de usuário do Google Cloud
  • Editor do DataScan Dataplex
  • Editor de catálogo do Dataplex
  • Editor de dados do BigQuery
  • Usuário de jobs do BigQuery
 Você usa essas funções adicionais para configurar verificações, ver resultados gerados por IA, organizar perfis de gráficos e acionar a extração final de dados.
Agente de descoberta do Dataplex Universal Catalog service-<var>PROJECT_NUMBER</var>@gcp-sa-dataplex.iam.gserviceaccount.com
  • Usuário da Agent Platform
  • Usuário de jobs do BigQuery
  • Leitor de dados do BigQuery
 Esse agente de serviço gerenciado pelo Google usa essas funções adicionais para chamar a Vertex AI e gerar esquemas e metadados inferidos.
Conta de serviço de conexão do BigQuery Uma identidade exclusiva associada à sua conexão (por exemplo, bqcx-<var>PROJECT_NUMBER</var>-<var>ID</var>@gcp-sa-bigquery-condel.iam.gserviceaccount.com)
  • Leitor de objetos do Storage (no bucket de origem)
  • Usuário da Agent Platform (no projeto)
 Ele conecta o BigQuery ao armazenamento externo, permitindo que o BigQuery leia os arquivos brutos, crie tabelas de objetos e execute inferências de IA sem expor suas credenciais de usuário pessoais.
Conta de serviço de execução de pipeline (opcional) Uma conta serviço gerenciado pelo usuário
  • Editor de dados do BigQuery
  • Usuário de jobs do BigQuery
  • Usuário do BigQuery
  • Usuário da Agent Platform
 Se você optar por extrair dados usando um pipeline automatizado, essa identidade vai executar os jobs em segundo plano para materializar as entidades geradas por IA em tabelas do BigQuery.
Conta de serviço padrão do Dataform (opcional) service-<var>PROJECT_NUMBER</var>@gcp-sa-dataform.iam.gserviceaccount.com
  • Criador de token da conta de serviço (concedido na conta de serviço de execução do pipeline)
 Ao usar o método de extração de pipeline, o Dataform precisa de permissão para personificar sua conta de serviço de execução de pipeline e orquestrar o fluxo de trabalho.

Permissões e funções do usuário final

Para garantir que sua conta de usuário tenha as permissões necessárias para criar verificações, ver insights, organizar perfis de gráficos e extrair dados, peça ao administrador para conceder os seguintes papéis do IAM à sua conta de usuário no projeto:

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 criar verificações, ver insights, organizar perfis de gráficos e extrair dados. 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 criar verificações, ver insights, selecionar perfis de gráfico e extrair dados:

  • DataScans:
    • dataplex.datascans.create
    • dataplex.datascans.get
    • dataplex.datascans.getData
    • dataplex.datascans.list
    • dataplex.datascans.update
  • Extração de dados:
    • bigquery.tables.create
    • bigquery.tables.update
    • bigquery.tables.getData
    • bigquery.jobs.create

O administrador também pode conceder à conta de serviço essas permissões com papéis personalizados ou outros papéis predefinidos.

Permissões e papéis do agente de serviço do Dataplex Discovery

O agente de serviço de descoberta do Dataplex é um agente de serviço que precisa de acesso para executar verificações e fazer inferências semânticas usando a Vertex AI.

Para garantir que o agente de serviço de descoberta do Dataplex (geralmente service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com) tenha as permissões necessárias para executar verificações e fazer inferência semântica usando a Vertex AI, peça ao administrador para conceder os seguintes papéis do IAM ao agente de serviço de descoberta do Dataplex (geralmente service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com) no projeto:

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 executar verificações e fazer inferência semântica usando a Vertex AI. 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 executar verificações e fazer inferência semântica usando a Vertex AI:

  • Todos:
    • aiplatform.endpoints.predict
    • bigquery.datasets.create
    • bigquery.datasets.get
    • bigquery.tables.get
    • bigquery.tables.getData
    • storage.buckets.get
    • storage.objects.get
    • storage.objects.list

O administrador também pode conceder ao agente de serviço de descoberta do Dataplex (geralmente service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com) essas permissões com papéis personalizados ou outros papéis predefinidos.

Permissões e papéis da conta de serviço de conexão do BigQuery

Com uma conexão de recurso do BigQuery Cloud, o Knowledge Catalog pode acessar dados não estruturados armazenados no Cloud Storage. Quando você cria uma conexão, o BigQuery cria automaticamente uma conta de serviço dedicada em seu nome. Essa conta de serviço serve como a identidade usada para se conectar à sua fonte de dados externa.

Por padrão, essa conta de serviço não tem permissões. Você precisa conceder explicitamente a essa conta de serviço os papéis do IAM necessários nos buckets do Cloud Storage que contêm seus dados. É possível usar uma conexão do BigQuery ou criar uma no mesmo local do bucket de origem do Cloud Storage. Para mais informações sobre como compartilhar conexões, consulte Compartilhar uma conexão com usuários.

Para garantir que a conta de serviço de conexão do BigQuery (recupere o ID na seção Informações de conexão dos detalhes da conexão) tenha as permissões necessárias para ler tabelas de objetos e executar inferências, peça ao administrador para conceder os seguintes papéis do IAM à conta de serviço de conexão do BigQuery (recupere o ID na seção Informações de conexão dos detalhes da conexão):

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 ler tabelas de objetos e executar inferências. 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 ler tabelas de objetos e executar inferências:

  • Todos:
    • storage.buckets.get no bucket que contém dados não estruturados
    • storage.objects.get no bucket que contém dados não estruturados
    • aiplatform.endpoints.predict no projeto

O administrador também pode conceder essas permissões à conta de serviço de conexão do BigQuery (recupere o ID na seção Informações de conexão dos detalhes da conexão) com papéis personalizados ou outros papéis predefinidos.

Papéis e permissões da conta de serviço de execução do pipeline (opcional)

Se você optar por extrair os dados inferidos usando um pipeline automatizado, crie ou forneça uma conta de serviço dedicada para executar o pipeline. Essa conta de serviço de execução atua como a identidade que autentica e executa as tarefas de extração e análise de dados em segundo plano no BigQuery. Além disso, é necessário conceder à conta de serviço padrão do Dataform permissão para personificar essa conta de serviço de execução.

Para garantir que a conta de serviço de execução do pipeline tenha as permissões necessárias para extrair as entidades e relações inferidas usando um pipeline, peça ao administrador para conceder os seguintes papéis do IAM à conta de serviço de execução do pipeline no projeto:

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 extrair as entidades e os relacionamentos inferidos usando um pipeline. 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 extrair as entidades e relações inferidas usando um pipeline:

  • Todos:
    • bigquery.tables.create
    • bigquery.tables.update
    • bigquery.tables.get
    • bigquery.tables.getData
    • bigquery.jobs.create
    • aiplatform.endpoints.predict

O administrador também pode conceder essas permissões à conta de serviço de execução de pipeline com papéis personalizados ou outros papéis predefinidos.

Para garantir que a conta de serviço padrão do Dataform (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com) tenha as permissões necessárias para representar a conta de serviço de execução do pipeline, peça ao administrador para conceder os seguintes papéis do IAM à conta de serviço padrão do Dataform (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com) na conta de serviço de execução do pipeline:

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 representar a conta de serviço de execução do pipeline. 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 representar a conta de serviço de execução do pipeline:

  • Todos: iam.serviceAccounts.getAccessToken

O administrador também pode conceder à conta de serviço padrão do Dataform (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com) essas permissões com papéis personalizados ou outros papéis predefinidos.

Preparar dados não estruturados

Antes de executar uma verificação de descoberta, faça upload dos dados não estruturados para um bucket do Cloud Storage. As verificações de perfil de dados para dados não estruturados são otimizadas para analisar documentos PDF.

Para mais informações sobre como armazenar e gerenciar arquivos no Cloud Storage, consulte Fazer upload de objetos.

Criar uma conexão de recursos do Cloud

Para publicar os resultados da verificação de descoberta como uma tabela de objetos do BigQuery, crie uma conexão de recursos do Cloud e conceda à conta de serviço dela acesso aos dados não estruturados no Cloud Storage.

  1. Crie uma conexão de recursos do Cloud.
  2. Conceda o papel de Leitor de objetos do Storage (roles/storage.objectViewer) à conta de serviço associada à conexão no bucket do Cloud Storage que contém seus dados não estruturados. Para mais informações, consulte Conceder acesso à conta de serviço.

Criar uma verificação de descoberta para dados não estruturados

Para extrair insights semânticos dos seus dados não estruturados, primeiro crie uma verificação de descoberta do Cloud Storage. Essa verificação localiza automaticamente seus arquivos não estruturados no Cloud Storage e os cataloga em uma tabela de objetos. Ao ativar a inferência semântica durante esse processo, o Knowledge Catalog usa os modelos Gemini 2.5 Pro da Vertex AI para analisar os arquivos e gerar metadados, esquemas e relações inferidos.

É possível criar uma verificação de descoberta do Cloud Storage com inferência semântica ativada usando o console Google Cloud ou a API REST.

Console

  1. No Google Cloud console, acesse a página Criação de metadados.

    Acessar "Curadoria de metadados"

  2. Na guia Descoberta do Cloud Storage, clique em Criar.

  3. Digite um nome para a verificação.

  4. Para selecionar o bucket do Cloud Storage que contém seus dados não estruturados, clique em Procurar.

  5. Em Opções de dados não estruturados, marque a caixa de seleção Ativar inferência semântica.

  6. No campo ID da conexão, especifique a conexão do BigQuery usada para acessar os arquivos.

    A verificação de descoberta cataloga automaticamente dados não estruturados no BigQuery criando tabelas de objetos. Como as tabelas de objetos desacoplam com segurança as credenciais de acesso aos dados do usuário que executa consultas, é necessária uma conexão para autenticar com o Cloud Storage e ler os arquivos.

  7. Clique em Executar agora (para uma verificação sob demanda) ou Criar (para uma verificação programada).

    Para detalhes sobre todas as configurações disponíveis, consulte Descobrir e catalogar dados do Cloud Storage.

O Knowledge Catalog cria uma tabela de objetos e enriquece a entrada do catálogo com metadados gerados por IA. Esse processo geralmente leva alguns minutos para conjuntos de dados padrão.

REST

Para criar uma verificação de descoberta do Cloud Storage com inferência semântica ativada usando a API REST, use o método dataScans.create com um dataDiscoverySpec.

POST https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans?dataScanId=DATASCAN
{
"description": "Cloud Storage discovery scan with semantic inference",
"data": {
"resource": "//storage.googleapis.com/BUCKET_NAME"
},
"executionSpec": {
"trigger": {
  "onDemand": {}
}
},
"dataDiscoverySpec": {
"bigqueryPublishingConfig": {
  "tableType": "OBJECT_TABLE",
  "connection": "projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID"
},
"unstructuredDataEventsConfig": {
  "enabled": true
}
}
}

Substitua:

  • PROJECT_ID: o ID do seu Google Cloud projeto.
  • LOCATION: a região Google Cloud (precisa ser compatível com o Gemini 2.5 Pro).
  • DATASCAN: o nome da verificação de descoberta.
  • BUCKET_NAME: o bucket do Cloud Storage que contém dados não estruturados.
  • CONNECTION_ID: o ID da conexão do BigQuery.

Executar a verificação de descoberta

Se você configurou a verificação de descoberta para ser executada sob demanda, é necessário acionar manualmente a verificação para localizar os dados não estruturados e gerar insights.

É possível acionar uma verificação de descoberta usando o console do Google Cloud ou a API REST.

Console

  1. No console do Google Cloud , acesse a página BigQuery.

    Acessar o BigQuery

  2. No menu de navegação, clique em Governança > Curadoria de metadados.

  3. No painel Descoberta do Cloud Storage, clique na verificação de descoberta que você quer executar.

  4. Clique em Executar agora.

REST

Para executar uma verificação de descoberta sob demanda usando a API REST, use o método dataScans.run:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans/DATASCAN:run"

Substitua as seguintes variáveis:

  • PROJECT_ID: o ID do seu Google Cloud projeto.
  • LOCATION: a Google Cloud região em que a verificação de descoberta está localizada.
  • DATASCAN: o nome da verificação de descoberta.

O Knowledge Catalog executa a verificação de descoberta, cria uma tabela de objetos e enriquece a entrada do catálogo com metadados gerados por IA. Esse processo geralmente leva alguns minutos para conjuntos de dados padrão.

Localizar a tabela de objetos

Depois que a verificação de descoberta é concluída, o Knowledge Catalog cria uma ou várias tabelas de objetos e preenche o Knowledge Catalog com uma entrada correspondente enriquecida com metadados gerados por IA. Quando várias entradas são criadas devido a uma verificação de descoberta, cada uma delas tem uma guia "Insights" própria. É possível conferir a descrição automática da tabela, os esquemas inferidos e os gráficos de relacionamento.

  1. No console do Google Cloud , acesse a página BigQuery.

    Acessar o BigQuery

  2. No menu de navegação, clique em Governança > Curadoria de metadados.

  3. No painel Descoberta do Cloud Storage, clique na verificação de descoberta que você executou para dados não estruturados.

    • A seção Detalhes da verificação mostra detalhes sobre a verificação de descoberta.
    • A seção Status da verificação mostra os resultados da descoberta do job de verificação mais recente.

  4. Clique no link Conjunto de dados publicado.

  5. Na lista de tabelas exibidas para o conjunto de dados do BigQuery, selecione a tabela de objetos gerada para a verificação de dados de descoberta.

  6. Copie o ID da tabela. Você vai precisar dele na próxima seção.

Analisar os resultados da verificação de descoberta

É possível conferir a tabela de objetos e os gráficos semânticos inferidos no Catálogo de dados.

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

    Acesse Pesquisar

  2. Cole e pesquise a tabela de objetos cujo ID você selecionou na seção anterior.

  3. Nos resultados da pesquisa, clique na tabela para abrir a página de entrada dela.

  4. Na guia Detalhes, em Aspectos, verifique a presença do aspecto Perfil de gráfico (dataplex-types.global.graph-profile). Esse aspecto contém os esquemas inferidos para entidades e relacionamentos.

  5. Clique na guia Insights. Na guia Insights, você pode conferir as seguintes informações:

    • Extração semântica. Um banner indica que entidades e relações extraíveis foram detectadas. Ele inclui um botão Extrair para materializar os dados usando SQL ou implantação de pipeline.

    • Descrição: Um resumo legível gerado por IA explica o conteúdo dos dados não estruturados. Ele descreve os nós principais (entidades) descobertos e como eles se mapeiam uns aos outros por arestas (relacionamentos).

    • Pipelines. Uma lista de pipelines de extração de dados implantados anteriormente associados a esse recurso. É possível conferir o nome de exibição, a região, a hora de criação e o usuário que criou o pipeline.

    • Entidades e relações inferidas. Um gráfico visual e interativo mostra a estrutura semântica descoberta dos seus dados não estruturados. O gráfico contém nós que representam entidades distintas, por exemplo, Recipe e Ingredient, e arestas que representam as conexões entre elas, por exemplo, HasAllergenStatus. Use a legenda para filtrar e analisar nós e arestas específicos.

    • Entidades. Uma lista detalhada das entidades principais descobertas. É possível abrir cada entidade para conferir a descrição gerada por IA e o esquema inferido, que inclui nomes de campos, tipos de dados e descrições de campos.

    • Relacionamentos. Uma lista detalhada das conexões descobertas entre entidades. É possível expandir cada relação para conferir a descrição e o esquema que define como as entidades se mapeiam.

Atualizar insights inferidos

Os insights inferidos são armazenados no catálogo do Knowledge Catalog como um aspecto anexado à tabela de objetos. É possível atualizar esses insights manualmente usando a API REST.

REST

Para atualizar insights inferidos usando a API REST, siga estas etapas:

  1. Crie um arquivo chamado payload.json e adicione o conteúdo JSON do aspecto que você quer atualizar. Exemplo:

    {
  "aspects": {
    "dataplex-types.global.graph-profile": {
      "data": {
        "nodeTypes": [],
        "edgeTypes": []
      }
    }
  }
}

  2. Execute o comando a seguir no terminal.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d @payload.json \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/ENTRY_ID?updateMask=aspects"

    Substitua:

    • PROJECT_ID: o ID do seu projeto. Por exemplo, example-project.
    • LOCATION: o local da entrada. Por exemplo, us-central1.
    • ENTRY_GROUP_ID: o ID do grupo de entradas, por exemplo, example-entry-group. Para tabelas de objetos do BigQuery, use @bigquery.
    • ENTRY_ID: o ID da entrada. Por exemplo, example-entry. Recupere esse ID na guia Visão geral da página de detalhes da entrada no console do Google Cloud .

Para mais informações e exemplos de código em outros idiomas, consulte Atualizar um aspecto de entrada.

Extrair dados para o BigQuery

É possível materializar as entidades e relações inferidas em tabelas ou visualizações estruturadas no BigQuery usando SQL ou um pipeline automatizado.

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

    Acesse Pesquisar

  2. Pesquise a tabela de objetos gerada pela sua verificação.

  3. Nos resultados da pesquisa, clique na tabela para abrir a página de entrada dela.

  4. Clique na guia Insights.

  5. Na guia Insights, clique em Extração.

  6. Escolha um dos seguintes métodos com base nas suas necessidades analíticas e na escala dos dados não estruturados:

    • Extração por SQL:escolha essa opção para análises rápidas e ad hoc, conjuntos de dados pequenos a médios ou quando quiser uma abordagem sem infraestrutura usando modelos remotos do BigQuery.

      Para extrair usando SQL, siga estas etapas:

      1. Selecione Extrair por SQL.
      2. No painel Extrair com SQL, selecione um conjunto de dados de destino. O conjunto de dados precisa estar no mesmo local que a origem.
      3. Clique em Extrair.
      4. No editor do BigQuery, uma consulta pré-preenchida é aberta usando a função ML.PROCESS_DOCUMENT. Execute a consulta para criar tabelas e visualizações padrão.

      Para mais informações sobre como usar o SQL para extrair insights de documentos, consulte Processar documentos com a função ML.PROCESS_DOCUMENT.

    • Extração por pipeline:escolha essa opção para processamento de dados em grande escala ou quando precisar de uma lógica de novas tentativas, tratamento de erros e orquestração automatizada robustos para lidar com grandes volumes de documentos.

      Para extrair usando um pipeline, siga estas etapas:

      1. Selecione Extrair por pipeline.
      2. No painel Extrair com pipeline, insira um nome de exibição para o pipeline.
      3. Selecione uma região.
      4. Selecione um conjunto de dados de destino. O conjunto de dados precisa estar no mesmo local que a origem.
      5. Clique em Extrair. Isso cria um pipeline do BigQuery que orquestra a materialização de dados usando o Dataform.
      6. Execute todas as tarefas no pipeline para gerar visualizações estruturadas de nós e arestas.

      Para mais informações sobre a execução de fluxos de trabalho de dados, consulte Introdução ao Dataform.

Depois de extrair e materializar os insights semânticos no BigQuery, você pode realizar as seguintes tarefas:

  • Consultar os dados estruturados. Execute consultas SQL padrão nas tabelas recém-criadas para analisar as entidades e relações extraídas.

  • Fazer junção com dados atuais. Combine os insights qualitativos extraídos dos seus arquivos não estruturados com os conjuntos de dados estruturados do BigQuery (como a junção de dados de faturas analisados com suas tabelas de contabilidade).

  • Analise insights de dados. Use o recurso Insights de dados no BigQuery Studio para gerar automaticamente perguntas em linguagem natural e consultas SQL para seus novos recursos estruturados.

  • Analisar com o Gemini. Use o Gemini no BigQuery para fazer análises conversacionais, resumir tendências ou criar painéis no Data Studio com base nos dados extraídos.

A seguir