Crie tabelas de objetos

Este documento descreve como tornar os dados não estruturados no Cloud Storage acessíveis no BigQuery através da criação de uma tabela de objetos.

Para criar uma tabela de objetos, tem de concluir as seguintes tarefas:

1. Crie um conjunto de dados para conter a tabela de objetos.
2. Crie uma associação para ler informações de objetos do Cloud Storage.
3. Conceda a função Storage Object Viewer (roles/storage.objectViewer) à conta de serviço associada à ligação.
4. Crie a tabela de objetos e associe-a à ligação através da declaração CREATE EXTERNAL TABLE.

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and BigQuery Connection API APIs.

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 APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and BigQuery Connection API APIs.

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 APIs

Funções necessárias

Para criar tabelas de objetos, tem de ter as seguintes funções no projeto:

• Para criar conjuntos de dados e tabelas, tem de ter a função de editor de dados do BigQuery (roles/bigquery.dataEditor).
• Para criar uma associação, tem de ter a função de administrador da associação do BigQuery (roles/bigquery.connectionAdmin).
• Para conceder uma função à conta de serviço da associação, tem de ter a função de administrador de IAM do projeto (roles/resourcemanager.projectIamAdmin).

Para consultar tabelas de objetos, tem de ter as seguintes funções no projeto:

• Função de visualizador de dados do BigQuery (roles/bigquery.dataViewer)
• Função de utilizador de ligação do BigQuery (roles/bigquery.connectionUser)

Para ver as autorizações exatas necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

• bigquery.datasets.create
• bigquery.tables.create
• bigquery.tables.update
• bigquery.connections.create
• bigquery.connections.get
• bigquery.connections.list
• bigquery.connections.update
• bigquery.connections.use
• bigquery.connections.delete
• bigquery.connections.delegate
• storage.bucket.*
• storage.object.*
• bigquery.jobs.create
• bigquery.tables.get
• bigquery.tables.getData
• bigquery.readsessions.create

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Atenção: os utilizadores que se destinam apenas a consultar os dados não devem ter o seguinte:

• A capacidade de ler objetos diretamente a partir do Cloud Storage, concedida pela função Leitor de objetos do Storage.
• A capacidade de associar tabelas a ligações, concedida pela função de administrador de ligações do BigQuery.

Caso contrário, os utilizadores podem criar novas tabelas de objetos que não tenham controlos de acesso, contornando assim os controlos colocados pelos administradores do data warehouse.

Crie um conjunto de dados

Crie um conjunto de dados do BigQuery para conter a tabela de objetos:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No painel esquerdo, clique em Explorador:

   

   Se não vir o painel do lado esquerdo, clique em Expandir painel do lado esquerdo para o abrir.

3. No painel Explorador, clique no nome do projeto.

4. Clique em Ver ações > Criar conjunto de dados.

5. Na página Criar conjunto de dados, faça o seguinte:

   1. Para ID do conjunto de dados, escreva um nome para o conjunto de dados.

   2. Para Tipo de localização, selecione Região ou Várias regiões.

      • Se selecionou Região, selecione uma localização na lista Região.
      • Se selecionou Multirregional, selecione EUA ou Europa na lista Multirregional.

   3. Clique em Criar conjunto de dados.

Crie uma associação

Pode ignorar este passo se tiver uma associação predefinida configurada ou tiver a função de administrador do BigQuery.

Crie uma associação de recursos da nuvem para a tabela de objetos usar e obtenha a conta de serviço da associação.

1. Aceda à página do BigQuery.

   Aceda ao BigQuery

2. No painel esquerdo, clique em Explorador:

   

3. No painel Explorador, clique em Adicionar dados.

   É apresentada a caixa de diálogo Adicionar dados.

4. No painel Filtrar por, na secção Tipo de origem de dados, selecione Aplicações empresariais.

   Em alternativa, no campo Pesquisar origens de dados, pode introduzir Vertex AI.

5. Na secção Origens de dados em destaque, clique em Vertex AI.

6. Clique no cartão da solução Modelos da Vertex AI: federação do BigQuery.

7. Na lista Tipo de ligação, selecione Modelos remotos, funções remotas, BigLake e Spanner (recurso da nuvem) da Vertex AI.

8. No campo ID da associação, introduza um nome para a associação.

9. Para Tipo de localização, selecione Região ou Várias regiões.

   • Se selecionou Região, selecione uma localização na lista Região.
   • Se selecionou Multirregional, selecione EUA ou Europa na lista Multirregional.

10. Clique em Criar associação.

11. Clique em Aceder à associação.

