Esecuzione programmatica dei job

L'API REST e le librerie client di BigQuery ti consentono di creare e gestire job asincroni per automatizzare le operazioni di caricamento, query, estrazione e copia dalle tue applicazioni. Dopo aver avviato un job chiamando il metodo jobs.insert, puoi eseguire il polling della proprietà status della risorsa del job per monitorare il completamento dell'esecuzione e verificare se l'operazione è riuscita.

Prima di iniziare

Concedi i ruoli IAM (Identity and Access Management) che forniscono agli utenti le autorizzazioni necessarie per eseguire ogni attività in questo documento.

Autorizzazioni obbligatorie

Per eseguire un job BigQuery, devi disporre dell'autorizzazione IAM bigquery.jobs.create.

Ciascuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per eseguire un job:

• roles/bigquery.user
• roles/bigquery.jobUser
• roles/bigquery.admin

Inoltre, quando crei un job, ti vengono concesse automaticamente le seguenti autorizzazioni per quel job:

• bigquery.jobs.get
• bigquery.jobs.update

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

Job in esecuzione

Per eseguire un job in modo programmatico:

1. Avvia il job chiamando il metodo jobs.insert. Quando chiami il metodo jobs.insert, includi una rappresentazione della risorsa job.

2. Nella sezione configuration della risorsa del job, includi una proprietà secondaria che specifichi il tipo di job: load, query, extract o copy.

3. Dopo aver chiamato il metodo jobs.insert, controlla lo stato del job chiamando jobs.get con l'ID job e la località e controlla il valore status.state per conoscere lo stato del job. Quando status.state è DONE, il job ha smesso di essere eseguito. Tuttavia, lo stato DONE non significa che il job è stato completato correttamente, ma solo che non è più in esecuzione.

   Nota: esistono alcune funzioni wrapper che gestiscono le richieste di stato dei job per te. Ad esempio, l'esecuzione di jobs.query crea un job ed esegue periodicamente il polling per lo stato DONE per un periodo di tempo specificato.

4. Verifica l'esito positivo del job. Se il job ha una proprietà errorResult, significa che non è riuscito. La proprietà status.errorResult contiene informazioni che descrivono cosa è andato storto in un job non riuscito. Se status.errorResult non è presente, il job è stato completato correttamente, anche se potrebbero essersi verificati alcuni errori non irreversibili, ad esempio problemi di importazione di alcune righe in un job di caricamento. Gli errori non irreversibili vengono restituiti nell'elenco status.errors del job.

Esecuzione di job utilizzando le librerie client

Per creare ed eseguire un job utilizzando le librerie client di Cloud per BigQuery:

C#

Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery C#.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

using Google.Cloud.BigQuery.V2;
using System;
using System.Collections.Generic;

public class BigQueryCreateJob
{
    public BigQueryJob CreateJob(string projectId = "your-project-id")
    {
        string query = @"
            SELECT country_name from `bigquery-public-data.utility_us.country_code_iso";

        // Initialize client that will be used to send requests.
        BigQueryClient client = BigQueryClient.Create(projectId);

        QueryOptions queryOptions = new QueryOptions
        {
            JobLocation = "us",
            JobIdPrefix = "code_sample_",
            Labels = new Dictionary<string, string>
            {
                ["example-label"] = "example-value"
            },
            MaximumBytesBilled = 1000000
        };

        BigQueryJob queryJob = client.CreateQueryJob(
            sql: query,
            parameters: null,
            options: queryOptions);

        Console.WriteLine($"Started job: {queryJob.Reference.JobId}");
        return queryJob;
    }
}

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobId;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.common.collect.ImmutableMap;
import java.util.UUID;

// Sample to create a job
public class CreateJob {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String query = "SELECT country_name from `bigquery-public-data.utility_us.country_code_iso`";
    createJob(query);
  }

  public static void createJob(String query) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Specify a job configuration to set optional job resource properties.
      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query)
              .setLabels(ImmutableMap.of("example-label", "example-value"))
              .build();

      // The location and job name are optional,
      // if both are not specified then client will auto-create.
      String jobName = "jobId_" + UUID.randomUUID().toString();
      JobId jobId = JobId.newBuilder().setLocation("us").setJob(jobName).build();

      // Create a job with job ID
      bigquery.create(JobInfo.of(jobId, queryConfig));

      // Get a job that was just created
      Job job = bigquery.getJob(jobId);
      if (job.getJobId().getJob().equals(jobId.getJob())) {
        System.out.print("Job created successfully." + job.getJobId().getJob());
      } else {
        System.out.print("Job was not created");
      }
    } catch (BigQueryException e) {
      System.out.print("Job was not created. \n" + e.toString());
    }
  }
}

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

query_job = client.query(
    "SELECT country_name from `bigquery-public-data.utility_us.country_code_iso`",
    # Explicitly force job execution to be routed to a specific processing
    # location.
    location="US",
    # Specify a job configuration to set optional job resource properties.
    job_config=bigquery.QueryJobConfig(
        labels={"example-label": "example-value"}, maximum_bytes_billed=1000000
    ),
    # The client libraries automatically generate a job ID. Override the
    # generated ID with either the job_id_prefix or job_id parameters.
    job_id_prefix="code_sample_",
)  # Make an API request.

print("Started job: {}".format(query_job.job_id))

Aggiunta di etichette dei job

Le etichette possono essere aggiunte ai job di query tramite la riga di comando utilizzando il flag --label dello strumento a riga di comando bq. Lo strumento bq supporta l'aggiunta di etichette solo ai job di query.

Puoi anche aggiungere un'etichetta a un job quando viene inviato tramite l'API specificando la proprietà labels nella configurazione del job quando chiami il metodo jobs.insert. L'API può essere utilizzata per aggiungere etichette a qualsiasi tipo di prestazione.

Non puoi aggiungere o aggiornare etichette ai job in attesa, in esecuzione o completati.

Quando aggiungi un'etichetta a un job, l'etichetta viene inclusa nei dati di fatturazione.

Per saperne di più, consulta Aggiunta di etichette dei job.

Passaggi successivi

• Consulta Esecuzione di query per un esempio di codice che avvia ed esegue il polling di un job di query.
• Per saperne di più sulla creazione di una rappresentazione della risorsa job, consulta la pagina Panoramica dei job nel riferimento API.