Ejecuta trabajos de manera programática

Para ejecutar un trabajo de BigQuery de manera programática mediante la API de REST o bibliotecas cliente, debes hacer lo siguiente:

  1. Llama al método jobs.insert con un ID de trabajo único que generó el código de cliente
  2. De manera periódica, solicita el recurso de trabajo y examina la propiedad de estado para saber cuándo se completa el trabajo.
  3. Comprueba si el trabajo finalizó de forma correcta.

Permisos necesarios

Como mínimo, para ejecutar trabajos de BigQuery, debes tener permisos bigquery.jobs.create. Las siguientes funciones predefinidas de IAM incluyen los permisos bigquery.jobs.create:

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

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 que contenga lo siguiente:

    • La ubicación en la propiedad location de la sección jobReference
    • El ID de trabajo que generó tu código de cliente. El servidor genera un ID de trabajo si lo omites, pero es una práctica recomendada generar el ID del trabajo en el lado del cliente para permitir un reintento confiable de la llamada jobs.insert.

      Por ejemplo:

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

  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 mediante una llamada a jobs.get con el ID y la ubicación del trabajo, y verifica el valor 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. Si deseas obtener más información, consulta la documentación de referencia de la API de BigQuery para 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 probar este ejemplo, sigue las instrucciones de configuración para Java que se encuentran en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de BigQuery para 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 probar esta muestra, 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. Si deseas obtener más información, consulta la documentación de referencia de la API de BigQuery para 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))

Genera un ID de trabajo

Se recomienda generar un ID de trabajo mediante el código de cliente y enviar ese ID de trabajo cuando llames a jobs.insert. Si llamas a jobs.insert sin especificar un ID de trabajo, BigQuery creará un ID de trabajo por ti, pero no podrás verificar el estado de ese trabajo hasta que regrese la llamada. Además, puede ser difícil saber si el trabajo se insertó con éxito. Si usas tu propio ID de trabajo, puedes verificar su estado en cualquier momento y puedes volver a intentarlo con el mismo ID de trabajo para asegurarte de que el trabajo se inicie exactamente una vez.

El ID de trabajo es una string que consta de letras (a-z, A-Z), números (0-9), guiones bajos (_) o guiones (-) con una longitud máxima de 1,024 caracteres. Los ID de trabajo deben ser únicos en un proyecto.

Un enfoque común para generar un ID de trabajo único es usar un prefijo y un sufijo legibles que consisten en una marca de tiempo o un GUID. Por ejemplo: daily_import_job_1447971251

Se puede encontrar un ejemplo de un método que genera GUID en el módulo UUID de Python. Para ver un ejemplo de uso del método uuid4() de Python con jobs.insert, consulta la sección sobre cómo cargar datos desde Cloud Storage.

Próximos pasos