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

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

  1. クライアント コードによって生成された一意のジョブ ID を使用して、jobs.insert メソッドを呼び出す
  2. 定期的にジョブリソースをリクエストし、ステータス プロパティを調べて、ジョブの完了を確認する
  3. ジョブが正常に終了したかどうかを確認します

必要な権限

BigQuery ジョブを実行するには、少なくとも bigquery.jobs.create 権限が付与されている必要があります。次の IAM 事前定義ロールには bigquery.jobs.create 権限が含まれています。

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

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

実行中のジョブ

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

  1. jobs.insert メソッドを呼び出してジョブを開始します。jobs.insert メソッドを呼び出す際に、以下を含むジョブリソース表現を含めます。

    • jobReference セクションの location プロパティに指定されたロケーション。
    • クライアント コードによって生成されたジョブ ID。ジョブ ID を省略した場合、ジョブ ID はサーバーにより生成されますが、jobs.insert の呼び出しを確実に再試行できるように、クライアント側でジョブ ID を生成することをおすすめします。

      例:

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

  2. ジョブリソースの configuration セクションに、ジョブタイプ(loadqueryextractcopy のいずれか)を指定する子プロパティを含めます。

  3. jobs.insert メソッドを呼び出した後に、ジョブ ID とロケーションを指定して jobs.get を呼び出し、status.state の値を調べてジョブ ステータスを確認します。status.stateDONE である場合は、ジョブが実行を停止したことを示します。ただし、ステータス DONE は、必ずしもジョブが正常に完了したことを示しているのではなく、ジョブが実行されなくなったことを示しているにすぎません。

  4. ジョブのステータスを確認します。ジョブに errorResult プロパティが存在する場合、そのジョブは失敗しています。status.errorResult プロパティには、ジョブの失敗原因を示す情報が含まれています。status.errorResult が存在しない場合、そのジョブは正常に完了したものの、読み込みジョブの一部の行のインポートで問題があったなど、致命的でないエラーが発生した可能性があることを示します。非致命的なエラーは、ジョブの status.errors リストで返されます。

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

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

C#

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

このサンプルを試す前に、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))

ジョブ ID の生成

ベスト プラクティスとして、ジョブ ID は、クライアント コードを使用して生成します。jobs.insert の呼び出し時に、そのジョブ ID を送信します。ジョブ ID を指定せずに jobs.insert を呼び出した場合、ジョブ ID は BigQuery により作成されますが、呼び出しが戻るまでそのジョブのステータスを確認できません。また、ジョブが正常に挿入されたかどうかの確認が難しくなる可能性があります。独自のジョブ ID を使用すると、ジョブのステータスをいつでも確認でき、再試行時に同じジョブ ID を使用してジョブが正確に 1 回だけ開始されるようにすることができます。

ジョブ ID はアルファベット(a~z、A~Z)、数字(0~9)、アンダースコア(_)、ダッシュ(-)で構成される文字列で、最大長は 1,024 文字です。ジョブ ID はプロジェクト内で一意であることが必要です。

一意のジョブ ID を生成する一般的なアプローチは、タイムスタンプや GUID で構成された、人が読める形式の接頭辞または接尾辞を付ける方法です。例: daily_import_job_1447971251

GUID を生成する方法の例については、Python UUID モジュールをご覧ください。Python uuid4() メソッドを jobs.insert とともに使用する方法の例については、Cloud Storage からのデータの読み込みをご覧ください。

次のステップ

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