Exécuter des tâches de manière automatisée

Pour exécuter une tâche BigQuery de manière automatisée à l'aide de l'API REST ou des bibliothèques clientes, procédez comme suit :

Appelez la méthode jobs.insert.
Interrogez régulièrement la ressource de tâche et examinez la propriété de l'état pour savoir quand la tâche est terminée.
Vérifiez que la tâche a bien été exécutée.

Avant de commencer

Attribuez aux utilisateurs des rôles IAM (Identity and Access Management) incluant les autorisations nécessaires pour effectuer l'ensemble des tâches du présent document.

Autorisations requises

Pour exécuter une tâche BigQuery, vous avez besoin de l'autorisation IAM bigquery.jobs.create.

Chacun des rôles IAM prédéfinis suivants inclut les autorisations dont vous avez besoin pour exécuter une tâche :

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

De plus, lorsque vous créez une tâche, vous recevez automatiquement les autorisations suivantes pour cette tâche :

bigquery.jobs.get
bigquery.jobs.update

Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la page Rôles prédéfinis et autorisations.

Tâches en cours d'exécution

Pour exécuter une tâche de manière automatisée, procédez comme suit :

Démarrez la tâche en appelant la méthode jobs.insert. Lorsque vous appelez la méthode jobs.insert, incluez une représentation de la ressource de tâche.
Dans la section configuration de la ressource de tâche, incluez une propriété enfant qui spécifie le type de tâche : load (charger), query (interroger), extract (extraire) ou copy (copier).
Après avoir appelé la méthode jobs.insert, vérifiez l'état de la tâche en appelant jobs.get à l'aide de l'ID et l'emplacement de la tâche, puis vérifiez la valeur status.state pour connaître l'état de la tâche. Lorsque status.state est défini sur DONE, la tâche a cessé de s'exécuter. À noter cependant qu'un état DONE ne signifie pas que la tâche a bien été exécutée, mais uniquement qu'elle n'est plus en cours d'exécution.

Remarque : Certaines fonctions de wrapper gèrent les requêtes d'état de tâche à votre place. Par exemple, l'exécution de jobs.query permet de créer une tâche et d'interroger régulièrement l'état DONE pendant une période donnée.
Vérifiez que votre tâche a bien été exécutée. Si la propriété de la tâche est définie sur errorResult, la tâche a échoué. La propriété status.errorResult contient des informations décrivant les problèmes liés à la tâche dont l'exécution a échoué. Si la propriété status.errorResult est absente, la tâche a bien été exécutée. Toutefois, des erreurs non fatales, telles que des problèmes d'importation de lignes lors d'une tâche de chargement, ont pu se produire. Les erreurs non fatales sont renvoyées dans la liste status.errors de la tâche.

Exécuter des tâches à l'aide des bibliothèques clientes

Pour créer et exécuter une tâche à l'aide des bibliothèques clientes Google Cloud pour BigQuery, procédez comme suit :

C#

Avant d'essayer cet exemple, suivez les instructions de configuration pour C# du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour C#.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.


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

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Java.

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

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Python.

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))

Ajouter des libellés à une tâche

Vous pouvez ajouter des étiquettes aux jobs de requêtes via l'option --label de l'outil de ligne de commande bq. L'outil bq n'accepte l'ajout d'étiquettes que pour les jobs de requête.

Vous pouvez également ajouter un libellé à une tâche envoyée via l'API en spécifiant la propriété labels dans la configuration de la tâche lorsque vous appelez la méthode jobs.insert. L'API peut être utilisée pour ajouter des libellés à tout type de tâche.

Vous ne pouvez pas ajouter de libellés à des tâches en attente, en cours ou terminées (ni mettre à jour les libellés).

Lorsque vous ajoutez une étiquette à une tâche, celle-ci est incluse dans vos données de facturation.

Pour en savoir plus, consultez la section Ajouter des libellés à une tâche.

Étape suivante

Consultez la page Exécuter des requêtes pour obtenir un exemple de code qui démarre et interroge une tâche de requête.
Pour plus d'informations sur la création d'une représentation de ressource de tâche, consultez la page de présentation des tâches dans la documentation de référence de l'API.