プログラムでのジョブの実行

REST API ライブラリまたはクライアントライブラリを使用してプログラムで BigQuery ジョブを実行するには、次のようにします。

jobs.insert メソッドを呼び出す
定期的にジョブリソースをリクエストし、ステータスプロパティを調べて、ジョブの完了を確認する
ジョブが正常に終了したかどうかを確認する

始める前に

このドキュメントの各タスクを実行するために必要な権限をユーザーに与える Identity and Access Management（IAM）のロールを付与します。

必要な権限

BigQuery ジョブを実行するには、bigquery.jobs.create IAM 権限が必要です。

次の IAM 事前定義ロールには、ジョブの実行に必要な権限が含まれています。

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

また、ジョブを作成すると、そのジョブに対する次の権限が自動的に付与されます。

bigquery.jobs.get
bigquery.jobs.update

BigQuery での IAM のロールと権限については、事前定義ロールと権限をご覧ください。

実行中のジョブ

ジョブをプログラムで実行するには:

jobs.insert メソッドを呼び出してジョブを開始します。jobs.insert メソッドを呼び出す際に、ジョブリソース表現を含めます。
ジョブリソースの configuration セクションに、ジョブタイプ（load、query、extract、copy のいずれか）を指定する子プロパティを含めます。
jobs.insert メソッドを呼び出した後に、ジョブ ID とロケーションを指定して jobs.get を呼び出し、status.state の値を調べてジョブステータスを確認します。status.state が DONE である場合は、ジョブが実行を停止したことを示します。ただし、ステータス DONE は、必ずしもジョブが正常に完了したことを示しているのではなく、ジョブが実行されなくなったことを示しているにすぎません。

注: ジョブステータスリクエストを管理するラッパー関数がいくつかあります。たとえば、jobs.query を実行すると、ジョブが作成され、指定された期間だけ定期的に DONE ステータスがポーリングされます。
ジョブのステータスを確認します。ジョブに errorResult プロパティが存在する場合、そのジョブは失敗しています。status.errorResult プロパティには、ジョブの失敗原因を示す情報が含まれています。status.errorResult が存在しない場合、そのジョブは正常に完了したものの、読み込みジョブの一部の行のインポートで問題があったなど、致命的でないエラーが発生した可能性があることを示します。非致命的なエラーは、ジョブの status.errors リストで返されます。

クライアントライブラリを使用したジョブの実行

BigQuery 用の Cloud クライアントライブラリを使用してジョブを作成し、実行するには:

C#

このサンプルを試す前に、クライアントライブラリを使用した BigQuery クイックスタートにある C# の設定手順を完了してください。詳細については、BigQuery C# API のリファレンスドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアントライブラリの認証を設定するをご覧ください。


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

このサンプルを試す前に、クライアントライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、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

このサンプルを試す前に、クライアントライブラリを使用した BigQuery クイックスタートにある Python の設定手順を完了してください。詳細については、BigQuery 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))

ジョブラベルの追加

bq コマンドラインツールを使用してクエリジョブにラベルを追加するには、--label フラグを使用します。bq ツールは、クエリジョブにのみラベルの追加をサポートしています。

jobs.insert メソッドを呼び出すときにジョブ構成で labels プロパティを指定することで、API でジョブを送信する際にジョブにラベルを追加することもできます。API を使用すると、どのジョブタイプにもラベルを追加できます。

ジョブが保留中、実行中、完了済みの場合は、ラベルの追加や更新を行えません。

ジョブにラベルを追加すると、そのラベルが課金データとしてカウントされます。

詳細については、ジョブラベルの追加をご覧ください。

次のステップ

クエリジョブを開始してポーリングするコード例については、クエリを実行するをご覧ください。
ジョブリソース表現の作成の詳細については、API リファレンスのジョブ概要ページをご覧ください。