Como executar jobs de maneira programática

Para executar um job do BigQuery com programação usando a API REST ou as bibliotecas de cliente, faça o seguinte:

Chame o método jobs.insert.
Solicite periodicamente o recurso do job e examine a property do status para saber se o job foi concluído.
Verifique se o job foi concluído com sucesso.

Antes de começar

Atribua papéis do Identity and Access Management (IAM) que concedam aos usuários as permissões necessárias para realizar cada tarefa deste documento.

Permissões necessárias

Para executar um job do BigQuery, você precisa da permissão do IAM bigquery.jobs.create.

Cada um dos papéis predefinidos do IAM a seguir inclui as permissões necessárias para executar um job:

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

Além disso, ao criar um job, você recebe automaticamente as seguintes permissões para ele:

bigquery.jobs.get
bigquery.jobs.update

Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Como executar jobs

Para executar um job de maneira programática:

Inicie o job chamando o método jobs.insert. Ao chamar o método jobs.insert, inclua uma representação de recurso de job.
Na seção configuration do recurso do job, inclua uma property filha que especifique o tipo de job: — load, query, extract, ou copy.
Depois de chamar o método jobs.insert, verifique o status do job chamando jobs.get com o ID e o local do job. Depois, verifique o valor status.state para saber o status do job. Quando status.state for DONE, a execução do job estará parada. No entanto, um status DONE não significa que o job foi concluído com êxito, apenas que ele não está mais em execução.

Observação: algumas funções do wrapper gerenciam solicitações de status do job para você. Por exemplo, executar jobs.query cria um job e periodicamente busca o status DONE por um período especificado.
Verifique o êxito do job. Se o job tiver uma property errorResult, ele falhou. A property status.errorResult contém informações que descrevem o que deu errado em um job que falhou. Se não houver status.errorResult, o job foi concluído com êxito, embora talvez tenha havido alguns erros não fatais, como problemas na importação de algumas linhas em um job de carregamento. Erros não fatais são retornados na lista status.errors do job.

Como executar jobs usando bibliotecas de cliente

Para criar e executar um job usando as bibliotecas de cliente do Cloud para BigQuery:

C#

Antes de testar esta amostra, siga as instruções de configuração do C# no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em C#.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.


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

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Como adicionar rótulos a jobs

Rótulos podem ser adicionados aos jobs de consulta pela linha de comando com a sinalização --label da ferramenta de linha de comando bq. A ferramenta bq permite a adição de rótulos apenas aos jobs de consulta.

Quando um job é enviado pela API, é possível adicionar um rótulo a ele ao especificar a property labels na configuração do job quando você chamar o método jobs.insert. A API pode ser usada para adicionar rótulos a qualquer tipo de job.

Não é possível adicionar ou atualizar rótulos em jobs pendentes, em execução ou concluídos.

Ao adicionar um rótulo a um job, o rótulo é incluído nos seus dados de faturamento.

Para mais informações, consulte Como adicionar rótulos de job.

A seguir

Consulte Como executar consultas para um exemplo de código que inicie e pesquise um job de consulta.
Para mais informações sobre como criar uma representação de recurso do job, consulte a página Visão geral dos jobs na referência da API.