Programmazione delle query

Questa pagina descrive come pianificare le query ricorrenti in BigQuery.

Puoi pianificare le query in modo che vengano eseguite su base ricorrente. Le query pianificate devono essere scritte in GoogleSQL, che può includere istruzioni DataDefinition Language (DDL) e Data Manipulation Language (DML). Puoi organizzare i risultati delle 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 per la query viene convertita dall'ora locale a UTC. Il fuso orario UTC non è influenzato dall'ora legale.

Prima di iniziare

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 o delle autorizzazioni bigquery.jobs.create, bigquery.transfers.get e bigquery.datasets.get.

  • Per eseguire una query pianificata, devi avere:

    • bigquery.datasets.get autorizzazioni per il 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 di roles/bigquery.admin include le autorizzazioni necessarie per pianificare o modificare una query.

Per ulteriori informazioni sui ruoli IAM in BigQuery, consulta Autorizzazioni e ruoli 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 agli utenti del ruolo Account di servizio, consulta Ruolo utente Account di servizio. Per selezionare un account di servizio nell'interfaccia utente della query pianificata della console Google Cloud, devi disporre delle seguenti autorizzazioni IAM:

  • iam.serviceAccounts.list

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 Rappresentato nel fuso orario UTC. Per le query pianificate regolarmente, run_time rappresenta il tempo di esecuzione previsto. Ad esempio, se la query pianificata è impostata su "ogni 24 ore", la differenza di run_time tra due query consecutive è esattamente di 24 ore, anche se il tempo di esecuzione effettivo potrebbe variare leggermente.
@run_date DATA Rappresenta una data di calendario logico.

Esempio

In questo esempio, il parametro @run_time fa parte della stringa di query, 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 creare la tabella per te.

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

Se la tabella di destinazione esiste e utilizzi la preferenza di scrittura WRITE_APPEND, BigQuery aggiunge i dati alla tabella di destinazione e prova a mappare lo schema. BigQuery consente automaticamente l'aggiunta e il riordinamento dei campi e ospita i campi facoltativi mancanti. Se lo schema della tabella cambia così tanto tra le esecuzioni che BigQuery non può elaborare automaticamente le modifiche, la query pianificata ha esito negativo.

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. Il set di dati di destinazione deve essere specificato 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 il modo in cui i risultati della query vengono scritti 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 usi una query DDL o DML, non puoi utilizzare l'opzione della preferenza di scrittura.

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

Clustering

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

Opzioni di partizionamento

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

Puoi utilizzare i seguenti tipi di partizionamento delle tabelle in BigQuery:

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

  • Per utilizzare il partizionamento dell'intervallo di numeri interi, lascia vuoto il campo Partizionamento della tabella di destinazione.

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

  • Per utilizzare il partizionamento per data di importazione, lascia vuoto il campo di partizionamento della tabella di destinazione e indica il partizionamento delle date nel nome della tabella. Ad esempio, mytable${run_date}. Per maggiori informazioni, consulta Sintassi dei modelli dei parametri.

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 Nel fuso orario UTC, secondo la programmazione. Per le query pianificate regolarmente, run_time rappresenta il tempo di esecuzione previsto. 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 può variare leggermente.

Vedi TransferRun.runTime.
run_date Stringa della 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 la fase di importazione.

Sistema di creazione dei modelli

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

Sintassi dei modelli dei parametri

La sintassi dei modelli supporta i modelli di stringa di base e la compensazione temporale. Ai parametri viene fatto riferimento nei seguenti formati:

  • {run_date}
  • {run_time[+\-offset]|"time_format"}
Parametro Purpose
run_date Questo parametro è sostituito dalla data nel formato YYYYMMDD.
run_time Questo parametro supporta le seguenti proprietà:


offset
Differenza di tempo espressa 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, il suffisso richiesto è AAAAMMGG, equivalente a "%Y%m%d".

Scopri di più sulla formattazione degli elementi di data/ora.

Note sull'utilizzo:
  • Non sono consentiti spazi vuoti tra run_time, offset e formato ora.
  • Per includere parentesi graffe letterali nella stringa, puoi eseguire l'escape delle parentesi graffe come '\{' and '\}'.
  • Per includere le virgolette letterali o una barra verticale in time_format, come "YYYY|MM|DD", puoi eseguire l'escape delle virgolette nella stringa di formato come: '\"' o '\|'.

Esempi di modelli di parametri

