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à:
- Crea una connessione per leggere l'oggetto da Cloud Storage.
- Concedi l'autorizzazione a leggere le informazioni di Cloud Storage nel servizio associato alla connessione.
- Crea la tabella degli oggetti e associala alla connessione utilizzando il metodo
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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.
-
Abilita le API BigQuery and BigQuery Connection API.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
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 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 bucket Cloud Storage, chiedi che ti conceda il ruolo Amministratore Storage (
roles/storage.admin
) per del progetto.Questo ruolo predefinito contiene le autorizzazioni necessarie per connettersi a Cloud Storage e creare e gestire bucket Cloud Storage. Per vedere le autorizzazioni esatte richieste, espandi la sezione Obbligatorio Autorizzazioni:
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 l'oggetto tabelle. Per vedere le autorizzazioni esatte richieste, espandi la sezione Obbligatorio Autorizzazioni:
Autorizzazioni obbligatorie
bigquery.tables.create
bigquery.tables.update
bigquery.connections.delegate
- Ruolo Editor dati BigQuery (
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.
- Ruolo Visualizzatore dati BigQuery (
Creare tabelle di oggetti
Prima di creare una tabella di oggetti, devi disporre di un set di dati esistente che contenga li annotino. Per saperne di più, consulta la sezione Creazione di set di dati.
Per creare una tabella di oggetti:
SQL
Utilizza la
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 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 di oggetti. La connessione determina quale 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 asterisco (
*
) in ciascun 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, 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 per BigQuery, consulta 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 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 sia precedente, l'operazione recupera i metadati 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 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 diBQ.REFRESH_EXTERNAL_METADATA_CACHE
per aggiornare la cache.Devi impostare
CACHE_MODE
seSTALENESS_INTERVAL
è impostato su un valore maggiore maggiore di 0.
Fai clic su
Esegui.
Per ulteriori informazioni su come eseguire le 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=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 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 di archiviazione ideale in Cloud Storage.Quando visualizzi i dettagli della connessione nella console Google Cloud, l'ID connessione è il valore riportato nell'ultima sezione ID connessione completo mostrato in 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 formatogs://bucket_name/[folder_name/]*
.Puoi utilizzare un carattere jolly asterisco (
*
) in ciascun 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 specificandogs://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 esempiogs://mybucket1/*,gs://mybucket2/folder5/*
.Per ulteriori informazioni sull'utilizzo degli URI Cloud Storage in per BigQuery, consulta 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 intervallo di valori compreso tra 30 minuti e 7 giorni, utilizzando
Y-M D H:M:S
descritto in Tipo di datiINTERVAL
documentazione. Ad esempio, specifica0-0 0 4:0:0
per un 4 di inattività di ora. 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 sia precedente, l'operazione recupera i metadati 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 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 diBQ.REFRESH_EXTERNAL_METADATA_CACHE
per aggiornare la cache.Devi impostare
CACHE_MODE
seSTALENESS_INTERVAL
è impostato su un valore maggiore 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 sugli 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'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
In questo esempio viene creata una tabella di oggetti con la memorizzazione nella cache dei metadati abilitata con aggiornamento manuale.
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 saperne di più su ciascuna risorsa, consulta la documentazione di BigQuery su Terraform.
Per applicare la configurazione Terraform a un progetto Google Cloud, completa i passaggi nella le sezioni seguenti.
Prepara Cloud Shell
- Avvia Cloud Shell.
-
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).
-
In Cloud Shell, crea una directory e un nuovo
all'interno di quella directory. Il nome file deve contenere i caratteri
.tf
, ad esempiomain.tf
. In questo tutorial, il file è denominatomain.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 nuovo oggetto
main.tf
.Facoltativamente, copia il codice da GitHub. Opzione consigliata quando 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
-upgrade
:terraform init -upgrade
Applica le modifiche
-
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.
-
Applica la configurazione Terraform eseguendo questo comando e inserendo
yes
alla richiesta:terraform apply
Attendi finché Terraform non visualizzi il messaggio "Applicazione completata!". per creare un nuovo messaggio email.
- 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.
Query su tabelle di oggetti
Puoi eseguire query su una tabella di oggetti come qualsiasi altra tabella BigQuery, esempio:
SELECT * FROM mydataset.myobjecttable;
L'esecuzione di query sulla tabella di un oggetto restituisce i metadati per gli oggetti sottostanti. Per maggiori informazioni le informazioni, vedi Schema della tabella degli oggetti.
Passaggi successivi
- Scopri come eseguire l'inferenza sulle tabelle di oggetti immagine.
- Scopri come analizzare le tabelle degli oggetti utilizzando le funzioni remote.