Creare tabelle di oggetti

Questo documento descrive come accedere ai dati non strutturati in BigQuery creando una tabella degli oggetti.

Per creare una tabella di oggetti, devi completare le seguenti attività:

1. Crea una connessione per leggere l'oggetto da Cloud Storage.
2. Concedi l'autorizzazione a leggere le informazioni di Cloud Storage all'account di servizio associato alla connessione.
3. Crea la tabella degli oggetti e associala alla connessione utilizzando il metodo CREATE EXTERNAL TABLE.

Prima di iniziare

1. 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.

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

   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

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the BigQuery and BigQuery Connection API APIs.

   Enable the APIs

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

   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

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the BigQuery and BigQuery Connection API APIs.

   Enable the APIs

8. Assicurati che l'amministratore BigQuery abbia creato una connessione e imposta a Cloud Storage.

Ruoli obbligatori

Per lavorare con le tabelle di oggetti, gli utenti devono: Autorizzazioni IAM in base al loro ruolo nell'organizzazione. Per ulteriori informazioni sui ruoli utente, consulta Modello di sicurezza. Per ulteriori informazioni su come concedere autorizzazioni, consulta Visualizzazione dei ruoli assegnabili nelle risorse.

• Amministratore dei data lake

  Per ottenere le autorizzazioni a cui devi connetterti Cloud Storage, chiedi all'amministratore di concederti l'autorizzazione di amministratore della connessione BigQuery (roles/bigquery.connectionAdmin) per il progetto.

  Per ottenere le autorizzazioni necessarie per creare e gestire i bucket Cloud Storage, chiedi all'amministratore di concederti il ruolo Amministratore archiviazione (roles/storage.admin) nel progetto.

  Questo ruolo predefinito contiene le autorizzazioni necessarie per connettersi a Cloud Storage e creare e gestire i bucket Cloud Storage. Per visualizzare le autorizzazioni esatte richieste, espandi la sezione Autorizzazioni obbligatorie:

  Autorizzazioni obbligatorie

  • bigquery.connections.create
  • bigquery.connections.get
  • bigquery.connections.list
  • bigquery.connections.update
  • bigquery.connections.use
  • bigquery.connections.delete
  • storage.bucket.*
  • storage.object.*

• Amministratore data warehouse

  Per ottenere le autorizzazioni necessarie per creare l'oggetto tabelle, chiedi all'amministratore di concedere i seguenti ruoli nel progetto:

  • Ruolo Editor dati BigQuery (roles/bigquery.dataEditor).
  • Ruolo Amministratore connessione BigQuery (roles/bigquery.connectionAdmin).

  Questo ruolo predefinito contiene le autorizzazioni necessarie per creare tabelle di oggetti. Per vedere le autorizzazioni esatte richieste, espandi la sezione Obbligatorio Autorizzazioni:

  Autorizzazioni obbligatorie

  • bigquery.tables.create
  • bigquery.tables.update
  • bigquery.connections.delegate

• Analista di dati

  Per ottenere le autorizzazioni necessarie per eseguire query sulle tabelle di oggetti, chiedi all'amministratore di concederti i seguenti ruoli nel progetto:

  • Ruolo Visualizzatore dati BigQuery (roles/bigquery.dataViewer)
  • Ruolo Utente connessione BigQuery (roles/bigquery.connectionUser)

  Questo ruolo predefinito contiene le autorizzazioni necessarie per eseguire query sull'oggetto tabelle. Per vedere le autorizzazioni esatte richieste, espandi la sezione Obbligatorio Autorizzazioni:

  Autorizzazioni obbligatorie

  • bigquery.jobs.create
  • bigquery.tables.get
  • bigquery.tables.getData
  • bigquery.readsessions.create

  Potresti anche riuscire a ottenere queste autorizzazioni con i ruoli personalizzati. o altri ruoli predefiniti.

Attenzione: gli analisti di dati non devono avere seguenti:

