Programmazione delle query

Questa pagina descrive come pianificare le query ricorrenti in BigQuery.

Puoi pianificare l'esecuzione delle query su base ricorrente. Le query pianificate devono essere escritas in GoogleSQL, che può includere istruzioni Data Definition Language (DDL) e Data Manipulation Language (DML). Puoi organizzare i risultati della query per data e ora parametrizzando la stringa di query e la tabella di destinazione.

Quando crei o aggiorni la pianificazione di una query, l'ora pianificata della query viene convertita dall'ora locale in UTC. Il fuso orario UTC non è interessato dall'ora legale.

Prima di iniziare

• Le query pianificate utilizzano funzionalità di BigQuery Data Transfer Service. Verifica di aver completato tutte le azioni richieste in Attivare BigQuery Data Transfer Service.
• Concedi i ruoli IAM (Identity and Access Management) che forniscono agli utenti le autorizzazioni necessarie per eseguire ogni attività in questo documento.
• 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 tu disponga dell'ID risorsa della chiave Cloud KMS necessario per utilizzare la chiave CMEK. Per informazioni su come funzionano le chiavi CMEK con BigQuery Data Transfer Service, consulta Specificare la chiave di crittografia con le query pianificate.

Autorizzazioni obbligatorie

Per pianificare una query, devi disporre delle seguenti autorizzazioni IAM:

• Per creare il trasferimento, devi disporre delle autorizzazioni bigquery.transfers.update e bigquery.datasets.get oppure delle autorizzazioni bigquery.jobs.create, bigquery.transfers.get e bigquery.datasets.get.

  Nota: se utilizzi la console Google Cloud o lo strumento a riga di comando bq per pianificare una query, devi disporre dell'autorizzazione bigquery.transfers.get.

• Per eseguire una query pianificata, devi disporre di:

  • Autorizzazioni bigquery.datasets.get sul set di dati di destinazione
  • bigquery.jobs.create

Per modificare o eliminare una query pianificata, devi disporre di una delle seguenti autorizzazioni IAM:

• bigquery.transfers.update
• bigquery.jobs.create e la proprietà della query pianificata

Il ruolo IAM predefinito roles/bigquery.admin include le autorizzazioni necessarie per pianificare o modificare una query.

Per saperne di più sui ruoli IAM in BigQuery, consulta Ruoli e autorizzazioni predefiniti.

Per creare o aggiornare le query pianificate eseguite da un account di servizio, devi avere accesso a quell'account di servizio. Per ulteriori informazioni sulla concessione del ruolo dell'account di servizio agli utenti, consulta Ruolo Utente account di servizio. Per selezionare un account di servizio nell'interfaccia utente delle query pianificate della console Google Cloud, devi disporre delle seguenti autorizzazioni IAM:

• iam.serviceAccounts.list

Nota: se utilizzi lo strumento a riga di comando bq, utilizza il parametro --service_account_name anziché autenticarti come account di servizio.

Opzioni di configurazione

Stringa di query

La stringa di query deve essere valida e scritta in GoogleSQL. Ogni esecuzione di una query pianificata può ricevere i seguenti parametri di query.

Per testare manualmente una stringa di query con i parametri @run_time e @run_date prima di pianificare una query, utilizza lo strumento a riga di comando bq.

Parametri disponibili

Parametro	Tipo GoogleSQL	Valore
@run_time	TIMESTAMP	Rappresentate nell'ora UTC. Per le query pianificate regolarmente, run_time rappresenta l'ora prevista di esecuzione. Ad esempio, se la query pianificata è impostata su "ogni 24 ore", la differenza run_time tra due query consecutive è esattamente di 24 ore, anche se il tempo di esecuzione effettivo potrebbe variare leggermente.
@run_date	DATE	Rappresenta una data di calendario logica.

Esempio

Il parametro @run_time fa parte della stringa di query in questo esempio, che esegue una query su un set di dati pubblico denominato hacker_news.stories.

SELECT @run_time AS time,
  title,
  author,
  text
FROM `bigquery-public-data.hacker_news.stories`
LIMIT
  1000

Tabella di destinazione

Se la tabella di destinazione per i risultati non esiste quando configuri la query pianificata, BigQuery tenta di crearla per te.

Se utilizzi una query DDL o DML, nella console Google Cloud scegli la regione o la Località di elaborazione. La posizione di elaborazione è obbligatoria per le query DDL o DML che creano la tabella di destinazione.

Se la tabella di destinazione esiste e utilizzi la WRITE_APPEND preferenza di scrittura, BigQuery aggiunge i dati alla tabella di destinazione e tenta di mappare lo schema. BigQuery consente automaticamente l'aggiunta e il riordinamento dei campi e supporta i campi facoltativi mancanti. Se lo schema della tabella cambia così tanto tra un'esecuzione e l'altra che BigQuery non riesce a elaborare le modifiche automaticamente, la query pianificata non va a buon fine.

Le query possono fare riferimento a tabelle di progetti e set di dati diversi. Quando configuri la query pianificata, non è necessario includere il set di dati di destinazione nel nome della tabella. Specifica il set di dati di destinazione separatamente.

Il set di dati e la tabella di destinazione per una query pianificata devono trovarsi nello stesso progetto della query pianificata.

Preferenza di scrittura

La preferenza di scrittura selezionata determina la modalità di scrittura dei risultati della query in una tabella di destinazione esistente.

• WRITE_TRUNCATE: se la tabella esiste, BigQuery sovrascrive i dati della tabella.
• WRITE_APPEND: se la tabella esiste, BigQuery aggiunge i dati alla tabella.

Se utilizzi una query DDL o DML, non puoi utilizzare l'opzione di preferenza di scrittura.

La creazione, il troncamento o l'accodamento di una tabella di destinazione avviene solo se BigQuery è in grado di completare correttamente la query. Le azioni di creazione, troncamento o accodamento vengono eseguite come un unico aggiornamento atomico al termine del job.

Clustering

Le query pianificate possono creare raggruppamenti solo nelle nuove tabelle, quando la tabella viene creata con un'istruzione CREATE TABLE AS SELECT DDL. Consulta Creazione di una tabella in cluster da un risultato di query nella pagina Utilizzo di istruzioni del linguaggio di definizione dei dati.

Opzioni di partizionamento

Le query pianificate possono creare tabelle di destinazione partizionate o non partizionate. La suddivisione in parti è disponibile nella console Google Cloud, nello strumento a riga di comando bq e nei metodi di configurazione dell'API. Se utilizzi una query DDL o DML con partizionamento, lascia vuoto il campo Partizionamento della tabella di destinazione.

In BigQuery puoi utilizzare i seguenti tipi di partizionamento delle tabelle:

• Partizionamento in base a intervalli di interi: tabelle partizionate in base a intervalli di valori in una colonna INTEGER specifica.
• Partizionamento delle colonne in base alle unità di tempo: tabelle partizionate in base a una colonna TIMESTAMP, DATE o DATETIME.
• Partizione per data di importazione: tabelle partizionate per data di importazione. BigQuery assegna automaticamente le righe alle partizioni in base al momento in cui BigQuery acquisisce i dati.