Questi esempi mostrano la specifica di nomi delle tabelle di destinazione con formati temporali diversi e la differenza del tempo di esecuzione.
run_time (UTC) Parametro basato su modello Nome tabella di destinazione di output
15-02-2018 00:00:00 mytable mytable
15-02-2018 00:00:00 mytable_{run_time|"%Y%m%d"} mytable_20180215
15-02-2018 00:00:00 mytable_{run_time+25h|"%Y%m%d"} mytable_20180216
15-02-2018 00:00:00 mytable_{run_time-1h|"%Y%m%d"} mytable_20180214
15-02-2018 00:00:00 mytable_{run_time+1.5h|"%Y%m%d%H"}
o
mytable_{run_time+90m|"%Y%m%d%H"}		 mytable_2018021501
15-02-2018 00:00:00 {run_time+97s|"%Y%m%d"}_mytable_{run_time+97s|"%H%M%S"} 20180215_mytable_000137

Utilizzo di un account di servizio

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 batch, con le proprie credenziali di servizio anziché quelle di un utente finale.

Per ulteriori informazioni sull'autenticazione con gli account di servizio, consulta Introduzione all'autenticazione.

Specifica la chiave di crittografia con query pianificate

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

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

Non puoi aggiornare un trasferimento esistente per aggiungere una CMEK se il trasferimento non è stato creato originariamente con una CMEK. Ad esempio, non puoi modificare una tabella di destinazione che in origine era criptata per impostazione predefinita per ora essere criptata con CMEK. Al contrario, non puoi modificare una tabella di destinazione criptata con CMEK in modo che abbia un tipo di crittografia diverso.

Puoi aggiornare una CMEK per un trasferimento se la configurazione di trasferimento è stata creata originariamente con una crittografia CMEK. Quando aggiorni una CMEK per una configurazione di trasferimento, BigQuery Data Transfer Service propaga la CMEK alle tabelle di destinazione all'esecuzione successiva del trasferimento, in cui BigQuery Data Transfer Service sostituisce eventuali CMEK obsolete con la nuova CMEK durante l'esecuzione del trasferimento. Per ulteriori informazioni, vedi 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 utilizza la chiave predefinita del progetto come chiave predefinita per qualsiasi nuova configurazione di trasferimento.

Configurare le query pianificate

Per una descrizione della sintassi della pianificazione, consulta Formattazione della pianificazione. Per maggiori dettagli 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 e Crea nuova query pianificata.

    Crea una nuova query pianificata nella console Google Cloud.

  3. Le opzioni della query pianificata si aprono nel riquadro Nuova query pianificata. Nuovo riquadro delle query pianificate.

  4. Nel riquadro Nuova query pianificata:

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

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

      • Per specificare una frequenza personalizzata, seleziona Personalizzata, poi inserisci una specifica temporale simile a una crono nel campo Pianificazione personalizzata, ad esempio every mon 23:30 o every 6 hours. Per maggiori dettagli sulle pianificazioni valide, inclusi intervalli personalizzati, consulta il campo schedule in Risorsa: TransferConfig.

        Formattazione di una query pianificata personalizzata.

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

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

      • Per salvare la query senza una pianificazione, in modo da poterla eseguire on demand in un secondo momento, seleziona On demand nel menu Si ripete.

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

    • In Nome set di dati, scegli il set di dati di destinazione appropriato.
    • In Nome tabella, inserisci il nome della tabella di destinazione.
    • In Preferenza di scrittura della tabella di destinazione, scegli Aggiungi alla tabella per aggiungere dati alla tabella o Sovrascrivi tabella per sovrascrivere la tabella di destinazione.

    • Per le query DDL e DML, scegli la Località di elaborazione o la regione.

      Nuova destinazione della query pianificata.

  6. 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. Per informazioni su come funzionano le chiavi di crittografia gestite dal cliente (CMEK) con BigQuery Data Transfer Service, consulta Specificare la chiave di crittografia con query pianificate.

    • Autentica 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 anziché utilizzare le tue credenziali utente. In Credenziali di query pianificate, fai clic sul menu per visualizzare un elenco degli account di servizio disponibili. Se hai eseguito l'accesso come identità federata, è necessario un account di servizio.

      Opzioni avanzate della query pianificata.

  7. Configurazioni aggiuntive:

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

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

      Nuove query DDL e DML pianificate.

  8. Fai clic sul pulsante Programma.

bq

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 per la query pianificata. Il nome visualizzato può essere qualsiasi valore che puoi identificare in seguito 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.
    • Usa --destination_table o --target_dataset, ma non entrambi.
  • interval. Se utilizzato in combinazione con bq query, rende una query una query pianificata ricorrente. È necessaria una pianificazione della frequenza di esecuzione della query. Per maggiori dettagli sulle pianificazioni valide, inclusi 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 a ogni esecuzione della query pianificata.

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

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

Ad esempio, il seguente comando crea una query pianificata denominata My Scheduled Query utilizzando la semplice query 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 usare lo strumento a riga di comando bq per configurare il trasferimento.

