Creazione di tabelle di 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à:
- Crea una connessione per leggere le informazioni degli oggetti da Cloud Storage.
- Concedi l'autorizzazione a leggere le informazioni di Cloud Storage all'account di servizio associato alla connessione.
- Crea la tabella dell'oggetto e associala alla connessione utilizzando
l'istruzione
CREATE EXTERNAL TABLE
.
Prima di iniziare
- Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.
-
Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.
-
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.
-
Abilita le API BigQuery and BigQuery Connection API.
-
Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.
-
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.
-
Abilita le API BigQuery and BigQuery Connection API.
- Assicurati che l'amministratore BigQuery abbia creato una connessione e configurato l'accesso a Cloud Storage.
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 maggiori informazioni sui ruoli utente, consulta Modello di sicurezza. Per ulteriori informazioni sulla concessione delle autorizzazioni, consulta Visualizzazione dei ruoli assegnabili nelle risorse.
Amministratore di 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
) per il progetto.Per ottenere le autorizzazioni necessarie per creare e gestire i bucket Cloud Storage, chiedi all'amministratore di concederti il ruolo Amministratore Storage (
roles/storage.admin
) per il 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 necessarie, 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 di data warehouse
Per ottenere le autorizzazioni necessarie per creare le tabelle di oggetti, chiedi all'amministratore di concederti i ruoli seguenti nel progetto:
- Ruolo di Editor dati BigQuery (
roles/bigquery.dataEditor
). - Ruolo Amministratore connessioni BigQuery (
roles/bigquery.connectionAdmin
).
Questo ruolo predefinito contiene le autorizzazioni necessarie per creare tabelle di oggetti. Per visualizzare le autorizzazioni esatte necessarie, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie
bigquery.tables.create
bigquery.tables.update
bigquery.connections.delegate
- Ruolo di Editor dati BigQuery (
Analista di dati
Per ottenere le autorizzazioni necessarie per eseguire query sulle tabelle degli oggetti, chiedi all'amministratore di concederti i ruoli seguenti 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 visualizzare le autorizzazioni esatte necessarie, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie
bigquery.jobs.create
bigquery.tables.get
bigquery.tables.getData
bigquery.readsessions.create
Potresti essere in grado di ottenere queste autorizzazioni anche con i ruoli personalizzati o altri ruoli predefiniti.
- Ruolo Visualizzatore dati BigQuery (
Creazione di tabelle di oggetti
Prima di creare una tabella dell'oggetto, devi disporre di un set di dati esistente che la contenga. Per scoprire di più, consulta la sezione Creazione di set di dati.
Per creare una tabella degli oggetti:
SQL
Utilizza l'istruzione CREATE EXTERNAL TABLE
.
Nella console Google Cloud, vai alla pagina BigQuery.
Nell'Editor 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 che conterrà la tabella degli oggetti.TABLE_NAME
: il nome della tabella dell'oggetto.REGION
: la regione o più regioni che contiene la connessione.CONNECTION_ID
: l'ID della connessione alla risorsa cloud da utilizzare con questa tabella degli oggetti. La connessione determina quale account di servizio viene utilizzato per leggere i dati da Cloud Storage.Quando visualizza i dettagli della connessione nella console Google Cloud, l'ID connessione è il valore nell'ultima sezione dell'ID connessione completo mostrato 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 sugli oggetti PDF specificando['gs://bucket_name/*.pdf']
. Per maggiori 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 maggiori informazioni sull'utilizzo degli URI Cloud Storage in BigQuery, consulta Percorso della risorsa di Cloud Storage.
STALENESS_INTERVAL
: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni relative alla tabella dell'oggetto e quanto devono essere aggiornati i metadati memorizzati nella cache affinché l'operazione li utilizzi. Per maggiori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per migliorare le prestazioni.Per disattivare la memorizzazione nella cache dei metadati, specifica 0. Questa è l'impostazione predefinita.
Per abilitare la memorizzazione nella cache dei metadati, specifica un valore letterale a intervalli 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 la tabella è stata aggiornata nelle ultime 4 ore. Se i metadati memorizzati nella cache sono precedenti, l'operazione recupera i metadati da Cloud Storage.CACHE_MODE
: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente. Per saperne di più sulle considerazioni sulla memorizzazione nella cache dei metadati, consulta la pagina relativa alla memorizzazione dei metadati per le prestazioni.Imposta
AUTOMATIC
per aggiornare la cache dei metadati a un intervallo definito dal sistema, di solito tra 30 e 60 minuti.Imposta il valore
MANUAL
se vuoi aggiornare la cache dei metadati in base a una pianificazione stabilita. In questo caso, puoi chiamare la procedura di sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
per aggiornare la cache.Devi impostare
CACHE_MODE
seSTALENESS_INTERVAL
è impostato su un valore maggiore di 0.
Fai clic su
Esegui.
Per ulteriori informazioni su come eseguire le query, consulta Eseguire una query interattiva.
Esempi
L'esempio seguente crea una tabella degli oggetti con un intervallo di inattività 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 degli oggetti sopra gli oggetti nei 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 degli 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 conterrà la tabella degli oggetti.TABLE_NAME
: il nome della tabella dell'oggetto.REGION
: la regione o più regioni che contiene la connessione.CONNECTION_ID
: l'ID della connessione alla 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 visualizza i dettagli della connessione nella console Google Cloud, l'ID connessione è il valore nell'ultima sezione dell'ID connessione completo mostrato 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 formatogs://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 sugli oggetti PDF specificandogs://bucket_name/*.pdf
. Per maggiori informazioni, consulta Supporto dei caratteri jolly per gli URI di Cloud Storage.Puoi specificare più bucket per l'opzione
uris
fornendo più percorsi, ad esempiogs://mybucket1/*,gs://mybucket2/folder5/*
.Per maggiori informazioni sull'utilizzo degli URI Cloud Storage in BigQuery, consulta Percorso della risorsa di Cloud Storage.
STALENESS_INTERVAL
: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni relative alla tabella dell'oggetto e quanto devono essere aggiornati i metadati memorizzati nella cache affinché l'operazione li utilizzi. Per maggiori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per migliorare 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 sui tipi di datiINTERVAL
. Ad esempio, specifica0-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 la tabella è stata aggiornata nelle ultime 4 ore. Se i metadati memorizzati nella cache sono precedenti, l'operazione recupera i metadati da Cloud Storage.CACHE_MODE
: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente. Per saperne di più sulle considerazioni sulla memorizzazione nella cache dei metadati, consulta la pagina relativa alla memorizzazione dei metadati per le prestazioni.Imposta
AUTOMATIC
per aggiornare la cache dei metadati a un intervallo definito dal sistema, di solito tra 30 e 60 minuti.Imposta il valore
MANUAL
se vuoi aggiornare la cache dei metadati in base a una pianificazione stabilita. In questo caso, puoi chiamare la procedura di sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
per aggiornare la cache.Devi impostare
CACHE_MODE
seSTALENESS_INTERVAL
è impostato su un valore maggiore di 0.
Esempi
L'esempio seguente crea una tabella degli oggetti con un intervallo di inattività 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 degli oggetti sopra gli oggetti nei 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 degli 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 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 aggiornamento manuale.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
I campi chiave da specificare per una tabella dell'oggetto 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 ciascuna risorsa, consulta la documentazione di Terraform su BigQuery.
Per applicare la configurazione Terraform in un progetto Google Cloud, completa i passaggi nelle sezioni seguenti.
prepara Cloud Shell
- Avvia Cloud Shell.
-
Imposta il progetto Google Cloud predefinito a 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
Se imposti valori espliciti nel file di configurazione Terraform, le variabili di ambiente vengono sostituite.
Prepara la directory
Ogni file di configurazione Terraform deve avere una propria directory (detta anche modulo principale).
-
In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome del file deve avere l'estensione
.tf
, ad esempiomain.tf
. In questo tutorial, il file è indicato comemain.tf
.mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
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.Se vuoi, copia il codice da GitHub. Questa opzione è consigliata se lo snippet Terraform fa parte di una soluzione end-to-end.
- Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
- Salva le modifiche.
-
Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory.
terraform init
Facoltativamente, per utilizzare la versione più recente del provider Google, includi l'opzione
-upgrade
:terraform init -upgrade
Applica le modifiche
-
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.
-
Applica la configurazione Terraform eseguendo il comando seguente e inserendo
yes
al prompt:terraform apply
Attendi finché Terraform non visualizza il messaggio "Applicazione completata".
- Apri il progetto Google Cloud per visualizzare i risultati. Nella console Google Cloud, vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.
Query sulle tabelle degli oggetti
Puoi eseguire query su una tabella degli oggetti come qualsiasi altro BigQuery, ad esempio:
SELECT * FROM mydataset.myobjecttable;
L'esecuzione di query su una tabella degli oggetti restituisce i metadati per gli oggetti sottostanti. Per ulteriori informazioni, consulta Schema della tabella degli oggetti.
Passaggi successivi
- Scopri come eseguire l'inferenza sulle tabelle degli oggetti immagine.
- Scopri come analizzare le tabelle di oggetti utilizzando le funzioni remote.