Per creare una tabella partizionata utilizzando una query pianificata nella console Google Cloud, utilizza le seguenti opzioni:

• Per utilizzare la suddivisione in intervalli di interi, lascia vuoto il campo di suddivisione della tabella di destinazione.

• Per utilizzare la partizione delle colonne in base alle unità di tempo, specifica il nome della colonna nel campo di partizione della tabella di destinazione quando configuri una query pianificata.

• Per utilizzare la partizione in base alla data di importazione, lascia vuoto il campo di partizionamento della tabella di destinazione e indica la data di partizione nel nome della tabella di destinazione. Ad esempio, mytable${run_date}. Per ulteriori informazioni, consulta la sezione Sintassi dei modelli di parametro.

Parametri disponibili

Quando configuri la query pianificata, puoi specificare come vuoi partizionare la tabella di destinazione con i parametri di runtime.

Parametro	Tipo di modello	Valore
run_time	Timestamp formattato	Nell'ora UTC, in base alla programmazione. Per le query pianificate regolarmente, run_time rappresenta l'ora prevista di esecuzione. Ad esempio, se la query pianificata è impostata su "ogni 24 ore", la run_timedifferenza tra due query consecutive è esattamente di 24 ore, anche se il tempo di esecuzione effettivo può variare leggermente. Consulta TransferRun.runTime.
run_date	Stringa di data	La data del parametro run_time nel seguente formato: %Y-%m-%d; ad esempio, 2018-01-01. Questo formato è compatibile con le tabelle partizionate per data di importazione.

Sistema di creazione di modelli

Le query pianificate supportano i parametri di runtime nel nome della tabella di destinazione con una sintassi di creazione di modelli.

Sintassi dei modelli di parametri

La sintassi dei modelli supporta la creazione di modelli di stringhe di base e lo sfasamento temporale. I parametri vengono indicati nei seguenti formati:

• {run_date}
• {run_time[+\-offset]|"time_format"}

Parametro	Purpose
run_date	Questo parametro viene sostituito dalla data nel formato YYYYMMDD.
run_time	Questo parametro supporta le seguenti proprietà: offset Offset di tempo espresso in ore (h), minuti (m) e secondi (s) in quest'ordine. I giorni (d) non sono supportati. Sono consentiti i decimali, ad esempio: 1.5h. time_format Una stringa di formattazione. I parametri di formattazione più comuni sono anni (%Y), mesi (%m) e giorni (%d). Per le tabelle partizionate, AAAAMMGG è il suffisso obbligatorio, equivalente a "%Y%m%d". Scopri di più sulla formattazione degli elementi data/ora.

Note sull'utilizzo:

• Non sono consentiti spazi tra run_time, offset e il formato dell'ora.
• Per includere le parentesi graffe nella stringa, puoi eseguire l'escape come '\{' and '\}'.
• Per includere virgolette letterali o una barra verticale in time_format, ad esempio "YYYY|MM|DD", puoi eseguire la loro sfuggita nella stringa di formato come: '\"' o '\|'.

Esempi di creazione di modelli di parametri

Questi esempi mostrano come specificare i nomi delle tabelle di destinazione con formati di data diversi e compensare il tempo di esecuzione.

run_time (UTC)	Parametro basato su modello	Nome della tabella di destinazione dell'output
2018-02-15 00:00:00	mytable	mytable
2018-02-15 00:00:00	mytable_{run_time|"%Y%m%d"}	mytable_20180215
2018-02-15 00:00:00	mytable_{run_time+25h|"%Y%m%d"}	mytable_20180216
2018-02-15 00:00:00	mytable_{run_time-1h|"%Y%m%d"}	mytable_20180214
2018-02-15 00:00:00	mytable_{run_time+1.5h|"%Y%m%d%H"} o mytable_{run_time+90m|"%Y%m%d%H"}	mytable_2018021501
2018-02-15 00:00:00	{run_time+97s|"%Y%m%d"}_mytable_{run_time+97s|"%H%M%S"}	20180215_mytable_000137

utilizza un service account

Puoi configurare una query pianificata per l'autenticazione come account di servizio. Un account di servizio è un Account Google associato al tuo progetto Google Cloud. L'account di servizio può eseguire job, come query pianificate o pipeline di elaborazione collettiva, con le proprie credenziali di servizio anziché con le credenziali di un utente finale.

Scopri di più sull'autenticazione con gli account di servizio in Introduzione all'autenticazione.

• Puoi configurare la query pianificata con un account di servizio. Se hai eseguito l'accesso con un'identità federata, è 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.

• Puoi aggiornare una query pianificata esistente con le credenziali di un account di servizio con lo strumento a riga di comando bq o la console Google Cloud. Per ulteriori informazioni, consulta Aggiornare le credenziali delle query pianificate.

Specifica la chiave di crittografia con le query pianificate

Puoi specificare le chiavi di crittografia gestite dal cliente (CMEK) per criptare i dati per un'esecuzione del trasferimento. Puoi utilizzare un CMEK per supportare i trasferimenti da query pianificate.

Quando specifichi una CMEK con un trasferimento, BigQuery Data Transfer Service applica la CMEK a qualsiasi cache intermedia su disco dei dati importati in modo che l'intero flusso di lavoro di trasferimento dei dati sia conforme alla CMEK.

Non puoi aggiornare un trasferimento esistente per aggiungere un CMEK se il trasferimento non è stato creato inizialmente con un CMEK. Ad esempio, non puoi modificare una tabella di destinazione inizialmente criptata per impostazione predefinita in modo che venga criptata con CMEK. Al contrario, non puoi nemmeno modificare una tabella di destinazione con crittografia CMEK per avere un tipo di crittografia diverso.

Puoi aggiornare un CMEK per un trasferimento se la configurazione del trasferimento è stata creata inizialmente con una crittografia CMEK. Quando aggiorni un CMEK per una configurazione di trasferimento, BigQuery Data Transfer Service lo propaga alle tabelle di destinazione alla successiva esecuzione del trasferimento, dove sostituisce eventuali CMEK obsoleti con il nuovo CMEK durante l'esecuzione del trasferimento. Per ulteriori informazioni, consulta Aggiornare un trasferimento.

Puoi anche utilizzare le chiavi predefinite del progetto. Quando specifichi una chiave predefinita del progetto con un trasferimento, BigQuery Data Transfer Service la utilizza come chiave predefinita per tutte le nuove configurazioni di trasferimento.

Configurare le query pianificate

Per una descrizione della sintassi della pianificazione, consulta Formattazione della pianificazione. Per informazioni dettagliate sulla sintassi della pianificazione, consulta Risorsa: TransferConfig.

Console

1. Apri la pagina BigQuery nella console Google Cloud.

   Vai a BigQuery

2. Esegui la query che ti interessa. Quando i risultati ti soddisfano, fai clic su Pianifica.

   

3. Le opzioni per le query pianificate si aprono nel riquadro Nuova query pianificata.

   

