Trasferimenti dei rapporti Cloud Storage
BigQuery Data Transfer Service per Cloud Storage ti consente di pianificare carichi dati 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 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 necessarie per criptare e decriptare, e che tu abbia l'ID risorsa della chiave Cloud KMS necessaria per usare CMEK. Per informazioni su come CMEK funziona con BigQuery Data Transfer Service, vedi Specificare la chiave di crittografia con i trasferimenti.
Limitazioni
I trasferimenti ricorrenti da Cloud Storage a BigQuery soggetto alle seguenti limitazioni:
- Tutti i file corrispondenti ai pattern definiti da un carattere jolly o dal runtime per il trasferimento devono condividere lo stesso schema definito la tabella di destinazione, altrimenti il trasferimento non andrà a buon fine. Lo schema della tabella cambia tra causa anche la mancata riuscita del trasferimento.
- Poiché gli oggetti Cloud Storage possono essere sottoposti al controllo delle versioni, è importante notare che gli oggetti Cloud Storage archiviati non sono supportate per i trasferimenti BigQuery. Per essere conformi, gli oggetti devono essere attivi trasferito.
- Non mi piace caricamenti individuali di dati da Cloud Storage a BigQuery, per i trasferimenti in corso devi creare la tabella di destinazione prima durante la configurazione del trasferimento. Per i file CSV e JSON, devi anche definire schema della tabella in anticipo. BigQuery Impossibile creare la tabella nell'ambito del processo di trasferimento di dati ricorrente.
- I trasferimenti da Cloud Storage impostano il parametro Write preference su
APPEND
per impostazione predefinita. In questa modalità, un file non modificato può essere caricato solo BigQuery una sola volta. Se la proprietàlast modification time
del file viene aggiornato, il file verrà ricaricato. BigQuery Data Transfer Service non garantisce che tutti i file saranno trasferiti o trasferiti solo una volta se i file di Cloud Storage vengono toccati a metà trasferimento. 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 contenuto nella stessa località (multiregionale) del set di dati.BigQuery non garantisce la coerenza dei dati esterni fonti. Le modifiche ai dati sottostanti durante l'esecuzione di una query possono comportare comportamenti imprevisti.
BigQuery non supporta Controllo delle versioni degli oggetti Cloud Storage. Se includi un numero di generazione nell'URI di Cloud Storage, il job di caricamento non riesce.
A seconda del formato dei dati di origine Cloud Storage, potrebbero essere limitazioni aggiuntive. Per ulteriori informazioni, vedi:
Il bucket Cloud Storage deve trovarsi in una località compatibile con la regione o le regioni del set di dati di destinazione in in BigQuery. Questa operazione è nota come colocation. Visualizza trasferimento Cloud Storage Posizioni dei dati per maggiori dettagli.
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. La l'intervallo predefinito per un bonifico ricorrente è ogni 24 ore.
Autorizzazioni obbligatorie
Quando carichi i dati in BigQuery, devi avere le autorizzazioni necessarie di caricare i dati in tabelle BigQuery nuove o esistenti partizioni di Compute Engine. Se carichi i dati da Cloud Storage, avrai bisogno anche di al bucket che contiene i tuoi dati. Assicurati di avere quanto segue autorizzazioni richieste:
BigQuery: assicurati che la persona o l'account di servizio la creazione del trasferimento le seguenti autorizzazioni in BigQuery:
bigquery.transfers.update
autorizzazioni per creare il trasferimento- Autorizzazioni
bigquery.datasets.get
ebigquery.datasets.update
attive il set di dati di destinazione
Il ruolo IAM predefinito
bigquery.admin
includebigquery.transfers.update
,bigquery.datasets.update
e Autorizzazionibigquery.datasets.get
. Per ulteriori informazioni Per i ruoli IAM in BigQuery Data Transfer Service, consulta Controllo dell'accesso.Cloud Storage: sono necessarie
storage.objects.get
autorizzazioni su al singolo bucket o di livello superiore. Se utilizzi un URI carattere jolly, devi avere anche le autorizzazionistorage.objects.list
. Se desideri eliminare i file di origine dopo ogni trasferimento riuscito, è necessariostorage.objects.delete
autorizzazioni. Ilstorage.objectAdmin
predefinito Ruolo IAM che includa 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 di trasferimento, per Nome visualizzato, inserisci un nome del trasferimento, ad esempio
My Transfer
. Il nome del trasferimento può essere qualsiasi valore che ti consenta di identificare il trasferimento, se necessario per modificarlo in un secondo momento.Nella sezione Opzioni di pianificazione:
Seleziona Frequenza di ripetizione. Se selezioni Ore, Giorni, Settimane o Mesi, devi anche specificare una frequenza. Tu Puoi anche selezionare Personalizzata per specificare una frequenza di ripetizione personalizzata. Se selezioni On demand, questo trasferimento verrà eseguito quando il trasferimento viene attivato manualmente.
Se applicabile, seleziona Inizia ora o Inizia all'ora impostata. e specificare 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 tuoi 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 parametri.
- In URI Cloud Storage, inserisci il valore URI Cloud Storage. Caratteri jolly e parameters sono supportati.
- Per Preferenza di scrittura, scegli:
- APPEND per aggiungere in modo incrementale nuovi dati ai tuoi dati esistenti tabella di destinazione. APPEND è il valore predefinito per Scrittura utente.
- MIRROR per sovrascrivere i dati nella tabella di destinazione durante a ogni esecuzione di trasferimento.
Per ulteriori informazioni su come BigQuery Data Transfer Service importa utilizzando APPEND o MIRROR, vedi 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. Elimina job non riprovare se il primo job l'eliminazione dei 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 quando
che esegue il job. Se il numero di record non validi supera questo
valore, un valore "non valido" viene restituito un errore nel risultato del job,
e il job non va a buon fine. Il valore predefinito è
0
. - (Facoltativo) Per Tipi di targeting decimale, inserisci un
un elenco separato da virgole di possibili tipi di dati SQL che
i valori decimali di origine. Quali dati SQL
il tipo selezionato per la conversione dipende da quanto segue:
condizioni:
- Il tipo di dati selezionato per la conversione sarà il primo tipo di dati dell'elenco seguente che supporta la precisione e la scala dei dati di origine, ordine: NUMERIC, BIGNUMERIC e STRING.
- Se nessuno dei tipi di dati elencati supporta precisione e scala, il tipo di dati che supporta sia selezionata l'opzione più ampia nell'elenco specificato. Se supera l'intervallo supportato durante la lettura dei valori verrà generato un errore.
- Il tipo di dati STRING supporta tutte le funzioni di precisione e scala e i relativi valori.
- Se questo campo viene lasciato vuoto, il tipo di dati verrà il valore predefinito è "NUMERIC,STRING" per ORC e "NUMERIC" della gli altri formati di file.
- Questo campo non può contenere tipi di dati duplicati.
- L'ordine dei tipi di dati elencati in questa viene ignorato.
- In Numero di errori consentiti, inserisci il numero massimo
di record non validi che BigQuery può ignorare quando
che esegue il job. Se il numero di record non validi supera questo
valore, un valore "non valido" viene restituito un errore nel risultato del job,
e il job non va a buon fine. Il valore predefinito è
- In JSON, CSV:
- In Ignora valori sconosciuti, seleziona la casella se vuoi il trasferimento per rilasciare dati che non corrispondono alla destinazione schema della tabella.
- In AVRO:
- In Usa tipi logici avro, seleziona la casella se vuoi
il trasferimento per convertire i tipi logici Avro nei loro
tipi di dati BigQuery corrispondenti. La
Il comportamento predefinito è ignorare l'attributo
logicalType
per la maggior parte dei tipi e utilizza il tipo Avro sottostante .
- In Usa tipi logici avro, seleziona la casella se vuoi
il trasferimento per convertire i tipi logici Avro nei loro
tipi di dati BigQuery corrispondenti. La
Il comportamento predefinito è ignorare l'attributo
In CSV:
- In Delimitatore di campo, inserisci il carattere che separa campi. Il valore predefinito è una virgola.
- Per Carattere, inserisci il carattere utilizzato per
le sezioni di dati delle citazioni in un file CSV. Il valore predefinito è
virgolette doppie (
"
). - In Righe di intestazione da saltare, inserisci il numero di righe di intestazione
nei file sorgente se non vuoi importarli. La
il valore predefinito è
0
. - In Consenti nuove righe tra virgolette, seleziona la casella se vuoi consenti ritorni a capo all'interno dei campi tra virgolette.
- In 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 progetto Google Cloud. Puoi associare un account di servizio a il trasferimento anziché utilizzare le tue credenziali utente. Per maggiori informazioni informazioni sull'uso di account di servizio con i trasferimenti di dati, vedi Utilizzare gli account di servizio.
- Se hai eseguito l'accesso con un'identità federata: per creare un trasferimento è necessario un account di servizio. Se hai firmato con un Account Google, poi l'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. Se attivi questa opzione, , il proprietario della configurazione di trasferimento riceve un'email quando un trasferimento non va a buon fine.
- Per Seleziona un argomento Pub/Sub, scegli l'argomento o fai clic su Crea un argomento. Questa opzione configura l'esecuzione delle notifiche in Pub/Sub per il trasferimento.
(Facoltativo) Nella sezione Opzioni avanzate:
- Se usi le CMEK, seleziona Chiave gestita dal cliente. Un elenco delle CMEK disponibili tra cui scegliere.
Per informazioni sul funzionamento delle CMEK con BigQuery Data Transfer Service, consulta 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 in BigQuery Data Transfer Service, consulta Specificare la chiave di crittografia con i trasferimenti.--service_account_name
: specifica un account di servizio da utilizzare per Autenticazione di trasferimento di Cloud Storage anziché 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 usato il progetto predefinito. - DATA_SOURCE è l'origine dati, ad esempio
google_cloud_storage
. - NAME è il nome visualizzato della configurazione di trasferimento. La Transfer name può essere qualsiasi valore che ti consenta di identificare se devi 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, per
esempio,
projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name
. - PARAMETERS contiene i parametri per il trasferimento creato
configurazione in formato JSON. Ad esempio:
--params='{"param":"param_value"}'
.destination_table_name_template
: il nome della destinazione Tabella BigQuery.data_path_template
: l'URI Cloud Storage che contiene file da trasferire, che può includere un carattere jolly.write_disposition
: determina se i file corrispondenti vengono aggiunti alla sezione con una tabella di destinazione o con mirroring completo. I valori supportati sonoAPPEND
oMIRROR
. Per informazioni su come BigQuery Data Transfer Service aggiunge o esegue il mirroring dei dati nei trasferimenti consulta Importazione dei dati per i trasferimenti di Cloud Storage.file_format
: il formato dei file che vuoi trasferimento. 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
, separato da virgole elenco dei possibili tipi di dati SQL da cui potrebbero essere i valori decimali di origine in cui viene convertito. Se questo campo non viene fornito, il tipo di dati predefinito sarà"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 . Per ulteriori informazioni, vedi il campoignoreUnknownvalues
dettagli nella tabella di riferimento diJobConfigurationLoad
.use_avro_logical_types
: perAVRO
valorifile_format
, impostato suTRUE
per interpretare i tipi logici nei tipi corrispondenti (ad ad esempioTIMESTAMP
), anziché utilizzare solo i relativi tipi non elaborati (ad ad esempioINTEGER
).parquet_enum_as_string
: perPARQUET
valorifile_format
, impostato suTRUE
per dedurre il tipo logicoPARQUET
ENUM
comeSTRING
anziché come il valore predefinito diBYTES
.parquet_enable_list_inference
: perPARQUET
valorifile_format
, impostato aTRUE
per utilizzare l'inferenza dello schema specifica perPARQUET
LIST
tipo logico.reference_file_schema_uri
: un percorso URI di un file di riferimento con lo schema del lettore.field_delimiter
: perCSV
valorifile_format
, un carattere che separa i campi. Il valore predefinito è una virgola.quote
: per i valorifile_format
diCSV
, un carattere utilizzato per le sezioni di dati delle citazioni in un file CSV. Il valore predefinito è una virgoletta doppia ("
).skip_leading_rows
: per i valorifile_format
diCSV
, indica il numero di righe di intestazione iniziali che non si desidera importare. Il valore predefinito è 0.allow_quoted_newlines
: per i valorifile_format
diCSV
, impostato suTRUE
per consentire le nuove righe all'interno dei campi tra virgolette.allow_jagged_rows
: per i valorifile_format
diCSV
, impostato suTRUE
su accettare le righe che mancano delle colonne finali facoltative. Mancanti i valori vengono compilati conNULL
.preserve_ascii_control_characters
: perCSV
valorifile_format
, impostato 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 al primo tentativo l'eliminazione del file di origine non riesce. Il valore predefinito èFALSE
.
- SERVICE_ACCOUNT_NAME è il nome dell'account di servizio utilizzato
di autenticare il trasferimento. L'account di servizio deve
essere di proprietà dello stesso
project_id
usato per creare il trasferimento; devono disporre di tutte le autorizzazioni richieste.
Ad esempio, il comando seguente crea un'istanza di Cloud Storage
trasferimento denominato My Transfer
utilizzando un valore data_path_template
pari a
gs://mybucket/myfile/*.csv
, set di dati di destinazione mydataset
e file_format
CSV
, Questo esempio include valori non predefiniti per i parametri facoltativi
associato a CSV
file_format.
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 nel comando dalla riga di comando.
API
Utilizza la projects.locations.transferConfigs.create
e fornisce un'istanza del metodo TransferConfig
risorsa.
Java
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Java BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Specifica la chiave di crittografia con trasferimenti
Puoi specificare le chiavi di crittografia gestite dal cliente (CMEK) per crittografare 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 CMEK a qualsiasi cache intermedia su disco dei dati importati, il flusso di lavoro di trasferimento dati è conforme a CMEK.
Non puoi aggiornare un trasferimento esistente per aggiungere una CMEK se il trasferimento non è stato eseguito originariamente creato con una CMEK. Ad esempio, non puoi modificare una destinazione che in origine era criptata per impostazione predefinita e ora è crittografata con CMEK. Al contrario, non puoi neanche modificare una tabella di destinazione criptata con CMEK un tipo diverso di crittografia.
Puoi aggiornare una CMEK per un trasferimento se la configurazione del trasferimento era originariamente creato con una crittografia CMEK. Quando aggiorni una CMEK per un trasferimento configurazione, BigQuery Data Transfer Service propaga la CMEK alla destinazione alla successiva esecuzione del trasferimento, in cui BigQuery Data Transfer Service sostituisce qualsiasi CMEK obsoleta con la nuova 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 di progetto con un trasferimento, BigQuery Data Transfer Service usa la chiave predefinita del progetto come chiave predefinita per tutti i nuovi trasferimenti configurazioni.
Attivare manualmente un trasferimento
Oltre ai trasferimenti pianificati automaticamente da Cloud Storage, può attivare manualmente un trasferimento per caricare file di dati aggiuntivi.
Se la configurazione di trasferimento è runtime con parametri, devi specificare un intervallo di date per le quali i trasferimenti aggiuntivi saranno a iniziare.
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 il runtime configurazioni di trasferimento parametrizzate).
Se hai fatto clic su Esegui trasferimento ora, seleziona Esegui trasferimento una tantum. oppure 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. oppure 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 fornisce il flag --transfer_run
. Puoi utilizzare --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 contenere un offset di fuso orario valido. Ad esempio:2017-08-19T12:11:35.00Z
2017-05-25T00:00:00+00:00
RUN_TIME è un timestamp che specifica l'orario di pianificazione durante l'esecuzione del trasferimento dei dati. Se vuoi eseguire un trasferimento una tantum per l'attuale nel tempo, puoi usare il flag
--run_time
.RESOURCE_NAME è il nome della risorsa del trasferimento (chiamato anche come configurazione di trasferimento), ad esempio
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7
. Se non conosci la risorsa del trasferimento esegui il comandobq ls --transfer_config --transfer_location=LOCATION
per trovare il nome della risorsa.
API
Utilizza la projects.locations.transferConfigs.startManualRuns
e fornire la risorsa di configurazione del trasferimento utilizzando il metodo parent
.
Passaggi successivi
- Scopri di più sui parametri di runtime nei trasferimenti di Cloud Storage.
- Scopri di più su BigQuery Data Transfer Service.