Executar tarefas programaticamente

Para executar uma tarefa do BigQuery programaticamente através da API REST ou das bibliotecas cliente:

1. Chame o método jobs.insert.
2. Peça periodicamente o recurso de trabalho e examine a propriedade de estado para saber quando o trabalho está concluído.
3. Verifique se a tarefa foi concluída com êxito.

Antes de começar

Conceda funções de gestão de identidade e acesso (IAM) que dão aos utilizadores as autorizações necessárias para realizar cada tarefa neste documento.

Autorizações necessárias

Para executar uma tarefa do BigQuery, precisa da autorização de IAM bigquery.jobs.create.

Cada uma das seguintes funções de IAM predefinidas inclui as autorizações de que precisa para executar uma tarefa:

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

Além disso, quando cria uma tarefa, são-lhe concedidas automaticamente as seguintes autorizações para essa tarefa:

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

Para mais informações sobre as funções e as autorizações do IAM no BigQuery, consulte o artigo Funções e autorizações predefinidas.

Executar tarefas

Para executar um trabalho de forma programática:

1. Inicie a tarefa chamando o método jobs.insert. Quando chamar o método jobs.insert, inclua uma representação do recurso de tarefa.

2. Na secção configuration do recurso de tarefa, inclua uma propriedade subordinada que especifique o tipo de tarefa: load, query, extract ou copy.

3. Depois de chamar o método jobs.insert, verifique o estado da tarefa chamando jobs.get com o ID da tarefa e a localização, e verifique o valor status.state para saber o estado da tarefa. Quando status.state é DONE, a tarefa deixou de ser executada. No entanto, um estado DONE não significa que a tarefa tenha sido concluída com êxito, apenas que já não está a ser executada.

   Nota: existem algumas funções de wrapper que gerem os pedidos de estado do trabalho por si. Por exemplo, a execução de jobs.query cria uma tarefa e verifica periodicamente o estado de DONE durante um período especificado.

4. Verifique se a tarefa foi bem-sucedida. Se a tarefa tiver uma propriedade errorResult, significa que falhou. A propriedade status.errorResult contém informações que descrevem o que correu mal num trabalho com falhas. Se status.errorResult estiver ausente, a tarefa foi concluída com êxito, embora possam ter ocorrido alguns erros não fatais, como problemas na importação de algumas linhas numa tarefa de carregamento. Os erros não fatais são devolvidos na lista status.errors do trabalho.

Executar tarefas com bibliotecas de cliente

Para criar e executar uma tarefa através das bibliotecas cliente do Google Cloud para o BigQuery:

C#

Antes de experimentar este exemplo, siga as C#instruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API C# BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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))

Adicionar etiquetas de trabalhos

Pode adicionar etiquetas a tarefas de consulta através da linha de comandos com a flag --label da ferramenta de linha de comandos bq. A ferramenta bq suporta a adição de etiquetas apenas a tarefas de consulta.

Também pode adicionar uma etiqueta a uma tarefa quando é enviada através da API especificando a propriedade labels na configuração da tarefa quando chama o método jobs.insert. A API pode ser usada para adicionar etiquetas a qualquer tipo de tarefa.

Não pode adicionar nem atualizar etiquetas em tarefas pendentes, em execução ou concluídas.

Quando adiciona uma etiqueta a um trabalho, a etiqueta é incluída nos seus dados de faturação.

Para mais informações, consulte o artigo Adicionar etiquetas de emprego.

O que se segue?

• Consulte o artigo Executar consultas para ver um exemplo de código que inicia e sonda uma tarefa de consulta.
• Para mais informações sobre como criar uma representação de recursos de trabalhos, consulte a página de vista geral de trabalhos na referência da API.