4. Nel riquadro Nuova query programmata:

   • In Nome per la query pianificata, inserisci un nome, ad esempio My scheduled query. Il nome della query pianificata può essere qualsiasi valore che puoi identificare in un secondo momento se devi modificare la query.

   • (Facoltativo) Per impostazione predefinita, l'esecuzione della query è pianificata su base giornaliera. Puoi modificare la programmazione predefinita selezionando un'opzione dal menu a discesa Ripeti:

     • Per specificare una frequenza personalizzata, seleziona Personalizzata, quindi inserisci una specifica di tempo simile a Cron nel campo Pianificazione personalizzata, ad esempio every mon 23:30 o every 6 hours. Per informazioni dettagliate sulle pianificazioni valide, inclusi gli intervalli personalizzati, consulta il campo schedule in Risorsa: TransferConfig.

       

       Nota: la durata minima tra le query pianificate è di 5 minuti.

     • Per modificare l'ora di inizio, seleziona l'opzione Inizia all'ora impostata e inserisci la data e l'ora di inizio che preferisci.

       Nota: se l'ora di inizio specificata è successiva a quella indicata nella pianificazione, la prima esecuzione della query avverrà nell'iterazione successiva del ciclo. Ad esempio, una query creata il giorno 2022-06-05 23:50 con pianificazione daily 00:00 e ora di inizio 2022-06-06 10:00 non verrà eseguita fino al giorno 2022-06-07 00:00.

     • Per specificare un'ora di fine, seleziona l'opzione Pianifica l'ora di fine, inserisci la data e l'ora di fine che preferisci.

     • Per salvare la query senza una pianificazione, in modo da poterla eseguire su richiesta in un secondo momento, seleziona On demand nel menu Ripeti.

5. Per una query GoogleSQL SELECT, seleziona l'opzione Imposta una tabella di destinazione per i risultati della query e fornisci le seguenti informazioni sul set di dati di destinazione.

   • Per Nome set di dati, scegli il set di dati di destinazione appropriato.
   • In Nome tabella, inserisci il nome della tabella di destinazione.

   • Per Preferenza di scrittura per tabella di destinazione, scegli Aggiungi alla tabella per aggiungere i dati alla tabella o Sovrapponi tabella per sovrascrivere la tabella di destinazione.

     

6. Scegli il Tipo di località.

   • Se hai attivato la tabella di destinazione per i risultati della query, puoi selezionare Selezione automatica della località per selezionare automaticamente la località in cui si trova la tabella di destinazione.

   • In caso contrario, scegli la posizione in cui si trovano i dati oggetto della query.

7. Opzioni avanzate:

   • (Facoltativo) CMEK Se utilizzi chiavi di crittografia gestite dal cliente, puoi selezionare Chiave gestita dal cliente in Opzioni avanzate. Viene visualizzato un elenco di CMEK disponibili tra cui scegliere. Per informazioni su come le chiavi di crittografia gestite dal cliente (CMEK) funzionano con BigQuery Data Transfer Service, consulta Specificare la chiave di crittografia con le query pianificate.

   • Autenticazione come account di servizio Se hai uno o più account di servizio associati al tuo progetto Google Cloud, puoi associare un account di servizio alla query pianificata invece di utilizzare le credenziali utente. In Credenziale per query programmate, fai clic sul menu per visualizzare un elenco dei tuoi account servizio disponibili. Un account di servizio è obbligatorio se hai eseguito l'accesso come identità federata.

     

8. Configurazioni aggiuntive:

   • (Facoltativo) Seleziona Invia notifiche via email per consentire le notifiche via email relative agli errori di esecuzione dei trasferimenti.

   • (Facoltativo) In Argomento Pub/Sub, inserisci il nome dell'argomento Pub/Sub, ad esempio: projects/myproject/topics/mytopic.

     

9. Fai clic su Salva.

bq

Esistono due modi per pianificare una query utilizzando lo strumento a riga di comando bq. L'opzione 2 ti consente di pianificare la query con più opzioni.

Opzione 1: utilizza il comando bq query.

Per creare una query pianificata, aggiungi le opzioni destination_table (o target_dataset), --schedule e --display_name al comando bq query.

bq query \
--display_name=name \
--destination_table=table \
--schedule=interval

Sostituisci quanto segue:

• name. Il nome visualizzato della query pianificata. Il nome visualizzato può essere qualsiasi valore che puoi identificare in un secondo momento se devi modificare la query.
• table. La tabella di destinazione per i risultati della query.
  • --target_dataset è un modo alternativo per assegnare un nome al set di dati di destinazione per i risultati della query, se utilizzato con query DDL e DML.
  • Utilizza --destination_table o --target_dataset, ma non entrambi.
• interval. Se utilizzato con bq query, trasforma una query in una query programmata ricorrente. È obbligatoria una pianificazione della frequenza con cui deve essere eseguita la query. Per informazioni dettagliate sulle pianificazioni valide, inclusi gli intervalli personalizzati, consulta il campo schedule in Risorsa: TransferConfig. Esempi:
  • --schedule='every 24 hours'
  • --schedule='every 3 hours'
  • --schedule='every monday 09:00'
  • --schedule='1st sunday of sep,oct,nov 00:00'

Flag facoltativi:

• --project_id è l'ID progetto. Se --project_id non è specificato, viene utilizzato il progetto predefinito.

• --replace tronca la tabella di destinazione e scrive nuovi risultati con ogni esecuzione della query pianificata.

• --append_table aggiunge i risultati alla tabella di destinazione.

• Per le query DDL e DML, puoi anche fornire il flag --location per specificare una determinata regione per l'elaborazione. Se --location non è specificato, viene utilizzata la località Google Cloud più vicina.

Se non vengono specificati sia `--replace` sia `--append_table` quando viene pianificata la query, non viene impostata alcuna preferenza di scrittura. A seconda della query, potrebbe verificarsi un errore nelle esecuzioni pianificate successive.

Ad esempio, il seguente comando crea una query pianificata denominata My Scheduled Query utilizzando la query semplice SELECT 1 from mydataset.test. La tabella di destinazione è mytable nel set di dati mydataset. La query pianificata viene creata nel progetto predefinito:

    bq query \
    --use_legacy_sql=false \
    --destination_table=mydataset.mytable \
    --display_name='My Scheduled Query' \
    --schedule='every 24 hours' \
    --replace=true \
    'SELECT
      1
    FROM
      mydataset.test'

Opzione 2: utilizza il comando bq mk.

Le query pianificate sono un tipo di trasferimento. Per pianificare una query, puoi utilizzare lo strumento a riga di comando bq per creare una configurazione di trasferimento.

Le query devono essere nel dialetto StandardSQL per essere pianificate.

Inserisci il comando bq mk e fornisci i seguenti flag obbligatori:

• --transfer_config
• --data_source
• --target_dataset (facoltativo per le query DDL e DML)
• --display_name
• --params

Flag facoltativi:

• --project_id è l'ID progetto. Se --project_id non è specificato, viene utilizzato il progetto predefinito.

• --schedule è la frequenza con cui vuoi eseguire la query. Se --schedule non viene specificato, il valore predefinito è "ogni 24 ore" in base all'ora di creazione.

