Jobs programmatisch ausführen

So führen Sie einen BigQuery-Job mithilfe der REST API oder der Clientbibliotheken programmatisch aus:

  1. Rufen Sie die Methode jobs.insert mit einer eindeutigen Job-ID auf, die von Ihrem Client-Code generiert wird
  2. Fordern Sie regelmäßig die Jobressource an und prüfen Sie das Statusattribut, um festzustellen, ob der Job abgeschlossen ist.
  3. Überprüfen Sie, ob der Job erfolgreich beendet wurde.

Erforderliche Berechtigungen

Zum Ausführen von BigQuery-Jobs brauchen Sie mindestens Berechtigungen des Typs bigquery.jobs.create. Die folgenden vordefinierten IAM-Rollen enthalten bigquery.jobs.create-Berechtigungen:

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

Weitere Informationen zu IAM-Rollen und Berechtigungen in BigQuery finden Sie unter Vordefinierte Rollen und Berechtigungen.

Aktive Jobs

So führen Sie einen Job programmatisch aus:

  1. Starten Sie den Job durch einen Aufruf der Methode jobs.insert. Nehmen Sie in den Aufruf der Methode jobs.insert eine Jobressourcendarstellung auf, die Folgendes enthält:

    • Ihren Standort im Abschnitt jobReference des Attributs location.
    • Die Job-ID, die von Ihrem Clientcode generiert wurde. Wenn Sie diesen Schritt auslassen, generiert der Server eine Job-ID für Sie. Es empfiehlt sich aber, die ID auf Clientseite zu generieren, damit der jobs.insert-Aufruf zuverlässig wiederholt werden kann.

      Beispiel:

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

  2. Fügen Sie im Abschnitt configuration der Jobressource ein untergeordnetes Attribut hinzu, das den Jobtyp angibt – load, query, extract oder copy.

  3. Prüfen Sie nach dem Aufrufen der Methode jobs.insert den Jobstatus durch einen Aufruf von jobs.get mit der Job-ID und dem Standort. Prüfen Sie den Wert status.state, um den Jobstatus zu ermitteln. Wenn für status.state der Status DONE angezeigt wird, wurde die Ausführung des Jobs beendet. Der Status DONE bedeutet jedoch nicht, dass der Job erfolgreich abgeschlossen wurde. Er zeigt lediglich an, dass er nicht weiter ausgeführt wird.

  4. Prüfen Sie, ob der Job erfolgreich abgeschlossen wurde. Weist der Job das Attribut errorResult auf, ist er fehlgeschlagen. Das Attribut status.errorResult enthält dann Informationen über das Fehlschlagen des Jobs. Ist das Attribut status.errorResult nicht vorhanden, wurde der Job erfolgreich abgeschlossen, obwohl einige nicht schwerwiegende Fehler aufgetreten sein können, z. B. Probleme beim Importieren einiger Zeilen eines Ladejobs. Nicht schwerwiegende Fehler werden in der Liste status.errors des Jobs zurückgegeben.

Jobs mit Clientbibliotheken ausführen

So erstellen und führen Sie einen Job mit den Cloud-Clientbibliotheken für BigQuery aus:

C#

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von C# in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur BigQuery C# API.


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

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Java in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur BigQuery Java API.

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

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Python in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur  Python API.

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

Job-ID erzeugen

Es hat sich bewährt, eine Job-ID unter Verwendung des Clientcodes zu erzeugen und diese Job-ID beim Aufruf von jobs.insert zu senden. Wenn Sie jobs.insert aufrufen, ohne eine Job-ID anzugeben, erstellt BigQuery eine Job-ID für Sie. Sie können den Status dieses Jobs dann aber erst prüfen, wenn der Aufruf wiederkehrt. Außerdem könnte es schwierig sein, festzustellen, ob der Job erfolgreich eingefügt wurde. Bei Verwendung Ihrer eigenen Job-ID können Sie den Status des Jobs jederzeit überprüfen und das Ausführen derselben Job-ID wiederholen, um sicherzustellen, dass der Job genau einmal gestartet wird.

Die Job-ID besteht aus einer Reihe von Buchstaben (a-z, A-Z), Ziffern (0-9), Unterstrichen (_) oder Bindestrichen (-) und hat eine maximale Länge von 1.024 Zeichen. Die Job-IDs innerhalb eines Projekts müssen eindeutig sein.

Eine übliche Vorgehensweise zum Erzeugen einer eindeutigen Job-ID besteht darin, ein menschenlesbares Präfix und ein Suffix zu verwenden, das aus einem Zeitstempel oder einer GUID besteht. Beispiel: daily_import_job_1447971251.

Ein Beispiel für eine Methode zum Erzeugen von GUIDs finden Sie im Python UUID-Modul. Ein Beispiel für die Verwendung der Python-Methode uuid4() mit jobs.insert finden Sie unter Daten aus Cloud Storage laden.

Tipp