Trasferimenti dei rapporti di Cloud Storage
BigQuery Data Transfer Service per Cloud Storage consente di pianificare caricamenti di dati ricorrenti da Cloud Storage a BigQuery.
Prima di iniziare
Prima di creare un trasferimento Cloud Storage, segui questi passaggi:
- Verifica di aver completato tutte le azioni richieste in Attivazione di BigQuery Data Transfer Service.
- Recupera l'URI Cloud Storage.
- Crea un set di dati BigQuery per archiviare i tuoi dati.
- Crea la tabella di destinazione per il trasferimento e specifica la definizione dello schema.
- Se prevedi di specificare una chiave di crittografia gestita dal cliente (CMEK), assicurati che il tuo account di servizio disponga delle autorizzazioni per criptare e decriptare e che sia necessario l'ID risorsa della chiave Cloud KMS per utilizzare CMEK. Per informazioni su come funziona CMEK con BigQuery Data Transfer Service, vedi Specificare la chiave di crittografia con trasferimenti.
Limitazioni
I trasferimenti ricorrenti da Cloud Storage a BigQuery sono soggetti alle seguenti limitazioni:
- Tutti i file che corrispondono ai pattern definiti da un carattere jolly o dai parametri di runtime per il trasferimento devono condividere lo stesso schema definito per la tabella di destinazione, altrimenti il trasferimento non andrà a buon fine. Anche le modifiche allo schema della tabella tra le esecuzioni causano il mancato trasferimento.
- Poiché gli oggetti Cloud Storage possono essere sottoposti al controllo delle versioni, è importante notare che gli oggetti Cloud Storage archiviati non sono supportati per i trasferimenti di BigQuery. Per poter essere trasferiti, gli oggetti devono essere attivi.
- A differenza dei caricamenti individuali di dati da Cloud Storage a BigQuery, per i trasferimenti in corso è necessario creare la tabella di destinazione prima di configurare il trasferimento. Per i file CSV e JSON, devi anche definire in anticipo lo schema della tabella. BigQuery non può creare la tabella nell'ambito del processo di trasferimento di dati ricorrente.
- Per impostazione predefinita, i trasferimenti da Cloud Storage impostano il parametro Preferenza di scrittura su
APPEND
. In questa modalità, un file non modificato può essere caricato in BigQuery solo una volta. Se la proprietàlast modification time
del file viene aggiornata, il file verrà ricaricato. BigQuery Data Transfer Service non garantisce che tutti i file verranno trasferiti o trasferiti solo una volta se i file di Cloud Storage vengono toccati durante il trasferimento. Sei soggetto alle seguenti limitazioni quando carichi dati in BigQuery da un bucket Cloud Storage:
Se la località del set di dati è impostata su un valore diverso dall'area multiregionale
US
, il bucket Cloud Storage deve trovarsi nella stessa regione o all'interno della stessa area multiregionale del set di dati.BigQuery non garantisce la coerenza dei dati per le origini dati esterne. Le modifiche ai dati sottostanti durante l'esecuzione di una query possono causare comportamenti imprevisti.
BigQuery non supporta il controllo delle versioni degli oggetti Cloud Storage. Se includi un numero di generazione nell'URI Cloud Storage, il job di caricamento non riesce.
A seconda del formato dei dati di origine di Cloud Storage, potrebbero essere previste ulteriori limitazioni. Per ulteriori informazioni, consulta:
Il bucket Cloud Storage deve trovarsi in una località compatibile con la regione o le regioni del set di dati di destinazione in BigQuery. Questa operazione è nota come colocation. Per maggiori dettagli, consulta Località dei dati di trasferimento in Cloud Storage.
Intervalli minimi
- I file di origine vengono prelevati per il trasferimento immediatamente, senza durata minima dei file.
- L'intervallo minimo tra un trasferimento ricorrente e l'altro è di 15 minuti. L'intervallo predefinito per un trasferimento ricorrente è ogni 24 ore.
Autorizzazioni obbligatorie
Quando carichi dati in BigQuery, devi disporre delle autorizzazioni che ti consentano di caricare i dati in tabelle e partizioni BigQuery nuove o esistenti. Se carichi i dati da Cloud Storage, avrai anche bisogno di accedere al bucket che contiene i dati. Assicurati di disporre delle seguenti autorizzazioni obbligatorie:
BigQuery: assicurati che la persona o l'account di servizio che crea il trasferimento disponga delle seguenti autorizzazioni in BigQuery:
bigquery.transfers.update
autorizzazioni per creare il trasferimento- Entrambe le autorizzazioni
bigquery.datasets.get
ebigquery.datasets.update
sul set di dati di destinazione
Il ruolo IAM predefinito di
bigquery.admin
include le autorizzazionibigquery.transfers.update
,bigquery.datasets.update
ebigquery.datasets.get
. Per ulteriori informazioni sui ruoli IAM in BigQuery Data Transfer Service, consulta Controllo dell'accesso.Cloud Storage: sono necessarie
storage.objects.get
autorizzazioni per il singolo bucket o superiore. Se utilizzi un carattere jolly URI, devi disporre anche delle autorizzazionistorage.objects.list
. Se vuoi eliminare i file di origine dopo ogni trasferimento riuscito, devi avere anche le autorizzazionistorage.objects.delete
. Il ruolo IAM predefinitostorage.objectAdmin
include tutte queste autorizzazioni.
Configura un trasferimento Cloud Storage
Per creare un trasferimento Cloud Storage in BigQuery Data Transfer Service:
Console
Vai alla pagina BigQuery nella console Google Cloud.
Fai clic su
Trasferimenti di dati.Fai clic su
Crea trasferimento.Nella sezione Tipo di origine, per Origine, scegli Google Cloud Storage.
Nella sezione Nome configurazione trasferimento, in Nome visualizzato, inserisci un nome per il trasferimento, ad esempio
My Transfer
. Il nome del trasferimento può essere qualsiasi valore che ti consenta di identificare il trasferimento se devi modificarlo in un secondo momento.Nella sezione Opzioni di pianificazione:
Seleziona Frequenza di ripetizione. Se selezioni Ore, Giorni, Settimane o Mesi, devi specificare anche una frequenza. Puoi anche selezionare Personalizzata per specificare una frequenza di ripetizione personalizzata. Se selezioni On demand, questo trasferimento verrà eseguito quando attivi manualmente il trasferimento.
Se applicabile, seleziona Inizia ora o Inizia all'ora impostata e fornisci una data di inizio e un'ora di esecuzione.
Nella sezione Impostazioni destinazione, per Set di dati di destinazione, scegli il set di dati creato per archiviare i dati.
Nella sezione Dettagli origine dati:
- In Tabella di destinazione, inserisci il nome della tabella di destinazione. La tabella di destinazione deve seguire le regole di denominazione delle tabelle. I nomi delle tabelle di destinazione supportano anche i parametri.
- In URI Cloud Storage, inserisci l'URI Cloud Storage. Sono supportati i caratteri jolly e i parametri.
- In Preferenza di scrittura, scegli:
- APPEND per aggiungere in modo incrementale nuovi dati alla tabella di destinazione esistente. APPEND è il valore predefinito per Write preference (Preferenza di scrittura).
- MIRROR per sovrascrivere i dati nella tabella di destinazione durante ogni esecuzione di trasferimento.
Per ulteriori informazioni su come BigQuery Data Transfer Service importa i dati utilizzando APPEND o MIRROR, consulta Importazione dei dati per i trasferimenti di Cloud Storage. Per ulteriori informazioni sul campo
writeDisposition
, consultaJobConfigurationLoad
.- In Elimina i file di origine dopo il trasferimento, seleziona la casella se vuoi eliminare i file di origine dopo ogni trasferimento riuscito. Eliminare i job fa il possibile. I job di eliminazione non riprovano se il primo tentativo per eliminare i file di origine non va a buon fine.
Nella sezione Opzioni di trasferimento:
- In Tutti i formati:
- In Numero di errori consentiti, inserisci il numero massimo di record non validi che BigQuery può ignorare durante l'esecuzione del job. Se il numero di record non validi supera questo valore, nel risultato del job viene restituito un errore "non valido" e il job non riesce. Il valore predefinito è
0
. - (Facoltativo) Per i tipi di destinazione decimale, inserisci un elenco separato da virgole di possibili tipi di dati SQL in cui potrebbero essere convertiti i valori decimali di origine. Il tipo di dati SQL
selezionato per la conversione dipende dalle seguenti
condizioni:
- Il tipo di dati selezionato per la conversione sarà il primo tipo di dati dell'elenco seguente a supportare la precisione e la scala dei dati di origine in questo ordine: NUMERIC, BIGNUMERIC e STRING.
- Se nessuno dei tipi di dati elencati supporta la precisione e la scala, viene selezionato il tipo di dati che supporta l'intervallo più ampio nell'elenco specificato. Se un valore supera l'intervallo supportato durante la lettura dei dati di origine, verrà generato un errore.
- Il tipo di dati STRING supporta tutti i valori di precisione e scala.
- Se questo campo viene lasciato vuoto, il tipo di dati predefinito sarà "NUMERIC,STRING" per ORC e "NUMERIC" per gli altri formati file.
- Questo campo non può contenere tipi di dati duplicati.
- L'ordine dei tipi di dati elencati in questo campo viene ignorato.
- In Numero di errori consentiti, inserisci il numero massimo di record non validi che BigQuery può ignorare durante l'esecuzione del job. Se il numero di record non validi supera questo valore, nel risultato del job viene restituito un errore "non valido" e il job non riesce. Il valore predefinito è
- In JSON, CSV:
- In Ignora valori sconosciuti, seleziona la casella se vuoi che il trasferimento trasmetta i dati che non corrispondono allo schema della tabella di destinazione.
- In AVRO:
- Per Utilizza tipi logici avro, seleziona la casella se vuoi che il trasferimento convertirà i tipi logici Avro nei tipi di dati BigQuery corrispondenti. Il
comportamento predefinito prevede di ignorare l'attributo
logicalType
per la maggior parte dei tipi e utilizzare invece il tipo Avro sottostante.
- Per Utilizza tipi logici avro, seleziona la casella se vuoi che il trasferimento convertirà i tipi logici Avro nei tipi di dati BigQuery corrispondenti. Il
comportamento predefinito prevede di ignorare l'attributo
In CSV:
- In Delimitatore di campo, inserisci il carattere che separa i campi. Il valore predefinito è una virgola.
- Per Carattere, inserisci il carattere utilizzato per
citare le sezioni di dati in un file CSV. Il valore predefinito sono le virgolette doppie (
"
). - In Righe di intestazione da saltare, inserisci il numero di righe di intestazione
nei file di origine se non vuoi importarli. Il valore predefinito è
0
. - Per Consenti nuove righe tra virgolette, seleziona la casella se vuoi consentire gli a capo all'interno dei campi tra virgolette.
- Per Consenti righe frastagliate, seleziona la casella se vuoi consentire il trasferimento di righe con
NULLABLE
colonne mancanti.
- In Tutti i formati:
Nel menu Account di servizio, seleziona un account di servizio dagli account di servizio associati al tuo progetto Google Cloud. Puoi associare un account di servizio al trasferimento anziché utilizzare le tue credenziali utente. Per ulteriori informazioni sull'utilizzo di account di servizio con trasferimenti di dati, vedi Utilizzare account di servizio.
- Se hai eseguito l'accesso con un'identità federata, sarà necessario un account di servizio per creare un trasferimento. Se hai eseguito l'accesso con un Account Google, un account di servizio per il trasferimento è facoltativo.
- L'account di servizio deve disporre delle autorizzazioni richieste sia per BigQuery che per Cloud Storage.
(Facoltativo) Nella sezione Opzioni di notifica:
- Fai clic sul pulsante di attivazione/disattivazione per abilitare le notifiche via email. Quando abiliti questa opzione, il proprietario della configurazione di trasferimento riceve una notifica via email quando un trasferimento non va a buon fine.
- In Seleziona un argomento Pub/Sub, scegli il nome dell'argomento o fai clic su Crea un argomento. Questa opzione consente di configurare le notifiche di Pub/Sub per il trasferimento.
(Facoltativo) Nella sezione Opzioni avanzate:
- Se utilizzi CMEK, seleziona Chiave gestita dal cliente. Viene visualizzato un elenco delle CMEK disponibili tra cui puoi scegliere.
Per informazioni su come funzionano le CMEK con BigQuery Data Transfer Service, vedi Specificare la chiave di crittografia con i trasferimenti.
Fai clic su Salva.
bq
Inserisci il comando bq mk
e fornisci il flag di creazione del trasferimento
--transfer_config
. Sono necessari anche i seguenti flag:
--data_source
--display_name
--target_dataset
--params
Flag facoltativi:
--destination_kms_key
: specifica l'ID risorsa della chiave per la chiave Cloud KMS se utilizzi una chiave di crittografia gestita dal cliente (CMEK) per questo trasferimento. Per informazioni su come funzionano le CMEK con BigQuery Data Transfer Service, vedi Specificare la chiave di crittografia con i trasferimenti.--service_account_name
: specifica un account di servizio da utilizzare per l'autenticazione del trasferimento di Cloud Storage al posto del tuo account utente.
bq mk \ --transfer_config \ --project_id=PROJECT_ID \ --data_source=DATA_SOURCE \ --display_name=NAME \ --target_dataset=DATASET \ --destination_kms_key="DESTINATION_KEY" \ --params='PARAMETERS' \ --service_account_name=SERVICE_ACCOUNT_NAME
Dove:
- PROJECT_ID è l'ID progetto. Se
--project_id
non è fornito per specificare un particolare progetto, viene utilizzato il progetto predefinito. - DATA_SOURCE è l'origine dati, ad esempio
google_cloud_storage
. - NAME è il nome visualizzato della configurazione di trasferimento. Il nome del trasferimento può essere qualsiasi valore che ti consenta di identificare il trasferimento, qualora dovessi modificarlo in un secondo momento.
- DATASET è il set di dati di destinazione per la configurazione del trasferimento.
- DESTINATION_KEY: l'ID risorsa della chiave Cloud KMS, ad esempio
projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name
. - PARAMETERS contiene i parametri per la configurazione di trasferimento
creata in formato JSON. Ad esempio:
--params='{"param":"param_value"}'
.destination_table_name_template
: il nome della tabella BigQuery di destinazione.data_path_template
: l'URI Cloud Storage contenente i file da trasferire, che può includere un carattere jolly.write_disposition
: determina se i file corrispondenti vengono aggiunti alla tabella di destinazione o sottoposti a mirroring completo. I valori supportati sonoAPPEND
oMIRROR
. Per informazioni su come BigQuery Data Transfer Service aggiunge o esegue il mirroring dei dati nei trasferimenti di Cloud Storage, consulta Importazione dei dati per i trasferimenti di Cloud Storage.file_format
: il formato dei file che vuoi trasferire. Il formato può essereCSV
,JSON
,AVRO
,PARQUET
oORC
. Il valore predefinito èCSV
.max_bad_records
: per qualsiasi valorefile_format
, il numero massimo di record non validi che possono essere ignorati. Il valore predefinito è0
.decimal_target_types
: per qualsiasi valorefile_format
, un elenco separato da virgole di possibili tipi di dati SQL in cui potrebbero essere convertiti i valori decimali di origine. Se questo campo non viene fornito, il tipo di dati predefinito è"NUMERIC,STRING"
perORC
e"NUMERIC"
per gli altri formati file.ignore_unknown_values
: per qualsiasi valorefile_format
, imposta suTRUE
per accettare righe contenenti valori che non corrispondono allo schema. Per maggiori informazioni, consulta i dettagli del campoignoreUnknownvalues
nella tabella di riferimento diJobConfigurationLoad
.use_avro_logical_types
: per i valorifile_format
diAVRO
, imposta suTRUE
per interpretare i tipi logici nei tipi corrispondenti (ad esempioTIMESTAMP
), anziché utilizzare solo i tipi non elaborati (ad esempioINTEGER
).parquet_enum_as_string
: per i valorifile_format
diPARQUET
, imposta suTRUE
per dedurre il tipo logicoPARQUET
ENUM
comeSTRING
anziché il valore predefinitoBYTES
.parquet_enable_list_inference
: per i valorifile_format
diPARQUET
, imposta suTRUE
per utilizzare l'inferenza dello schema specifica per il tipo logicoPARQUET
LIST
.reference_file_schema_uri
: un percorso URI di un file di riferimento con lo schema del lettore.field_delimiter
: per i valorifile_format
diCSV
, un carattere che separa i campi. Il valore predefinito è una virgola.quote
: per i valorifile_format
diCSV
, un carattere utilizzato per citare le sezioni di dati in un file CSV. Il valore predefinito è le virgolette doppie ("
).skip_leading_rows
: per i valorifile_format
diCSV
, indica il numero di righe di intestazione iniziali che non vuoi importare. Il valore predefinito è 0.allow_quoted_newlines
: per i valorifile_format
diCSV
, imposta suTRUE
per consentire gli a capo all'interno dei campi tra virgolette.allow_jagged_rows
: per i valorifile_format
diCSV
, imposta suTRUE
per accettare le righe in cui mancano le colonne facoltative finali. I valori mancanti vengono inseriti conNULL
.preserve_ascii_control_characters
: per i valorifile_format
diCSV
, imposta suTRUE
per conservare tutti i caratteri di controllo ASCII incorporati.encoding
: specifica il tipo di codificaCSV
. I valori supportati sonoUTF8
,ISO_8859_1
,UTF16BE
,UTF16LE
,UTF32BE
eUTF32LE
.delete_source_files
: imposta suTRUE
per eliminare i file di origine dopo ogni trasferimento riuscito. I job di eliminazione non vengono eseguiti nuovamente se il primo tentativo di eliminare il file di origine non va a buon fine. Il valore predefinito èFALSE
.
- SERVICE_ACCOUNT_NAME è il nome dell'account di servizio utilizzato
per autenticare il trasferimento. L'account di servizio deve essere di proprietà dello stesso
project_id
utilizzato per creare il trasferimento e deve avere tutte le autorizzazioni richieste.
Ad esempio, il seguente comando crea un trasferimento Cloud Storage denominato My Transfer
utilizzando un valore data_path_template
di gs://mybucket/myfile/*.csv
, un set di dati di destinazione mydataset
e file_format
CSV
. Questo esempio include valori non predefiniti per i parametri facoltativi
associati al file_format CSV
.
Il trasferimento viene creato nel progetto predefinito:
bq mk --transfer_config \
--target_dataset=mydataset \
--project_id=myProject \
--display_name='My Transfer' \
--destination_kms_key=projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey \
--params='{"data_path_template":"gs://mybucket/myfile/*.csv",
"destination_table_name_template":"MyTable",
"file_format":"CSV",
"max_bad_records":"1",
"ignore_unknown_values":"true",
"field_delimiter":"|",
"quote":";",
"skip_leading_rows":"1",
"allow_quoted_newlines":"true",
"allow_jagged_rows":"false",
"delete_source_files":"true"}' \
--data_source=google_cloud_storage \
--service_account_name=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com projects/862514376110/locations/us/transferConfigs/ 5dd12f26-0000-262f-bc38-089e0820fe38
Dopo aver eseguito il comando, viene visualizzato un messaggio simile al seguente:
[URL omitted] Please copy and paste the above URL into your web browser and
follow the instructions to retrieve an authentication code.
Segui le istruzioni e incolla il codice di autenticazione nella riga di comando.
API
Utilizza il metodo projects.locations.transferConfigs.create
e fornisci un'istanza della risorsa TransferConfig
.
Java
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Java di BigQuery.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Specifica la chiave di crittografia con trasferimenti
Puoi specificare le chiavi di crittografia gestite dal cliente (CMEK) per criptare i dati per un'esecuzione di trasferimento. Puoi utilizzare una CMEK per supportare i trasferimenti da Cloud Storage.Quando specifichi una CMEK con un trasferimento, BigQuery Data Transfer Service applica la chiave CMEK a qualsiasi cache intermedia su disco dei dati importati, in modo che l'intero flusso di lavoro di trasferimento di dati sia conforme a CMEK.
Non puoi aggiornare un trasferimento esistente per aggiungere una CMEK se il trasferimento non è stato creato in origine con una CMEK. Ad esempio, non puoi cambiare una tabella di destinazione precedentemente criptata per impostazione predefinita in modo che sia ora crittografata con CMEK. Inoltre, non puoi cambiare una tabella di destinazione criptata con CMEK in modo da avere un tipo diverso di crittografia.
Puoi aggiornare una CMEK per il trasferimento se la configurazione di trasferimento è stata originariamente creata con una crittografia CMEK. Quando aggiorni una CMEK per una configurazione di trasferimento, BigQuery Data Transfer Service propaga la CMEK alle tabelle di destinazione alla successiva esecuzione del trasferimento, dove BigQuery Data Transfer Service sostituisce qualsiasi CMEK obsoleta con la nuova CMEK durante l'esecuzione del trasferimento. Per ulteriori informazioni, vedi Aggiornare un trasferimento.
Puoi anche usare le chiavi predefinite di progetto. Quando specifichi una chiave predefinita del progetto con un trasferimento, BigQuery Data Transfer Service utilizza la chiave predefinita del progetto come chiave predefinita per qualsiasi nuova configurazione di trasferimento.
Attivare manualmente un trasferimento
Oltre ai trasferimenti pianificati automaticamente da Cloud Storage, puoi attivare manualmente un trasferimento per caricare file di dati aggiuntivi.
Se la configurazione di trasferimento è con parametri di runtime, dovrai specificare un intervallo di date per il quale verranno avviati ulteriori trasferimenti.
Per attivare un trasferimento:
Console
Vai alla pagina BigQuery nella console Google Cloud.
Fai clic su
Trasferimenti di dati.Seleziona il trasferimento dall'elenco.
Fai clic su Esegui trasferimento ora o Pianifica backfill (per le configurazioni di trasferimento con parametri di runtime).
Se hai fatto clic su Esegui trasferimento ora, seleziona Esegui trasferimento una tantum o Esegui per una data specifica, a seconda dei casi. Se hai selezionato Esegui per una data specifica, seleziona una data e un'ora specifiche:
Se hai fatto clic su Pianifica backfill, seleziona Esegui trasferimento una tantum o Esegui per un intervallo di date, a seconda dei casi. Se hai selezionato Esegui per un intervallo di date, seleziona una data e un'ora di inizio e di fine:
Fai clic su Ok.
bq
Inserisci il comando bq mk
e fornisci il flag --transfer_run
. Puoi utilizzare il flag --run_time
o i flag --start_time
e --end_time
.
bq mk \ --transfer_run \ --start_time='START_TIME' \ --end_time='END_TIME' \ RESOURCE_NAME
bq mk \ --transfer_run \ --run_time='RUN_TIME' \ RESOURCE_NAME
Dove:
START_TIME e END_TIME sono timestamp che terminano con
Z
o contengono una differenza di fuso orario valida. Ad esempio:2017-08-19T12:11:35.00Z
2017-05-25T00:00:00+00:00
RUN_TIME è un timestamp che specifica l'ora di pianificare l'esecuzione del trasferimento di dati. Se vuoi eseguire un trasferimento una tantum per l'ora corrente, puoi utilizzare il flag
--run_time
.RESOURCE_NAME è il nome della risorsa del trasferimento (chiamato anche configurazione del trasferimento), ad esempio
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7
. Se non conosci il nome della risorsa del trasferimento, esegui il comandobq ls --transfer_config --transfer_location=LOCATION
per trovarlo.
API
Utilizza il metodo projects.locations.transferConfigs.startManualRuns
e fornisci la risorsa di configurazione del trasferimento utilizzando il parametro parent
.
Passaggi successivi
- Scopri di più sui parametri di runtime nei trasferimenti di Cloud Storage.
- Scopri di più su BigQuery Data Transfer Service.