• Per le query DDL e DML, puoi anche fornire il flag --location per specificare una determinata regione per l'elaborazione. Se --location non è specificato, viene utilizzata la località Google Cloud più vicina.

• --service_account_name è per l'autenticazione della query pianificata con un account di servizio anziché con il tuo account utente individuale.

• --destination_kms_key specifica l'ID risorsa chiave per la chiave se utilizzi una chiave di crittografia gestita dal cliente (CMEK) per questo trasferimento. Per informazioni su come funzionano le chiavi CMEK con BigQuery Data Transfer Service, consulta Specificare la chiave di crittografia con le query pianificate.

bq mk \
--transfer_config \
--target_dataset=dataset \
--display_name=name \
--params='parameters' \
--data_source=data_source

Sostituisci quanto segue:

• dataset. Il set di dati di destinazione per la configurazione del trasferimento.
  • Questo parametro è facoltativo per le query DDL e DML. È obbligatorio per tutte le altre query.
• name. Il nome visualizzato per la configurazione del trasferimento. Il nome visualizzato può essere qualsiasi valore che puoi identificare in un secondo momento se devi modificare la query.
• parameters. Contiene i parametri per la configurazione del trasferimento creata in formato JSON. Ad esempio: --params='{"param":"param_value"}'.
  • Per una query pianificata, devi fornire il parametro query.
  • Il parametro destination_table_name_template è il nome della tabella di destinazione.
    • Questo parametro è facoltativo per le query DDL e DML. È obbligatorio per tutte le altre query.
  • Per il parametro write_disposition, puoi scegliere WRITE_TRUNCATE per troncare (sovrascrivere) la tabella di destinazione o WRITE_APPEND per accodare i risultati della query alla tabella di destinazione.
    • Questo parametro è facoltativo per le query DDL e DML. È obbligatorio per tutte le altre query.
• data_source. L'origine dati: scheduled_query.
• (Facoltativo) Il flag --service_account_name serve per l'autenticazione con un account di servizio anziché con un account utente individuale.
• Facoltativo: --destination_kms_key specifica l'ID risorsa chiave per la chiave Cloud KMS, ad esempio projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name.

Nota: per scrivere i risultati in una tabella partizionata per data di importazione, consulta le istruzioni nella sezione Tabella di destinazione. Una query pianificata non va a buon fine se crei una configurazione di trasferimento con il parametro destination_table_name_template impostato su una tabella partizionata in base al momento dell'importazione e fornisci anche un errore se imposti il parametro partitioning_field su una tabella partizionata in base al momento dell'importazione.

Nota: non puoi configurare le notifiche utilizzando lo strumento a riga di comando.

Ad esempio, il seguente comando crea una configurazione di trasferimento delle query programmate denominata My Scheduled Query utilizzando la semplice query SELECT 1 from mydataset.test. La tabella di destinazione mytable viene troncata per ogni scrittura e il set di dati di destinazione è mydataset. La query pianificata viene creata nel progetto predefinito e si autentica come account di servizio:

bq mk \
--transfer_config \
--target_dataset=mydataset \
--display_name='My Scheduled Query' \
--params='{"query":"SELECT 1 from mydataset.test","destination_table_name_template":"mytable","write_disposition":"WRITE_TRUNCATE"}' \
--data_source=scheduled_query \
--service_account_name=[e-mail]

La prima volta che esegui il comando, ricevi 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 nel messaggio 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

Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create a scheduled query
public class CreateScheduledQuery {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    final String datasetId = "MY_DATASET_ID";
    final String query =
        "SELECT CURRENT_TIMESTAMP() as current_time, @run_time as intended_run_time, "
            + "@run_date as intended_run_date, 17 as some_integer";
    Map<String, Value> params = new HashMap<>();
    params.put("query", Value.newBuilder().setStringValue(query).build());
    params.put(
        "destination_table_name_template",
        Value.newBuilder().setStringValue("my_destination_table_{run_date}").build());
    params.put("write_disposition", Value.newBuilder().setStringValue("WRITE_TRUNCATE").build());
    params.put("partitioning_field", Value.newBuilder().build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Scheduled Query Name")
            .setDataSourceId("scheduled_query")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createScheduledQuery(projectId, transferConfig);
  }

  public static void createScheduledQuery(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = dataTransferServiceClient.createTransferConfig(request);
      System.out.println("\nScheduled query created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("\nScheduled query was not created." + ex.toString());
    }
  }
}

Python

Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

# The project where the query job runs is the same as the project
# containing the destination dataset.
project_id = "your-project-id"
dataset_id = "your_dataset_id"

# This service account will be used to execute the scheduled queries. Omit
# this request parameter to run the query as the user with the credentials
# associated with this client.
service_account_name = "[e-mail]"

# Use standard SQL syntax for the query.
query_string = """
SELECT
  CURRENT_TIMESTAMP() as current_time,
  @run_time as intended_run_time,
  @run_date as intended_run_date,
  17 as some_integer
"""

parent = transfer_client.common_project_path(project_id)

transfer_config = bigquery_datatransfer.TransferConfig(
    destination_dataset_id=dataset_id,
    display_name="Your Scheduled Query Name",
    data_source_id="scheduled_query",
    params={
        "query": query_string,
        "destination_table_name_template": "your_table_{run_date}",
        "write_disposition": "WRITE_TRUNCATE",
        "partitioning_field": "",
    },
    schedule="every 24 hours",
)

transfer_config = transfer_client.create_transfer_config(
    bigquery_datatransfer.CreateTransferConfigRequest(
        parent=parent,
        transfer_config=transfer_config,
        service_account_name=service_account_name,
    )
)

print("Created scheduled query '{}'".format(transfer_config.name))

Configurare query pianificate con un account di servizio

Java

Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create a scheduled query with service account
public class CreateScheduledQueryWithServiceAccount {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    final String datasetId = "MY_DATASET_ID";
    final String serviceAccount = "MY_SERVICE_ACCOUNT";
    final String query =
        "SELECT CURRENT_TIMESTAMP() as current_time, @run_time as intended_run_time, "
            + "@run_date as intended_run_date, 17 as some_integer";
    Map<String, Value> params = new HashMap<>();
    params.put("query", Value.newBuilder().setStringValue(query).build());
    params.put(
        "destination_table_name_template",
        Value.newBuilder().setStringValue("my_destination_table_{run_date}").build());
    params.put("write_disposition", Value.newBuilder().setStringValue("WRITE_TRUNCATE").build());
    params.put("partitioning_field", Value.newBuilder().build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Scheduled Query Name")
            .setDataSourceId("scheduled_query")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createScheduledQueryWithServiceAccount(projectId, transferConfig, serviceAccount);
  }

  public static void createScheduledQueryWithServiceAccount(
      String projectId, TransferConfig transferConfig, String serviceAccount) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .setServiceAccountName(serviceAccount)
              .build();
      TransferConfig config = dataTransferServiceClient.createTransferConfig(request);
      System.out.println(
          "\nScheduled query with service account created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("\nScheduled query with service account was not created." + ex.toString());
    }
  }
}

