Ejecuta trabajos de manera programática

La API de REST y las bibliotecas cliente de BigQuery te permiten crear y administrar trabajos asíncronos para automatizar las operaciones de carga, consulta, extracción y copia desde tus aplicaciones. Después de iniciar un trabajo con una llamada al método jobs.insert, puedes sondear la propiedad de estado del recurso del trabajo para hacer un seguimiento de cuándo se completa la ejecución y confirmar si la operación se realizó correctamente.

Antes de comenzar

Otorga roles de Identity and Access Management (IAM) que les brindan a los usuarios los permisos necesarios para hacer cada tarea de este documento.

Permisos necesarios

Para ejecutar un trabajo de BigQuery, necesitas el permiso bigquery.jobs.create de IAM.

Cada una de las siguientes funciones predefinidas de IAM incluye los permisos que necesitas para ejecutar un trabajo:

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

Además, cuando creas un trabajo, se te otorgan los siguientes permisos de forma automática:

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

Para obtener más información sobre las funciones y los permisos de IAM en BigQuery, consulta Funciones y permisos predefinidos.

Ejecuta trabajos

Para ejecutar un trabajo de manera programática, haz lo siguiente:

  1. Para iniciar el trabajo, llama al método jobs.insert. Cuando llames al método jobs.insert, incluye una representación de recurso de trabajo.

  2. En la sección configuration del recurso de trabajo, incluye una propiedad secundaria que especifique el tipo de trabajo: load, query, extract o copy.

  3. Después de llamar al método jobs.insert, verifica el estado del trabajo llamando a jobs.get con el ID de tarea y la ubicación, y verifica el valor de status.state para conocer el estado del trabajo. Cuando status.state es DONE, el trabajo deja de ejecutarse; sin embargo, un estado DONE no significa que el trabajo se completó de forma correcta, solo que ya no se está ejecutando.

  4. Comprueba si el trabajo se realizó de forma correcta. Si el trabajo tiene una propiedad errorResult, significa que el trabajo falló. La propiedad status.errorResult contiene información que describe lo que salió mal en un trabajo con errores. Si status.errorResult está ausente, el trabajo se completó de forma correcta, aunque puede haber algunos errores recuperables, como problemas cuando se importan algunas filas. Los errores recuperables se muestran en la lista status.errors del trabajo.

Ejecuta trabajos mediante bibliotecas cliente

Si quieres crear y ejecutar un trabajo mediante las bibliotecas cliente de Cloud para BigQuery, haz lo siguiente:

C#

Antes de probar este ejemplo, sigue las instrucciones de configuración para C# incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para C#.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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 probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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 probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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))

Agrega etiquetas de trabajo

Se pueden agregar etiquetas a los trabajos de consulta con la marca --label en la herramienta de línea de comandos de bq. La herramienta bq admite que se agreguen etiquetas solo a trabajos de consulta.

También puedes agregar una etiqueta a un trabajo cuando se envía a través de la API si especificas la propiedad labels en la configuración del trabajo cuando llamas al método jobs.insert. La API se puede usar para agregar etiquetas a cualquier tipo de trabajo.

No puedes agregar ni actualizar etiquetas en trabajos pendientes, en ejecución o completados.

Cuando agregas una etiqueta a un trabajo, la etiqueta se incluye en tus datos de facturación.

Para obtener más información, consulta Agrega etiquetas de trabajo.

¿Qué sigue?