Creare tabelle degli oggetti

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

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

  1. Crea una connessione per leggere le informazioni sugli oggetti da Cloud Storage.
  2. Concedi il ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer) alaccount di serviziot associato alla connessione.
  3. Crea la tabella degli oggetti e associala alla connessione utilizzando l'istruzione 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.

    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.

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud 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.
  8. Assicurati che l'amministratore BigQuery abbia creato una connessione e configurato l'accesso a Cloud Storage.

    9. Ruoli obbligatori

    Per lavorare con le tabelle degli oggetti, gli utenti devono disporre delle seguenti autorizzazioni IAM in base al loro ruolo nell'organizzazione. Per ulteriori informazioni sui ruoli utente, consulta Modello di sicurezza. Per ulteriori informazioni sulla concessione delle autorizzazioni, vedi Visualizzazione dei ruoli assegnabili sulle risorse.

    • Amministratore del data lake

      Per ottenere le autorizzazioni necessarie per connetterti a Cloud Storage, chiedi all'amministratore di concederti il ruolo Amministratore connessioni BigQuery (roles/bigquery.connectionAdmin) nel progetto.

      Per ottenere le autorizzazioni necessarie per creare e gestire 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 vedere quali sono esattamente le autorizzazioni 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 del data warehouse

      Per ottenere le autorizzazioni necessarie per creare tabelle di oggetti, chiedi all'amministratore di concederti 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 quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

      Autorizzazioni obbligatorie

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

    • Analista di dati

      Per ottenere le autorizzazioni necessarie per interrogare le tabelle degli 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 sulle tabelle degli oggetti. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

      Autorizzazioni obbligatorie

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

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

    Creare tabelle degli oggetti

    Prima di creare una tabella degli oggetti, devi disporre di un set di dati esistente che la contenga. Per saperne di più, consulta Creazione di set di dati.

    Per creare una tabella degli 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`| DEFAULT}
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 che deve contenere la tabella degli oggetti.
      • TABLE_NAME: il nome della tabella degli oggetti.
      • REGION: la regione o multiregione che contiene la connessione.
      • CONNECTION_ID: l'ID della connessione risorsa cloud da utilizzare con questa tabella degli oggetti. La connessione determina quale service account 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.

        Per utilizzare una connessione predefinita, specifica DEFAULT anziché la stringa di connessione contenente PROJECT_ID.REGION.CONNECTION_ID.

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

        Puoi utilizzare un carattere jolly asterisco (*) 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 maggiori informazioni, consulta Supporto dei caratteri jolly per gli URI 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 quanto devono essere aggiornati i metadati memorizzati nella cache affinché l'operazione li utilizzi. Per ulteriori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.

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

        Per attivare la memorizzazione nella cache dei metadati, specifica un valore letterale di intervallo compreso tra 30 minuti e 7 giorni. Ad esempio, specifica INTERVAL 4 HOUR per un intervallo di obsolescenza di 4 ore. Con questo valore, le operazioni sulla tabella utilizzano i metadati memorizzati nella cache se sono stati aggiornati nelle ultime 4 ore. Se i metadati memorizzati nella cache sono più vecchi, l'operazione recupera i metadati da Cloud Storage.

      • CACHE_MODE: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente. Per ulteriori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per 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 determini. 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.

    3. Fai clic su Esegui.

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

    Esempi

    Il seguente esempio crea una tabella degli oggetti con un intervallo di obsolescenza della cache dei metadati 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 per gli 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 il comando bq mk.

    bq mk --table \
--external_table_definition=BUCKET_PATH@REGION.CONNECTION_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 che deve contenere la tabella degli oggetti.
    • TABLE_NAME: il nome della tabella degli oggetti.
    • REGION: la regione o multiregione che contiene la connessione.
    • CONNECTION_ID: l'ID della connessione risorsa 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 che contiene gli oggetti rappresentati dalla tabella degli oggetti, nel formato gs://bucket_name/[folder_name/]*.

      Puoi utilizzare un carattere jolly asterisco (*) 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 maggiori informazioni, consulta Supporto dei caratteri jolly per gli URI 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 quanto devono essere aggiornati i metadati memorizzati nella cache affinché l'operazione li utilizzi. Per ulteriori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.

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

      Per attivare la memorizzazione nella cache dei metadati, specifica un valore di intervallo compreso tra 30 minuti e 7 giorni utilizzando il formato Y-M D H:M:S descritto nella documentazione del tipo di dati INTERVAL. Ad esempio, specifica 0-0 0 4:0:0 per un intervallo di obsolescenza di 4 ore. Con questo valore, le operazioni sulla tabella utilizzano i metadati memorizzati nella cache se sono stati aggiornati nelle ultime 4 ore. Se i metadati memorizzati nella cache sono più vecchi, l'operazione recupera i metadati da Cloud Storage.

    • CACHE_MODE: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente. Per ulteriori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per 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 determini. 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

    Il seguente esempio crea una tabella degli oggetti con un intervallo di obsolescenza della cache dei metadati 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/*.pdf@us.my-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

    API

    Chiama il metodo tables.insert. Includi un oggetto ExternalDataConfiguration con il campo objectMetadata impostato su SIMPLE nella risorsa Table 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 degli oggetti con la memorizzazione nella cache dei metadati abilitata con l'aggiornamento manuale.

    Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare 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 saperne di più 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 di Terraform in un progetto Google Cloud , completa i passaggi nelle sezioni seguenti.

    Prepara Cloud Shell

    1. Avvia Cloud Shell.

    2. Imposta il progetto Google Cloud predefinito in cui 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 nel file di configurazione Terraform.

    Prepara la directory

    Ogni file di configurazione di Terraform deve avere la propria directory (chiamata anche modulo radice).

    1. In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file viene 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 file main.tf appena creato.

      (Facoltativo) Copia il codice da GitHub. Questa operazione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.

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

      (Facoltativo) Per utilizzare l'ultima versione del provider Google, includi l'opzione -upgrade: 

      terraform init -upgrade

    Applica le modifiche

    1. Rivedi la configurazione e verifica che le risorse che Terraform creerà o aggiornerà corrispondano alle tue aspettative: 
      terraform plan

      Apporta le correzioni necessarie alla configurazione.

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

      Attendi che Terraform visualizzi il messaggio "Apply complete!" (Applicazione completata).

    3. Apri il tuo Google Cloud progetto per visualizzare i risultati. Nella console Google Cloud , vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.

    Eseguire 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 su una tabella di oggetti restituisce i metadati degli oggetti sottostanti. Per ulteriori informazioni, vedi Schema della tabella degli oggetti.

    Passaggi successivi