Python

Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

# The project where the query job runs is the same as the project
# containing the destination dataset.
project_id = "your-project-id"
dataset_id = "your_dataset_id"

# This service account will be used to execute the scheduled queries. Omit
# this request parameter to run the query as the user with the credentials
# associated with this client.
service_account_name = "[e-mail]"

# Use standard SQL syntax for the query.
query_string = """
SELECT
  CURRENT_TIMESTAMP() as current_time,
  @run_time as intended_run_time,
  @run_date as intended_run_date,
  17 as some_integer
"""

parent = transfer_client.common_project_path(project_id)

transfer_config = bigquery_datatransfer.TransferConfig(
    destination_dataset_id=dataset_id,
    display_name="Your Scheduled Query Name",
    data_source_id="scheduled_query",
    params={
        "query": query_string,
        "destination_table_name_template": "your_table_{run_date}",
        "write_disposition": "WRITE_TRUNCATE",
        "partitioning_field": "",
    },
    schedule="every 24 hours",
)

transfer_config = transfer_client.create_transfer_config(
    bigquery_datatransfer.CreateTransferConfigRequest(
        parent=parent,
        transfer_config=transfer_config,
        service_account_name=service_account_name,
    )
)

print("Created scheduled query '{}'".format(transfer_config.name))

Visualizza lo stato delle query pianificate

Console

Per visualizzare lo stato delle query pianificate, fai clic su Query pianificate nel riquadro di navigazione. Aggiorna la pagina per visualizzare lo stato aggiornato delle query pianificate. Fai clic su una query pianificata per visualizzarne ulteriori dettagli.

bq

Le query pianificate sono un tipo di trasferimento. Per visualizzare i dettagli di una query pianificata, puoi prima utilizzare lo strumento a riga di comando bq per elencare le configurazioni di trasferimento.

Inserisci il comando bq ls e specifica il flag di trasferimento --transfer_config. Sono obbligatori anche i seguenti flag:

• --transfer_location

Ad esempio:

bq ls \
--transfer_config \
--transfer_location=us

Per visualizzare i dettagli di una singola query pianificata, inserisci il comando bq show e fornisci il valore transfer_path per la configurazione della query/del trasferimento pianificato.

Ad esempio:

bq show \
--transfer_config \
projects/862514376110/locations/us/transferConfigs/5dd12f26-0000-262f-bc38-089e0820fe38

API

Utilizza il metodo projects.locations.transferConfigs.list e fornisci un'istanza della risorsa TransferConfig.

Java

Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ListTransferConfigsRequest;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import java.io.IOException;

// Sample to get list of transfer config
public class ListTransferConfigs {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    listTransferConfigs(projectId);
  }

  public static void listTransferConfigs(String projectId) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      ListTransferConfigsRequest request =
          ListTransferConfigsRequest.newBuilder().setParent(parent.toString()).build();
      dataTransferServiceClient
          .listTransferConfigs(request)
          .iterateAll()
          .forEach(config -> System.out.print("Success! Config ID :" + config.getName() + "\n"));
    } catch (ApiException ex) {
      System.out.println("Config list not found due to error." + ex.toString());
    }
  }
}

Python

Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

project_id = "my-project"
parent = transfer_client.common_project_path(project_id)

configs = transfer_client.list_transfer_configs(parent=parent)
print("Got the following configs:")
for config in configs:
    print(f"\tID: {config.name}, Schedule: {config.schedule}")

Aggiornare le query pianificate

Console

Per aggiornare una query pianificata:

1. Nel riquadro di navigazione, fai clic su Query pianificate.
2. Nell'elenco delle query pianificate, fai clic sul nome della query da modificare.
3. Nella pagina Dettagli della query pianificata che si apre, fai clic su Modifica.
4. (Facoltativo) Modifica il testo della query nel riquadro di modifica della query.
5. Fai clic su Pianifica query e poi seleziona Aggiorna query pianificata.
6. (Facoltativo) Modifica le altre opzioni di pianificazione per la query.
7. Fai clic su Aggiorna.

bq

Le query pianificate sono un tipo di trasferimento. Per aggiornare la query pianificata, puoi utilizzare lo strumento a riga di comando bq per creare una configurazione di trasferimento.

Inserisci il comando bq update con il flag --transfer_config obbligatorio.

Flag facoltativi:

• --project_id è l'ID progetto. Se --project_id non è specificato, viene utilizzato il progetto predefinito.

• --schedule è la frequenza con cui vuoi eseguire la query. Se --schedule non viene specificato, il valore predefinito è "ogni 24 ore" in base all'ora di creazione.

• --service_account_name ha effetto solo se è impostato anche --update_credentials. Per ulteriori informazioni, consulta Aggiornare le credenziali delle query pianificate.

• --target_dataset (facoltativo per le query DDL e DML) è un modo alternativo per assegnare un nome al set di dati di destinazione per i risultati della query, se utilizzato con le query DDL e DML.

• --display_name è il nome della query pianificata.

• --params i parametri per la configurazione del trasferimento creata in formato JSON. Ad esempio: --params='{"param":"param_value"}'.

• --destination_kms_key specifica l'ID risorsa chiave per la chiave Cloud KMS se utilizzi una chiave di crittografia gestita dal cliente (CMEK) per questo trasferimento. Per informazioni su come le chiavi di crittografia gestite dal cliente (CMEK) funzionano con BigQuery Data Transfer Service, consulta Specificare la chiave di crittografia con le query pianificate.

bq update \
--target_dataset=dataset \
--display_name=name \
--params='parameters'
--transfer_config \
RESOURCE_NAME

Sostituisci quanto segue:

• dataset. Il set di dati di destinazione per la configurazione del trasferimento. Questo parametro è facoltativo per le query DDL e DML. È obbligatorio per tutte le altre query.
• name. Il nome visualizzato per la configurazione del trasferimento. Il nome visualizzato può essere qualsiasi valore che puoi identificare in un secondo momento se devi modificare la query.
• parameters. Contiene i parametri per la configurazione del trasferimento creata in formato JSON. Ad esempio: --params='{"param":"param_value"}'.
  • Per una query pianificata, devi fornire il parametro query.
  • Il parametro destination_table_name_template è il nome della tabella di destinazione. Questo parametro è facoltativo per le query DDL e DML. È obbligatorio per tutte le altre query.
  • Per il parametro write_disposition, puoi scegliere WRITE_TRUNCATE per troncare (sovrascrivere) la tabella di destinazione o WRITE_APPEND per accodare i risultati della query alla tabella di destinazione. Questo parametro è facoltativo per le query DDL e DML. È obbligatorio per tutte le altre query.
• Facoltativo: --destination_kms_key specifica l'ID risorsa chiave per la chiave Cloud KMS, ad esempio projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name.
• RESOURCE_NAME: il nome della risorsa del trasferimento (chiamato anche configurazione di trasferimento). Se non conosci il nome della risorsa del trasferimento, individualo con: bq ls --transfer_config --transfer_location=location.