• La possibilità di leggere gli oggetti direttamente da Cloud Storage (vedi il ruolo IAM Visualizzatore oggetti Storage), che consente agli analisti dei dati di aggirare i controlli di accesso impostati dagli amministratori del data warehouse.

• La possibilità di associare le tabelle alle connessioni (ad esempio l'amministratore delle connessioni BigQuery).

  In caso contrario, gli analisti dei dati possono creare nuove tabelle di oggetti che non hanno controlli di accesso, aggirando così i controlli impostati dagli amministratori del data warehouse.

Crea tabelle di oggetti

Prima di creare una tabella di oggetti, devi avere un set di dati esistente per contenerla. Per ulteriori informazioni, consulta Creare set di dati.

Per creare una tabella di oggetti:

SQL

Utilizza l'istruzione CREATE EXTERNAL TABLE.

1. Nella console Google Cloud, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nell'editor di query, inserisci la seguente istruzione:

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

   Sostituisci quanto segue:

   • PROJECT_ID: il tuo ID progetto.
   • DATASET_ID: l'ID del set di dati da che contiene la tabella dell'oggetto.
   • TABLE_NAME: il nome della tabella degli oggetti.
   • REGION: la regione o la multiregione che contiene la connessione.
   • CONNECTION_ID: l'ID della connessione alla risorsa cloud da utilizzare con questa tabella di oggetti. La connessione determina quale account di servizio viene utilizzato per leggere i dati da Cloud Storage.

     Quando visualizzi i dettagli della connessione nella console Google Cloud, l'ID connessione è il valore nell'ultima dell'ID connessione completo visualizzato in Connection ID (ID connessione), ad esempio projects/myproject/locations/connection_location/connections/myconnection.

   • BUCKET_PATH: il percorso Bucket Cloud Storage che contiene gli oggetti rappresentati della tabella degli oggetti, nel formato ['gs://bucket_name/[folder_name/]*'].

     Puoi utilizzare un carattere jolly (*) in ogni percorso per limitare gli oggetti inclusi nella tabella degli oggetti. Ad esempio, se il bucket contiene vari tipi di dati non strutturati, Puoi creare la tabella degli oggetti solo su oggetti PDF specificando ['gs://bucket_name/*.pdf']. Per ulteriori informazioni, consulta Supporto dei caratteri jolly per gli URI di Cloud Storage.

     Puoi specificare più bucket per l'opzione uris fornendo più percorsi, ad esempio ['gs://mybucket1/*', 'gs://mybucket2/folder5/*'].

     Per ulteriori informazioni sull'utilizzo degli URI Cloud Storage in BigQuery, consulta Percorso della risorsa Cloud Storage.

   • STALENESS_INTERVAL: specifica se I metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella degli oggetti e l'aggiornamento dei metadati memorizzati nella cache affinché l'operazione usarla. Per ulteriori informazioni sulle considerazioni sulla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per migliorare le prestazioni.

     Per disabilitare la memorizzazione nella cache dei metadati, specifica 0. Questa è l'impostazione predefinita.

     Per abilitare la memorizzazione nella cache dei metadati, specifica valore letterale intervallo compreso tra 30 minuti e 7 giorni. Ad esempio, specifica INTERVAL 4 HOUR per un intervallo di inattività di 4 ore. Con questo valore, le operazioni sulla tabella utilizzano i metadati memorizzati nella cache se è stato aggiornato nelle ultime 4 ore. Se i metadati memorizzati nella cache sono precedenti a questa data, l'operazione recupera i metadati da Cloud Storage.

   • CACHE_MODE: specifica se i metadati la cache viene aggiornata automaticamente o manualmente. Per ulteriori informazioni considerazioni sulla memorizzazione nella cache dei metadati, Memorizzazione nella cache dei metadati per migliorare le prestazioni.

     Imposta su AUTOMATIC per aggiornare la cache dei metadati a un intervallo definito dal sistema, in genere tra 30 e 60 minuti.

     Imposta MANUAL se vuoi aggiornare la cache dei metadati in base a una pianificazione che hai stabilito. In questo caso, puoi chiamare la procedura di sistema di BQ.REFRESH_EXTERNAL_METADATA_CACHE per aggiornare la cache.

     Devi impostare CACHE_MODE se STALENESS_INTERVAL è impostato su un valore maggiore maggiore di 0.

3. Fai clic su Esegui.

Per ulteriori informazioni su come eseguire query, consulta Eseguire una query interattiva.

Esempi

Nell'esempio seguente viene creata una tabella di oggetti con una cache di metadati intervallo di inattività di 1 giorno:

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'
);