12. No painel Informações de associação, copie o ID da conta de serviço para utilização num passo seguinte.

Conceda acesso à conta de serviço

Conceda à conta de serviço da ligação a função Leitor de objetos de armazenamento:

Consola

1. Aceda à página IAM e administrador.

   Aceda a IAM e administração

2. Clique em Adicionar.

   É apresentada a caixa de diálogo Adicionar responsáveis.

3. No campo Novos membros, introduza o ID da conta de serviço que copiou anteriormente.

4. No campo Selecionar uma função, escolha Cloud Storage e, de seguida, selecione Visualizador de objetos de armazenamento.

5. Clique em Guardar.

gcloud

Use o comando gcloud projects add-iam-policy-binding.

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None

Substitua o seguinte:

• PROJECT_NUMBER: o número do projeto do projeto no qual conceder a função.
• MEMBER: o ID da conta de serviço que copiou anteriormente.

Crie uma tabela de objetos

Para criar uma tabela de objetos:

SQL

Use a declaração CREATE EXTERNAL TABLE.

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, introduza a seguinte declaração:

   CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME`
   WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID`| DEFAULT}
   OPTIONS(
     object_metadata = 'SIMPLE',
     uris = ['BUCKET_PATH'[,...]],
     max_staleness = STALENESS_INTERVAL,
     metadata_cache_mode = 'CACHE_MODE');

   Substitua o seguinte:

   • PROJECT_ID: o ID do projeto.
   • DATASET_ID: o ID do conjunto de dados que contém a tabela de objetos.
   • TABLE_NAME: o nome da tabela de objetos.
   • REGION: a região ou a região múltipla que contém a ligação.
   • CONNECTION_ID: o ID da associação de recursos da nuvem a usar com esta tabela de objetos. A associação determina que conta de serviço é usada para ler dados do Cloud Storage.

     Quando vê os detalhes da associação na consola Google Cloud , o ID da associação é o valor na última secção do ID da associação totalmente qualificado que é apresentado em ID da associação, por exemplo projects/myproject/locations/connection_location/connections/myconnection.

     Para usar uma ligação predefinida, especifique DEFAULT em vez da string de ligação que contém PROJECT_ID.REGION.CONNECTION_ID.

   • BUCKET_PATH: o caminho para o contentor do Cloud Storage que contém os objetos representados pela tabela de objetos, no formato ['gs://bucket_name/[folder_name/]*'].

     Pode usar um caráter universal de asterisco (*) em cada caminho para limitar os objetos incluídos na tabela de objetos. Por exemplo, se o contentor tiver vários tipos de dados não estruturados, pode criar a tabela de objetos apenas sobre objetos PDF especificando ['gs://bucket_name/*.pdf']. Para mais informações, consulte o artigo Suporte de carateres universais para URIs do Cloud Storage.

     Pode especificar vários contentores para a opção uris fornecendo vários caminhos, por exemplo, ['gs://mybucket1/*', 'gs://mybucket2/folder5/*'].

     Para mais informações sobre a utilização de URIs do Cloud Storage no BigQuery, consulte o artigo Caminho do recurso do Cloud Storage.

   • STALENESS_INTERVAL: especifica se as operações na tabela de objetos usam metadados em cache e qual a antiguidade máxima dos metadados em cache para que a operação os use. Para mais informações sobre considerações relativas à colocação em cache de metadados, consulte o artigo Colocação em cache de metadados para desempenho.

     Para desativar a colocação em cache de metadados, especifique 0. Esta é a predefinição.

     Para ativar o armazenamento em cache de metadados, especifique um valor literal de intervalo entre 30 minutos e 7 dias. Por exemplo, especifique INTERVAL 4 HOUR para um intervalo de desatualização de 4 horas. Com este valor, as operações na tabela usam metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem mais antigos, a operação obtém metadados do Cloud Storage.

   • CACHE_MODE: especifica se a cache de metadados é atualizada automaticamente ou manualmente. Para mais informações sobre considerações de colocação em cache de metadados, consulte Colocação em cache de metadados para desempenho.

     Definido como AUTOMATIC para que a cache de metadados seja atualizada a um intervalo definido pelo sistema, normalmente entre 30 e 60 minutos.

     Defina como MANUAL se quiser atualizar a cache de metadados de acordo com uma programação que determinar. Neste caso, pode chamar o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar a cache.

     Tem de definir CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor superior a 0.

3. Clique em Executar.

Para mais informações sobre como executar consultas, consulte o artigo Execute uma consulta interativa.

Exemplos