Nota: per scrivere i risultati in una tabella partizionata per data di importazione, consulta le istruzioni nella sezione Tabella di destinazione. Una query pianificata non va a buon fine se crei una configurazione di trasferimento con il parametro destination_table_name_template impostato su una tabella partizionata in base al momento dell'importazione e fornisci anche un errore se imposti il parametro partitioning_field su una tabella partizionata in base al momento dell'importazione.

Nota: non puoi configurare le notifiche utilizzando lo strumento a riga di comando.

Ad esempio, il seguente comando aggiorna una configurazione di trasferimento delle query pianificate denominata My Scheduled Query utilizzando la semplice query SELECT 1 from mydataset.test. La tabella di destinazione mytable viene troncata per ogni scrittura e il set di dati di destinazione è mydataset:

bq update \
--target_dataset=mydataset \
--display_name='My Scheduled Query' \
--params='{"query":"SELECT 1 from mydataset.test","destination_table_name_template":"mytable","write_disposition":"WRITE_TRUNCATE"}'
--transfer_config \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

API

Utilizza il metodo projects.transferConfigs.patch e fornisci il nome della risorsa del trasferimento utilizzando il parametro transferConfig.name. Se non conosci il nome della risorsa del trasferimento, utilizza il comando bq ls --transfer_config --transfer_location=location per elencare tutti i trasferimenti o chiama il metodo projects.locations.transferConfigs.list e fornisci l'ID progetto utilizzando il parametro parent.

Java

Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.cloud.bigquery.datatransfer.v1.UpdateTransferConfigRequest;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

// Sample to update transfer config.
public class UpdateTransferConfig {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setName(configId)
            .setDisplayName("UPDATED_DISPLAY_NAME")
            .build();
    FieldMask updateMask = FieldMaskUtil.fromString("display_name");
    updateTransferConfig(transferConfig, updateMask);
  }

  public static void updateTransferConfig(TransferConfig transferConfig, FieldMask updateMask)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      UpdateTransferConfigRequest request =
          UpdateTransferConfigRequest.newBuilder()
              .setTransferConfig(transferConfig)
              .setUpdateMask(updateMask)
              .build();
      TransferConfig updateConfig = dataTransferServiceClient.updateTransferConfig(request);
      System.out.println("Transfer config updated successfully :" + updateConfig.getDisplayName());
    } catch (ApiException ex) {
      System.out.print("Transfer config was not updated." + ex.toString());
    }
  }
}

Python

Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

from google.cloud import bigquery_datatransfer
from google.protobuf import field_mask_pb2

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"
new_display_name = "My Transfer Config"

transfer_config = bigquery_datatransfer.TransferConfig(name=transfer_config_name)
transfer_config.display_name = new_display_name

transfer_config = transfer_client.update_transfer_config(
    {
        "transfer_config": transfer_config,
        "update_mask": field_mask_pb2.FieldMask(paths=["display_name"]),
    }
)

print(f"Updated config: '{transfer_config.name}'")
print(f"New display name: '{transfer_config.display_name}'")

Nota: non puoi aggiornare la posizione di una query pianificata. Se sposti un set di dati di origine o di destinazione utilizzato in una query pianificata, devi creare una nuova query pianificata nella nuova posizione.

Aggiornare le query pianificate con limitazioni di proprietà

Se provi ad aggiornare una query pianificata che non è di tua proprietà, l'aggiornamento potrebbe non riuscire con il seguente messaggio di errore:

Cannot modify restricted parameters without taking ownership of the transfer configuration.

Il proprietario della query pianificata è l'utente associato alla query pianificata o l'utente che ha accesso all'account di servizio associato alla query pianificata. L'utente associato è visibile nei dettagli di configurazione della query pianificata. Per informazioni su come aggiornare la query pianificata per acquisire la proprietà, consulta Aggiornare le credenziali delle query pianificate. Per concedere agli utenti l'accesso a un account di servizio, devi disporre del ruolo Utente account di servizio.

Qualsiasi utente che non sia il proprietario della query pianificata, ma abbia accesso a tutte le risorse menzionate dalla query, potrebbe comunque essere autorizzato ad aggiornarla. Questo scenario è supportato solo se la query può essere convalidata entro un minuto o due. In caso contrario, viene visualizzato lo stesso messaggio di errore indicato in precedenza. Se la query è troppo complessa, puoi aggiornare le credenziali della query pianificata per assumerne la proprietà diretta o utilizzare un account di servizio.

Aggiorna le credenziali delle query pianificate

Se stai pianificando una query esistente, potresti dover aggiornare le credenziali dell'utente nella query. Le credenziali sono automaticamente aggiornate per le nuove query pianificate.

Ecco alcune altre situazioni che potrebbero richiedere l'aggiornamento delle credenziali:

• Vuoi eseguire query sui dati di Google Drive in una query pianificata.

• Quando provi a pianificare la query, ricevi l'errore INVALID_USER:

  Error code 5 : Authentication failure: User Id not found. Error code: INVALID_USERID

• Quando provi a actualizare la query, ricevi il seguente errore relativo ai parametri con limitazioni:

  Cannot modify restricted parameters without taking ownership of the transfer configuration.

Nota: se non sei il proprietario della query pianificata, devi disporre dell'autorizzazione bigquery.transfers.update per il tuo progetto Google Cloud per aggiornare le credenziali della query pianificata. Per ulteriori informazioni, consulta Autorizzazioni richieste.

Console

Per aggiornare le credenziali esistenti in una query pianificata:

1. Trova e visualizza lo stato di una query pianificata.

2. Fai clic sul pulsante ALTRO e seleziona Aggiorna credenziali.

   

3. Attendi 10-20 minuti affinché la modifica venga applicata. Potresti dover vuotare la cache del browser.

Attenzione: la modifica delle credenziali utilizzate in una query pianificata per un account di servizio non è supportata nella console Google Cloud.

bq

Le query pianificate sono un tipo di trasferimento. Per aggiornare le credenziali di una query pianificata, puoi utilizzare lo strumento a riga di comando bq per aggiornare la configurazione del trasferimento.

Inserisci il comando bq update e specifica il flag di trasferimento --transfer_config. Sono obbligatori anche i seguenti flag:

• --update_credentials

Flag facoltativo:

• --service_account_name è per l'autenticazione della query pianificata con un account di servizio anziché con il tuo account utente individuale.

Ad esempio, il seguente comando aggiorna una configurazione di trasferimento delle query pianificate per l'autenticazione come account di servizio:

bq update \
--update_credentials \
--service_account_name=[e-mail]
--transfer_config \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

Java

Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.cloud.bigquery.datatransfer.v1.UpdateTransferConfigRequest;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

