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:

  1. Chame o método jobs.insert usando um ID de job exclusivo gerado pelo código de cliente.
  2. Solicite periodicamente o recurso do job e examine a property do status para saber se o job foi concluído.
  3. Verifique se o job foi concluído com sucesso.

Permissões necessárias

Para executar jobs do BigQuery, é necessário ter, no mínimo, as permissões bigquery.jobs.create. Os seguintes papéis predefinidos do IAM incluem as permissões bigquery.jobs.create:

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

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:

  1. Inicie o job chamando o método jobs.insert. Ao chamar o método jobs.insert, inclua uma representação do recurso do job que contenha:

    • Seu local na property location na seção jobReference.
    • O ID de job gerado pelo código do cliente. O servidor gera um ID de job se você o omitir, mas gerar o ID do job no lado do cliente para permitir novas tentativas confiáveis da chamada jobs.insert é uma prática recomendada.

      Por exemplo:

      {
        "jobReference": {
          "projectId": "my_project",
          "jobId": "job_123",
          “location”: “asia-northeast1”
        },
        "configuration":
        {
          // ..
        },
      }
      

  2. Na seção configuration do recurso do job, inclua uma property filha que especifique o tipo de job: load, query, extract ou copy.

  3. 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.

  4. 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 essa amostra, siga as instruções de configuração para 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#.


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 essa amostra, siga as instruções de configuração para 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.

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 essa amostra, siga as instruções de configuração para 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.

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

Gerar um ID de job

Como prática recomendada, gere um ID de job usando o código de cliente e envie esse ID de job ao chamar jobs.insert. Se você chamar jobs.insert sem especificar um ID de job, o BigQuery criará um ID, mas não será possível verificar o status dele até o retorno da chamada. Além disso, talvez fique difícil saber se o job foi inserido com sucesso. Com um ID de job próprio, é possível verificar o status dele a qualquer momento e tentar novamente com esse mesmo ID para garantir que ele inicie exatamente uma vez.

O ID de job é uma string que contém letras (a-z, A-Z), números (0-9), sublinhados (_) ou traços (-), com tamanho máximo de 1.024 caracteres. É necessário que os IDs de job sejam exclusivos em um projeto.

Uma abordagem comum para gerar um ID de job exclusivo é usar um prefixo legível por humanos e um sufixo que consiste em um carimbo de data/hora ou em um GUID. Por exemplo: daily_import_job_1447971251.

O módulo UUID do Python (em inglês) traz um exemplo de método para gerar GUIDs. Para um exemplo de como usar o método uuid4() de Python com jobs.insert, consulte Como carregar dados do Cloud Storage.

Próximas etapas

  • 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.