Per poter essere pianificate, le query devono essere in dialetto StandardSQL.

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 indica la frequenza di esecuzione della query. Se --schedule non è 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 particolare regione per l'elaborazione. Se --location non è specificata, viene utilizzata la località Google Cloud più vicina.

  • --service_account_name consente di autenticare la query pianificata con un account di servizio anziché con il tuo account utente individuale.

  • --destination_kms_key specifica l'ID risorsa della chiave per la chiave se utilizzi una chiave di crittografia gestita dal cliente (CMEK) per questo trasferimento. Per informazioni su come funzionano le CMEK con BigQuery Data Transfer Service, 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 di trasferimento. Il nome visualizzato può essere qualsiasi valore che puoi identificare in seguito se devi modificare la query.
  • parameters. Contiene i parametri per la configurazione di 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 aggiungere 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. Origine dati: scheduled_query.
  • (Facoltativo) Il flag --service_account_name riguarda l'autenticazione con un account di servizio anziché con un account utente individuale.
  • (Facoltativo) --destination_kms_key specifica l'ID risorsa della chiave per la chiave Cloud KMS, ad esempio projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name.

Ad esempio, il seguente comando crea una configurazione di trasferimento delle query pianificato 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 viene autenticata 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=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com

La prima volta che esegui 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 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 saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 = "abcdef-test-sa@abcdef-test.iam.gserviceaccount.com"

# 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 le 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 saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 = "abcdef-test-sa@abcdef-test.iam.gserviceaccount.com"

# 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 della query pianificata

Console

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

Elenca le query pianificate.

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 fornisci il flag di trasferimento --transfer_config. Sono richiesti 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 di query/trasferimento pianificata.

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 saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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}")

Aggiorna query pianificate

Console

Per aggiornare una query pianificata, segui questi passaggi:

  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 query pianificata che si apre, fai clic su Modifica. Modifica i dettagli della query pianificata.
  4. (Facoltativo) Modifica il testo della query nel riquadro di modifica della query.
  5. Fai clic su Pianifica query e seleziona Aggiorna query pianificata.
  6. (Facoltativo) Modifica eventuali altre opzioni di pianificazione per la query.
  7. Fai clic su Update (Aggiorna).

bq

Le query pianificate sono un tipo di trasferimento. Per aggiornare la query pianificata, puoi usare lo strumento a riga di comando bq per configurare il trasferimento.

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

Flag facoltativi:

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

  • --schedule indica la frequenza di esecuzione della query. Se --schedule non è 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 maggiori informazioni, consulta Aggiornare le credenziali della query pianificata.

  • --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 delle query, se utilizzato con query DDL e DML.

  • --display_name è il nome della query pianificata.

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

  • --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 chiavi di crittografia gestite dal cliente (CMEK) con BigQuery Data Transfer Service, vedi Specificare la chiave di crittografia con 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 di trasferimento. Il nome visualizzato può essere qualsiasi valore che puoi identificare in seguito se devi modificare la query.
  • parameters. Contiene i parametri per la configurazione di 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 aggiungere 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 della 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 (noto anche come configurazione di trasferimento). Se non conosci il nome della risorsa trasferimento, cercalo con: bq ls --transfer_config --transfer_location=location.

Ad esempio, il seguente comando aggiorna una configurazione di trasferimento delle query pianificato 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, usa il comando bq ls --transfer_config --transfer_location=location per elencare tutti i trasferimenti oppure 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 saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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}'")

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 e generare 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 affinché diventi la proprietà, consulta Aggiornare le credenziali della query pianificata. Per concedere agli utenti l'accesso a un account di servizio, devi disporre del ruolo utente Account di servizio.

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

Aggiorna le credenziali della query pianificata

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

Ecco altri casi che potrebbero richiedere l'aggiornamento delle credenziali:

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

  • Ricevi un errore INVALID_USER quando cerchi di pianificare la query:

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

  • Quando provi ad aggiornare la query, ricevi il seguente errore relativo ai parametri con restrizioni:

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

Console

Per aggiornare le credenziali esistenti in una query pianificata:

  1. Trovare e visualizzare lo stato di una query pianificata.

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

    Aggiorna le credenziali della query pianificata.

  3. Attendi 10-20 minuti affinché la modifica abbia effetto. Potresti dover svuotare la cache del browser.

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 di trasferimento.

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

  • --update_credentials

Flag facoltativo:

  • --service_account_name consente di autenticare la 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 pianificato per l'autenticazione come account di servizio:

bq update \
--update_credentials \
--service_account_name=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com
--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 saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 = "abcdef-test-sa@abcdef-test.iam.gserviceaccount.com"
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 per date storiche