L'esempio seguente crea una tabella di oggetti sugli oggetti in tre Bucket 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/*']
);

L'esempio seguente crea una tabella di oggetti solo sugli oggetti PDF in un bucket Cloud Storage:

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

bq

Utilizza la 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

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• DATASET_ID: l'ID del set di dati da che contiene la tabella dell'oggetto.
• TABLE_NAME: il nome della tabella dell'oggetto.
• REGION: il una o più regioni che contiene la connessione.
• CONNECTION_ID: l'ID del connessione alle risorse cloud da utilizzare con questa tabella esterna. La connessione determina quale account di servizio viene utilizzato per leggere i dati da Cloud Storage.

  Quando visualizzi i dettagli della connessione nella console Google Cloud, l'ID connessione è il valore nell'ultima sezione dell'ID connessione completo visualizzato in ID connessione, ad esempio projects/myproject/locations/connection_location/connections/myconnection.

• BUCKET_PATH: il percorso del bucket Cloud Storage contenente gli oggetti rappresentati dalla tabella degli oggetti, nel formato gs://bucket_name/[folder_name/]*.

  Puoi utilizzare un carattere jolly (*) in ogni percorso per limitare gli oggetti inclusi nella tabella degli oggetti. Ad esempio, se il bucket contiene diversi tipi di dati non strutturati, puoi creare la tabella degli oggetti solo per gli oggetti PDF specificando gs://bucket_name/*.pdf. Per ulteriori informazioni, vedi Supporto dei caratteri jolly per gli URI Cloud Storage.

  Puoi specificare più bucket per l'opzione uris fornendo più bucket percorsi, ad esempio gs://mybucket1/*,gs://mybucket2/folder5/*.

  Per ulteriori informazioni sull'utilizzo degli URI Cloud Storage in BigQuery, vedi Percorso della risorsa di Cloud Storage.

• STALENESS_INTERVAL: specifica se I metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella degli oggetti e l'aggiornamento dei metadati memorizzati nella cache affinché l'operazione usarla. Per ulteriori informazioni sulle considerazioni sulla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per migliorare le prestazioni.

  Per disabilitare la memorizzazione nella cache dei metadati, specifica 0. Questa è l'impostazione predefinita.

  Per abilitare la memorizzazione nella cache dei metadati, specifica un valore di intervallo compreso tra 30 minuti e 7 giorni, utilizzando Y-M D H:M:S descritto in Tipo di dati INTERVAL documentazione. Ad esempio, specifica 0-0 0 4:0:0 per un intervallo di inattività di 4 ore. Con questo valore, le operazioni sulla tabella utilizzano i metadati memorizzati nella cache se è stato aggiornato nelle ultime 4 ore. Se i metadati memorizzati nella cache precedente, l'operazione recupera i metadati Cloud Storage.

• CACHE_MODE: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente. Per ulteriori informazioni considerazioni sulla memorizzazione nella cache dei metadati, Memorizzazione nella cache dei metadati per migliorare le prestazioni.

  Imposta il valore AUTOMATIC affinché la cache dei metadati venga vengono aggiornati a un intervallo definito dal sistema, solitamente compreso tra 30 e 60 minuti.

  Imposta su MANUAL se vuoi aggiornare dei metadati in base a una pianificazione determinata da te. In questo caso, puoi chiamare la procedura di sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE per aggiornare la cache.

  Devi impostare CACHE_MODE se STALENESS_INTERVAL è impostato su un valore maggiore di 0.