// Sample to update credentials in transfer config.
public class UpdateCredentials {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    String serviceAccount = "MY_SERVICE_ACCOUNT";
    TransferConfig transferConfig = TransferConfig.newBuilder().setName(configId).build();
    FieldMask updateMask = FieldMaskUtil.fromString("service_account_name");
    updateCredentials(transferConfig, serviceAccount, updateMask);
  }

  public static void updateCredentials(
      TransferConfig transferConfig, String serviceAccount, FieldMask updateMask)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      UpdateTransferConfigRequest request =
          UpdateTransferConfigRequest.newBuilder()
              .setTransferConfig(transferConfig)
              .setUpdateMask(updateMask)
              .setServiceAccountName(serviceAccount)
              .build();
      dataTransferServiceClient.updateTransferConfig(request);
      System.out.println("Credentials updated successfully");
    } catch (ApiException ex) {
      System.out.print("Credentials was not updated." + ex.toString());
    }
  }
}

Python

Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

from google.cloud import bigquery_datatransfer
from google.protobuf import field_mask_pb2

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

service_account_name = "[e-mail]"
transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"

transfer_config = bigquery_datatransfer.TransferConfig(name=transfer_config_name)

transfer_config = transfer_client.update_transfer_config(
    {
        "transfer_config": transfer_config,
        "update_mask": field_mask_pb2.FieldMask(paths=["service_account_name"]),
        "service_account_name": service_account_name,
    }
)

print("Updated config: '{}'".format(transfer_config.name))

Configurare un'esecuzione manuale su date storiche

Oltre a pianificare l'esecuzione di una query in futuro, puoi anche attivare manualmente le esecuzioni immediate. L'attivazione di un'esecuzione immediata è necessaria se la query utilizza il parametro run_date e si sono verificati problemi durante un'esecuzione precedente.

Ad esempio, ogni giorno alle 09:00 esegui una query su una tabella di origine per trovare le righe corrispondenti alla data corrente. Tuttavia, scopri che i dati non sono stati aggiunti alla tabella di origine per gli ultimi tre giorni. In questo caso, puoi impostare l'esecuzione della query sui dati storici all'interno di un intervallo di date specificato. La query viene eseguita utilizzando combinazioni di parametri run_date e run_time corrispondenti alle date configurate nella query pianificata.

Dopo aver configurato una query pianificata, ecco come eseguire la query utilizzando un intervallo di date storico:

Console

Dopo aver fatto clic su Pianifica per salvare la query pianificata, puoi fare clic sul pulsante Query pianificate per visualizzare l'elenco delle query attualmente pianificate. Fai clic su un nome visualizzato per visualizzare i dettagli della pianificazione delle query. In alto a destra nella pagina, fai clic su Pianifica il backfill per specificare un intervallo di date storico.

I tempi di esecuzione scelti rientrano tutti nell'intervallo selezionato, inclusa la prima data ed esclusa l'ultima.

Gli intervalli di date che fornisci sono in UTC, ma la pianificazione della query viene visualizzata nel tuo fuso orario locale (consulta Esempio 2 per risolvere il problema).

Esempio 1

La query pianificata è impostata per l'esecuzione alle ore every day 09:00 (fuso orario del Pacifico USA). Mancano i dati del 1°, 2 e 3 gennaio. Scegli il seguente intervallo di date storico:

Start Time = 1/1/19
End Time = 1/4/19

La query viene eseguita utilizzando i parametri run_date e run_time che corrispondono ai seguenti periodi di tempo:

• 1/1/19 09:00 PST
• 1/2/19 09:00 PST
• 3/1/19 09:00 fuso orario del Pacifico USA

Esempio 2

La query pianificata è impostata per l'esecuzione alle ore every day 23:00 (fuso orario del Pacifico USA). Mancano i dati del 1°, 2 e 3 gennaio. Scegli i seguenti intervalli di date storici (vengono scelte date successive perché alle 23:00 (ora del Pacifico USA) il fuso orario UTC ha una data diversa):

Start Time = 1/2/19
End Time = 1/5/19

La query viene eseguita utilizzando i parametri run_date e run_time che corrispondono ai seguenti periodi di tempo:

• 2/01/19 06:00 UTC o 1/01/2019 23:00 PST
• 3/01/19 06:00 UTC o 2/01/2019 23:00 PST
• 4/01/19 06:00 UTC o 3/01/2019 23:00 PST

Dopo aver configurato le esecuzioni manuali, aggiorna la pagina per visualizzarle nell'elenco delle esecuzioni.

bq

Per eseguire manualmente la query su un intervallo di date storico:

Inserisci il comando bq mk e specifica il flag di esecuzione del trasferimento --transfer_run. Sono obbligatori anche i seguenti flag:

• --start_time
• --end_time

bq mk \
--transfer_run \
--start_time='start_time' \
--end_time='end_time' \
resource_name

Sostituisci quanto segue:

• start_time e end_time. Timestamp che terminano con Z o contengono una differenza di fuso orario valida. Esempi:
  • 2017-08-19T12:11:35.00Z
  • 2017-05-25T00:00:00+00:00
• resource_name. Il nome della risorsa della query pianificata (o del trasferimento). Il nome della risorsa è noto anche come configurazione di trasferimento.

Ad esempio, il seguente comando pianifica un backfill per la risorsa query pianificata (o la configurazione di trasferimento):projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7.

  bq mk \
  --transfer_run \
  --start_time 2017-05-25T00:00:00Z \
  --end_time 2017-05-25T00:00:00Z \
  projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

Per ulteriori informazioni, vedi bq mk --transfer_run.

API

Utilizza il metodo projects.locations.transferConfigs.scheduleRun e fornisci un percorso della risorsa TransferConfig.

Java

Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ScheduleTransferRunsRequest;
import com.google.cloud.bigquery.datatransfer.v1.ScheduleTransferRunsResponse;
import com.google.protobuf.Timestamp;
import java.io.IOException;
import org.threeten.bp.Clock;
import org.threeten.bp.Instant;
import org.threeten.bp.temporal.ChronoUnit;

// Sample to run schedule back fill for transfer config
public class ScheduleBackFill {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    Clock clock = Clock.systemDefaultZone();
    Instant instant = clock.instant();
    Timestamp startTime =
        Timestamp.newBuilder()
            .setSeconds(instant.minus(5, ChronoUnit.DAYS).getEpochSecond())
            .setNanos(instant.minus(5, ChronoUnit.DAYS).getNano())
            .build();
    Timestamp endTime =
        Timestamp.newBuilder()
            .setSeconds(instant.minus(2, ChronoUnit.DAYS).getEpochSecond())
            .setNanos(instant.minus(2, ChronoUnit.DAYS).getNano())
            .build();
    scheduleBackFill(configId, startTime, endTime);
  }

  public static void scheduleBackFill(String configId, Timestamp startTime, Timestamp endTime)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ScheduleTransferRunsRequest request =
          ScheduleTransferRunsRequest.newBuilder()
              .setParent(configId)
              .setStartTime(startTime)
              .setEndTime(endTime)
              .build();
      ScheduleTransferRunsResponse response = client.scheduleTransferRuns(request);
      System.out.println("Schedule backfill run successfully :" + response.getRunsCount());
    } catch (ApiException ex) {
      System.out.print("Schedule backfill was not run." + ex.toString());
    }
  }
}

Python

Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

import datetime

from google.cloud.bigquery_datatransfer_v1 import (
    DataTransferServiceClient,
    StartManualTransferRunsRequest,
)

