透過程式執行工作

如何使用 REST API 或用戶端程式庫,透過程式執行 BigQuery 工作:

  1. 呼叫 jobs.insert 方法。
  2. 定期要求工作資源並檢查狀態屬性,掌握工作完成時間。
  3. 確認工作是否順利完成。

事前準備

授予身分與存取權管理 (IAM) 角色,讓使用者擁有執行本文件各項工作所需的權限。

所需權限

如要執行 BigQuery 工作,您需要 bigquery.jobs.create IAM 權限。

下列預先定義的 IAM 角色都包含執行作業所需的權限:

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

此外,建立工作時,系統會自動授予您該工作的下列權限:

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

如要進一步瞭解 BigQuery 中的 IAM 角色和權限,請參閱預先定義的角色與權限一文。

執行中的工作

如何透過程式執行工作:

  1. 呼叫 jobs.insert 方法啟動工作。呼叫 jobs.insert 方法時,請加入工作資源表示法。

  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 參考說明文件

如要向 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 參考說明文件

如要向 BigQuery 進行驗證,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

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 參考說明文件

如要向 BigQuery 進行驗證,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

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 工具僅支援在查詢工作中加入標籤。

如果某個工作是透過 API 提交,您也可以在其中加入標籤,方法是當您呼叫 jobs.insert 方法時,在工作設定中指定 labels 屬性。API 可用於在任何工作類型中加入標籤。

您無法在待處理、執行中或已完成的工作中加入或更新標籤。

在工作中加入標籤後,標籤就會納入您的帳單資料中。

詳情請參閱「新增工作標籤」。

後續步驟

  • 如需啟動及輪詢查詢工作的程式碼範例,請參閱執行查詢一文。
  • 如要進一步瞭解如何建立工作資源表示法,請參閱 API 參考資料中的工作總覽頁面