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 auf.
  2. Fordern Sie regelmäßig die Jobressource an und prüfen Sie das Statusattribut, um festzustellen, ob der Job abgeschlossen ist.
  3. Prüfen Sie, ob der Job erfolgreich beendet wurde.

Hinweis

Erteilen Sie IAM-Rollen (Identity and Access Management), die Nutzern die erforderlichen Berechtigungen zum Ausführen der einzelnen Aufgaben in diesem Dokument geben.

Erforderliche Berechtigungen

Zum Ausführen eines BigQuery-Jobs benötigen Sie die IAM-Berechtigung bigquery.jobs.create.

Jede der folgenden vordefinierten IAM-Rollen enthält die Berechtigungen, die Sie zum Ausführen eines Jobs benötigen:

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

Wenn Sie einen Job erstellen, erhalten Sie außerdem automatisch die folgenden Berechtigungen für diesen Job:

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

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.

  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 ausprobieren, folgen Sie der C#-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery C# API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.


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 ausprobieren, folgen Sie der Java-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Java API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

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 ausprobieren, folgen Sie der Python-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Python API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

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

Joblabels hinzufügen

Mit dem --label-Flag des bq-Befehlszeilentools können Labels zu Abfragejobs über die Befehlszeile hinzugefügt werden. Mit dem bq-Tool können Labels nur Abfragejobs hinzugefügt werden.

Sie können einem Job auch ein Label hinzufügen, wenn er über die API übertragen wird. Geben Sie dazu in der Jobkonfiguration das Attribut labels an, wenn Sie die Methode jobs.insert aufrufen. Über die API können Labels beliebigen Jobtypen hinzugefügt werden.

Sie können keine Labels zu ausstehenden, laufenden oder abgeschlossenen Jobs hinzufügen oder für derartige Jobs aktualisieren.

Wenn Sie einem Job ein Label hinzufügen, wird das Label in Ihre Abrechnungsdaten einbezogen.

Weitere Informationen finden Sie unter Joblabels hinzufügen.

Nächste Schritte