# Create a client object
client = DataTransferServiceClient()

# Replace with your transfer configuration name
transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"
now = datetime.datetime.now(datetime.timezone.utc)
start_time = now - datetime.timedelta(days=5)
end_time = now - datetime.timedelta(days=2)

# Some data sources, such as scheduled_query only support daily run.
# Truncate start_time and end_time to midnight time (00:00AM UTC).
start_time = datetime.datetime(
    start_time.year, start_time.month, start_time.day, tzinfo=datetime.timezone.utc
)
end_time = datetime.datetime(
    end_time.year, end_time.month, end_time.day, tzinfo=datetime.timezone.utc
)

requested_time_range = StartManualTransferRunsRequest.TimeRange(
    start_time=start_time,
    end_time=end_time,
)

# Initialize request argument(s)
request = StartManualTransferRunsRequest(
    parent=transfer_config_name,
    requested_time_range=requested_time_range,
)

# Make the request
response = client.start_manual_transfer_runs(request=request)

# Handle the response
print("Started manual transfer runs:")
for run in response.runs:
    print(f"backfill: {run.run_time} run: {run.name}")

Eliminare le query pianificate

Console

Per eliminare una query pianificata tramite la console:

1. Nel riquadro di navigazione, fai clic su Query pianificate.

2. Nell'elenco delle query pianificate, fai clic sul nome della query pianificata da eliminare.

3. Nella pagina Dettagli query programmata che si apre, fai clic su Elimina.

Java

Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.DeleteTransferConfigRequest;
import java.io.IOException;

// Sample to delete a transfer config
public class DeleteTransferConfig {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // i.e projects/{project_id}/transferConfigs/{config_id}` or
    // `projects/{project_id}/locations/{location_id}/transferConfigs/{config_id}`
    String configId = "MY_CONFIG_ID";
    deleteTransferConfig(configId);
  }

  public static void deleteTransferConfig(String configId) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      DeleteTransferConfigRequest request =
          DeleteTransferConfigRequest.newBuilder().setName(configId).build();
      dataTransferServiceClient.deleteTransferConfig(request);
      System.out.println("Transfer config deleted successfully");
    } catch (ApiException ex) {
      System.out.println("Transfer config was not deleted." + ex.toString());
    }
  }
}

Python

Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

import google.api_core.exceptions
from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"
try:
    transfer_client.delete_transfer_config(name=transfer_config_name)
except google.api_core.exceptions.NotFound:
    print("Transfer config not found.")
else:
    print(f"Deleted transfer config: {transfer_config_name}")

Quote

Le query pianificate vengono eseguite con le credenziali e il progetto del creator, come se tu stessi eseguendo la query. Le query pianificate vengono sempre eseguite come job di query collettive.

Anche se usano funzionalità di BigQuery Data Transfer Service, le query programmate non sono trasferimenti e non sono quindi soggette alla quota dei job di caricamento. Le query programmate sono soggette alle stesse quote e limiti di BigQuery, come le query manuali.

Prezzi

Il prezzo delle query programmate è lo stesso delle query BigQuery manuali.

Aree geografiche supportate

Attenzione: le query tra regioni non sono supportate. La tabella di destinazione per la query pianificata deve trovarsi nella stessa regione dei dati sottoposti a query. La località selezionata per la query programmata deve essere anche la stessa regione dei dati sottoposti a query.

Le query pianificate sono supportate nelle seguenti località.

Regioni

La tabella seguente elenca le regioni delle Americhe in cui BigQuery è disponibile.

Descrizione della regione	Nome della regione	Dettagli
Columbus, Ohio	us-east5
Dallas	us-south1	Bassi livelli di CO2
Iowa	us-central1	Bassi livelli di CO2
Las Vegas	us-west4
Los Angeles	us-west2
Montréal	northamerica-northeast1	Bassi livelli di CO2
Virginia del Nord	us-east4
Oregon	us-west1	Bassi livelli di CO2
Salt Lake City	us-west3
San Paolo	southamerica-east1	Bassi livelli di CO2
Santiago	southamerica-west1	Bassi livelli di CO2
Carolina del Sud	us-east1
Toronto	northamerica-northeast2	Bassi livelli di CO2

La tabella seguente elenca le regioni dell'Asia Pacifico in cui è disponibile BigQuery.

Descrizione della regione	Nome della regione	Dettagli
Delhi	asia-south2
Hong Kong	asia-east2
Giacarta	asia-southeast2
Melbourne	australia-southeast2
Mumbai	asia-south1
Osaka	asia-northeast2
Seul	asia-northeast3
Singapore	asia-southeast1
Sydney	australia-southeast1
Taiwan	asia-east1
Tokyo	asia-northeast1

La tabella seguente elenca le regioni in Europa in cui BigQuery è disponibile.

Descrizione della regione	Nome della regione	Dettagli
Belgio	europe-west1	Bassi livelli di CO2
Berlino	europe-west10	Bassi livelli di CO2
Finlandia	europe-north1	Bassi livelli di CO2
Francoforte	europe-west3	Bassi livelli di CO2
Londra	europe-west2	Bassi livelli di CO2
Madrid	europe-southwest1	Bassi livelli di CO2
Milano	europe-west8
Paesi Bassi	europe-west4	Bassi livelli di CO2
Parigi	europe-west9	Bassi livelli di CO2
Torino	europe-west12
Varsavia	europe-central2
Zurigo	europe-west6	Bassi livelli di CO2

La tabella seguente elenca le regioni del Medio Oriente in cui BigQuery è disponibile.

Descrizione della regione	Nome della regione	Dettagli
Dammam	me-central2
Doha	me-central1
Tel Aviv	me-west1

La tabella seguente elenca le regioni in Africa in cui BigQuery è disponibile.

Descrizione della regione	Nome della regione	Dettagli
Johannesburg	africa-south1

Più regioni

La tabella seguente elenca le regioni multiple in cui BigQuery è disponibile.

Descrizione multiregionale	Nome multiregione
Data center all'interno degli stati membri dell'Unione Europea^1	EU
Data center negli Stati Uniti^2	US

Nota: la selezione di una località multiregione non fornisce la replica tra regioni o la ridondanza regionale, pertanto non aumenta la disponibilità del set di dati in caso di interruzione del servizio a livello di regione. I dati vengono archiviati in un'unica regione all'interno della posizione geografica.

¹ I dati che si trovano nella regione multipla EU vengono memorizzati solo in una delle seguenti località: europe-west1 (Belgio) o europe-west4 (Paesi Bassi). La posizione esatta in cui i dati vengono archiviati ed elaborati viene determinata automaticamente da BigQuery.

² I dati situati nella regione multipla US vengono memorizzati solo in una delle seguenti località: us-central1 (Iowa), us-west1 (Oregon) o us-central2 (Oklahoma). La posizione esatta in cui i dati vengono archiviati ed elaborati viene determinata automaticamente da BigQuery.

Passaggi successivi

• Per un esempio di query pianificata che utilizza un account di servizio e include i parametri @run_date e @run_time, consulta Creare snapshot delle tabelle con una query pianificata.