O exemplo seguinte cria uma tabela de objetos com um intervalo de desatualização da cache de metadados de 1 dia:

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://mybucket/*'],
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

O exemplo seguinte cria uma tabela de objetos sobre os objetos em três contentores do Cloud Storage:

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket1/*','gs://bucket2/folder1/*','gs://bucket3/*']
);

O exemplo seguinte cria uma tabela de objetos apenas com os objetos PDF num contentor do Cloud Storage:

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket1/*.pdf']
);

bq

Use o comando bq mk.

bq mk --table \
--external_table_definition=[e-mail]_ID \
--object_metadata=SIMPLE \
--max_staleness=STALENESS_INTERVAL \
--metadata_cache_mode=CACHE_MODE \
PROJECT_ID:DATASET_ID.TABLE_NAME

Substitua o seguinte:

• PROJECT_ID: o ID do projeto.
• DATASET_ID: o ID do conjunto de dados que contém a tabela de objetos.
• TABLE_NAME: o nome da tabela de objetos.
• REGION: a região ou a região múltipla que contém a ligação.
• CONNECTION_ID: o ID da ligação de recursos da nuvem a usar com esta tabela externa. A associação determina que conta de serviço é usada para ler dados do Cloud Storage.

  Quando vê os detalhes da ligação na Google Cloud consola, o ID da ligação é o valor na última secção do ID da ligação totalmente qualificado que é apresentado em ID da ligação, por exemplo projects/myproject/locations/connection_location/connections/myconnection.

• BUCKET_PATH: o caminho para o contentor do Cloud Storage que contém os objetos representados pela tabela de objetos, no formato gs://bucket_name/[folder_name/]*.

  Pode usar um caráter universal de asterisco (*) em cada caminho para limitar os objetos incluídos na tabela de objetos. Por exemplo, se o contentor tiver vários tipos de dados não estruturados, pode criar a tabela de objetos apenas sobre objetos PDF especificando gs://bucket_name/*.pdf. Para mais informações, consulte o artigo Suporte de carateres universais para URIs do Cloud Storage.

  Pode especificar vários contentores para a opção uris fornecendo vários caminhos, por exemplo, gs://mybucket1/*,gs://mybucket2/folder5/*.

  Para mais informações sobre a utilização de URIs do Cloud Storage no BigQuery, consulte o artigo Caminho de recurso do Cloud Storage.

• STALENESS_INTERVAL: especifica se as operações na tabela de objetos usam metadados em cache e qual a antiguidade máxima dos metadados em cache para que a operação os use. Para mais informações sobre considerações relativas à colocação em cache de metadados, consulte o artigo Colocação em cache de metadados para desempenho.

  Para desativar a colocação em cache de metadados, especifique 0. Esta é a predefinição.

  Para ativar o armazenamento em cache de metadados, especifique um valor de intervalo entre 30 minutos e 7 dias, usando o formato Y-M D H:M:S descrito na documentação do INTERVAL tipo de dados. Por exemplo, especifique 0-0 0 4:0:0 para um intervalo de desatualização de 4 horas. Com este valor, as operações na tabela usam metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem mais antigos, a operação obtém metadados do Cloud Storage.

• CACHE_MODE: especifica se a cache de metadados é atualizada automaticamente ou manualmente. Para mais informações sobre considerações de colocação em cache de metadados, consulte Colocação em cache de metadados para desempenho.

  Definido como AUTOMATIC para que a cache de metadados seja atualizada a um intervalo definido pelo sistema, normalmente entre 30 e 60 minutos.

  Defina como MANUAL se quiser atualizar a cache de metadados de acordo com uma programação que determinar. Neste caso, pode chamar o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar a cache.

  Tem de definir CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor superior a 0.

Exemplos

O exemplo seguinte cria uma tabela de objetos com um intervalo de desatualização da cache de metadados de 1 dia:

bq mk --table \
--external_table_definition=gs://mybucket/*@us.my-connection \
--object_metadata=SIMPLE \
--max_staleness=0-0 1 0:0:0 \
--metadata_cache_mode=AUTOMATIC \
my_dataset.object_table

O exemplo seguinte cria uma tabela de objetos sobre os objetos em três contentores do Cloud Storage:

bq mk --table \
--external_table_definition=gs://bucket1/*,gs://bucket2/folder1/*,gs://bucket3/*@us.my-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

O exemplo seguinte cria uma tabela de objetos apenas com os objetos PDF num contentor do Cloud Storage:

bq mk --table \
--external_table_definition=gs://bucket1/*[e-mail]-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

API

Chame o método tables.insert. Inclua um objeto ExternalDataConfiguration com o campo objectMetadata definido como SIMPLE no recurso Table que transmite.

O exemplo seguinte mostra como chamar este método através de curl:

ACCESS_TOKEN=$(gcloud auth print-access-token) curl \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST \
-d '{"tableReference": {"projectId": "my_project", "datasetId": "my_dataset", "tableId": "object_table_name"}, "externalDataConfiguration": {"objectMetadata": "SIMPLE", "sourceUris": ["gs://mybucket/*"]}}' \
https://www.googleapis.com/bigquery/v2/projects/my_project/datasets/my_dataset/tables

Terraform

Este exemplo cria uma tabela de objetos com a colocação em cache de metadados ativada com atualização manual.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Os campos de chave a especificar para uma tabela de objetos são google_bigquery_table.external_data_configuration.object_metadata, google_bigquery_table.external_data_configuration.metadata_cache_mode, e google_bigquery_table.max_staleness. Para mais informações sobre cada recurso, consulte a documentação do Terraform BigQuery.

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a connection in the US region named "my-connection-id".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection-id"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.default.project_id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This defines a Google BigQuery dataset.
resource "google_bigquery_dataset" "default" {
  dataset_id = "my_dataset_id"
}

# This creates a bucket in the US region named "my-bucket" with a pseudorandom suffix.
resource "random_id" "bucket_name_suffix" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.bucket_name_suffix.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

# This defines a BigQuery object table with manual metadata caching.
resource "google_bigquery_table" "default" {
  deletion_protection = false
  table_id            = "my-table-id"
  dataset_id          = google_bigquery_dataset.default.dataset_id
  external_data_configuration {
    connection_id = google_bigquery_connection.default.name
    autodetect    = false
    # `object_metadata is` required for object tables. For more information, see
    # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/bigquery_table#object_metadata
    object_metadata = "SIMPLE"
    # This defines the source for the prior object table.
    source_uris = [
      "gs://${google_storage_bucket.default.name}/*",
    ]

    metadata_cache_mode = "MANUAL"
  }

  # This ensures that the connection can access the bucket
  # before Terraform creates a table.
  depends_on = [
    google_project_iam_member.default
  ]
}

Para aplicar a configuração do Terraform num Google Cloud projeto, conclua os passos nas secções seguintes.

Prepare o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o Google Cloud projeto predefinido onde quer aplicar as suas configurações do Terraform.

   Só tem de executar este comando uma vez por projeto e pode executá-lo em qualquer diretório.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   As variáveis de ambiente são substituídas se definir valores explícitos no ficheiro de configuração do Terraform.

Prepare o diretório

Cada ficheiro de configuração do Terraform tem de ter o seu próprio diretório (também denominado módulo raiz).

1. No Cloud Shell, crie um diretório e um novo ficheiro nesse diretório. O nome do ficheiro tem de ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o ficheiro é denominado main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se estiver a seguir um tutorial, pode copiar o código de exemplo em cada secção ou passo.

   Copie o exemplo de código para o main.tf criado recentemente.

   Opcionalmente, copie o código do GitHub. Isto é recomendado quando o fragmento do Terraform faz parte de uma solução completa.

3. Reveja e modifique os parâmetros de exemplo para aplicar ao seu ambiente.
4. Guarde as alterações.
5. Inicialize o Terraform. Só tem de fazer isto uma vez por diretório.

   terraform init

   Opcionalmente, para usar a versão mais recente do fornecedor Google, inclua a opção -upgrade:

   terraform init -upgrade

Aplique as alterações

1. Reveja a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expetativas:

   terraform plan

   Faça correções à configuração conforme necessário.

2. Aplique a configuração do Terraform executando o seguinte comando e introduzindo yes no comando:

   terraform apply

   Aguarde até que o Terraform apresente a mensagem "Apply complete!" (Aplicação concluída!).

3. Abra o seu Google Cloud projeto para ver os resultados. Na Google Cloud consola, navegue para os seus recursos na IU para se certificar de que o Terraform os criou ou atualizou.

Nota: normalmente, os exemplos do Terraform partem do princípio de que as APIs necessárias estão ativadas no seu Google Cloud projeto.

Consultar tabelas de objetos

Pode consultar uma tabela de objetos como qualquer outra tabela do BigQuery, por exemplo:

SELECT *
FROM mydataset.myobjecttable;

A consulta de uma tabela de objetos devolve metadados para os objetos subjacentes. Para mais informações, consulte o esquema da tabela de objetos.

O que se segue?

• Saiba como executar a inferência em tabelas de objetos de imagens.
• Saiba como analisar tabelas de objetos através de funções remotas.