Oltre a pianificare l'esecuzione di una query in futuro, puoi anche attivare manualmente le esecuzioni immediate. Sarà necessario attivare un'esecuzione immediata 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 in una tabella di origine per le righe che corrispondono alla data corrente. Tuttavia, noterai che i dati non sono stati aggiunti alla tabella di origine negli ultimi tre giorni. In questo caso, puoi impostare la query in modo che venga eseguita sui dati storici entro un intervallo di date specificato. La query viene eseguita utilizzando combinazioni di parametri run_date e run_time che corrispondono alle date configurate nella query pianificata.

Dopo aver impostato una query pianificata, ecco come eseguirla 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 vedere i dettagli della pianificazione della query. In alto a destra nella pagina, fai clic su Pianifica backfill per specificare un intervallo di date storico.

Pulsante Pianifica backfill.

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

imposta date storiche

Esempio 1

La query pianificata è impostata per l'esecuzione nel fuso orario del Pacifico - every day 09:00. Ti mancano i dati del 1° gennaio, del 2 gennaio e del 3 gennaio. Scegli il seguente intervallo di date storiche:

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 orari:

  • 1/01/19 09:00 Fuso orario del Pacifico
  • 2/01/19 09:00 Fuso orario del Pacifico
  • 3/01/19 09:00 Fuso orario del Pacifico

Esempio 2

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

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 orari:

  • 2/01/19 06:00 UTC o 1/01/2019 23:00 Ora del Pacifico
  • 3/1/19 06:00 UTC o 2/01/2019 23:00 Ora del Pacifico
  • 4/1/19 06:00 UTC o 3/1/2019 23:00 Ora del Pacifico

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

bq

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

Inserisci il comando bq mk e fornisci il flag di esecuzione del trasferimento --transfer_run. Sono richiesti 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. I timestamp che terminano con Z o contengono uno scarto di fuso orario valido. 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 è anche noto come configurazione di trasferimento.

Ad esempio, il comando seguente pianifica un backfill per la risorsa di 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

Usa 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 saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 che vuoi eliminare.

  3. Nella pagina Dettagli query pianificata che si apre, fai clic su Elimina. Aggiorna le credenziali della query pianificata.

Java

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

Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 dell'autore, come se stessi eseguendo la query personalmente. Le query pianificate vengono sempre eseguite come job di query batch.

Sebbene le query pianificate utilizzino le funzionalità di BigQuery Data Transfer Service, non sono trasferimenti e non sono 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 pianificate è uguale a quello delle query BigQuery manuali.

Aree geografiche supportate

Le query pianificate sono supportate nelle seguenti località.

Regioni

La seguente tabella elenca le regioni delle Americhe in cui è disponibile BigQuery.
Descrizione della regione Nome regione Dettagli
Columbus, Ohio us-east5
Dallas us-south1
Iowa us-central1 icona foglia A basse emissioni di CO2
Las Vegas us-west4
Los Angeles us-west2
Montréal northamerica-northeast1 icona foglia A basse emissioni di CO2
Virginia del Nord us-east4
Oregon us-west1 icona foglia A basse emissioni di CO2
Salt Lake City us-west3
San Paolo southamerica-east1 icona foglia A basse emissioni di CO2
Santiago southamerica-west1 icona foglia A basse emissioni di CO2
Carolina del Sud us-east1
Toronto northamerica-northeast2 icona foglia A basse emissioni di CO2
La seguente tabella elenca le regioni dell'Asia Pacifico in cui è disponibile BigQuery.
Descrizione della regione Nome 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 seguente tabella elenca le regioni in Europa in cui è disponibile BigQuery.
Descrizione della regione Nome regione Dettagli
Belgio europe-west1 icona foglia A basse emissioni di CO2
Berlino europe-west10
Finlandia europe-north1 icona foglia A basse emissioni di CO2
Francoforte europe-west3 icona foglia A basse emissioni di CO2
Londra europe-west2 icona foglia A basse emissioni di CO2
Madrid europe-southwest1
Milano europe-west8
Paesi Bassi europe-west4
Parigi europe-west9 icona foglia A basse emissioni di CO2
Torino europe-west12
Varsavia europe-central2
Zurigo europe-west6 icona foglia A basse emissioni di CO2
La seguente tabella elenca le regioni del Medio Oriente in cui è disponibile BigQuery.
Descrizione della regione Nome regione Dettagli
Dammam me-central2
Doha me-central1
Tel Aviv me-west1
La seguente tabella elenca le regioni in Africa in cui è disponibile BigQuery.
Descrizione della regione Nome regione Dettagli
Johannesburg africa-south1

Più regioni

La tabella seguente elenca le regioni multiple in cui è disponibile BigQuery.
Descrizione per più regioni Nome più regioni
Data center negli stati membri dell'Unione Europea1 EU
Data center negli Stati Uniti US

1 I dati che si trovano nella località multiregionale EU vengono archiviati solo nei data center europe-west1 (Belgio) o europe-west4 (Paesi Bassi).

Che cosa succede dopo?