Esempi

Nell'esempio seguente viene creata una tabella di oggetti con una cache di metadati intervallo di inattività di 1 giorno:

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

L'esempio seguente crea una tabella di oggetti sugli oggetti in tre Bucket 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

L'esempio seguente crea una tabella di oggetti solo per gli oggetti PDF in un bucket Cloud Storage:

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

API

Chiama il Metodo tables.insert. Includi un'opzione Oggetto ExternalDataConfiguration con il campo objectMetadata impostato su SIMPLE in Table risorsa che trasmetti.

L'esempio seguente mostra come chiamare questo metodo utilizzando 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

Questo esempio crea una tabella di oggetti con la memorizzazione nella cache dei metadati abilitata con aggiornamenti manuali.

Per eseguire l'autenticazione in BigQuery, configura il valore predefinito dell'applicazione Credenziali. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.

I campi chiave da specificare per una tabella di oggetti sono google_bigquery_table.external_data_configuration.object_metadata, google_bigquery_table.external_data_configuration.metadata_cache_mode, e google_bigquery_table.max_staleness. Per ulteriori informazioni su ogni risorsa, consulta la documentazione di 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
  ]
}

Per applicare la configurazione Terraform in un progetto Google Cloud, completa i passaggi nelle seguenti sezioni.

Prepara Cloud Shell

1. Avvia Cloud Shell.

2. Imposta il progetto Google Cloud predefinito dove vuoi applicare le configurazioni Terraform.

   Devi eseguire questo comando una sola volta per progetto e puoi eseguirlo in qualsiasi directory.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Le variabili di ambiente vengono sostituite se imposti valori espliciti in Terraform di configurazione del deployment.

Prepara la directory

Ogni file di configurazione Terraform deve avere una directory dedicata (inoltre chiamato modulo principale).

1. In Cloud Shell, crea una directory e un nuovo all'interno di quella directory. Il nome file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf.

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

2. Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

   Copia il codice campione nel nuovo oggetto main.tf.

   Facoltativamente, copia il codice da GitHub. Questa opzione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.

3. Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
4. Salva le modifiche.
5. Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory.

   terraform init

   Facoltativamente, per utilizzare la versione più recente del provider Google, includi -upgrade :

   terraform init -upgrade

Applica le modifiche

1. Rivedi la configurazione e verifica che le risorse che Terraform creerà o che l'aggiornamento soddisfi le tue aspettative:

   terraform plan

   Apporta le correzioni necessarie alla configurazione.

2. Applica la configurazione di Terraform eseguendo il seguente comando e inserendo yes al prompt:

   terraform apply

   Attendi finché Terraform non visualizzi il messaggio "Applicazione completata!". per creare un nuovo messaggio email.

3. Apri il progetto Google Cloud per visualizzare i risultati. Nella console Google Cloud, vai alle risorse nella UI per assicurarti create o aggiornate da Terraform.

Nota: gli esempi di Terraform in genere presuppongono che le API richieste siano nel tuo progetto Google Cloud.

Esegui query sulle tabelle di oggetti

Puoi eseguire query su una tabella di oggetti come su qualsiasi altra tabella BigQuery, ad esempio:

SELECT *
FROM mydataset.myobjecttable;

L'esecuzione di query sulla tabella di un oggetto restituisce i metadati per gli oggetti sottostanti. Per ulteriori informazioni, consulta Schema della tabella di oggetti.

Passaggi successivi

• Scopri come eseguire l'inferenza sulle tabelle degli oggetti immagine.
• Scopri come analizzare le tabelle di oggetti utilizzando le funzioni remote.