以编程方式运行作业

如需使用 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 方法之后，通过调用 jobs.get 并提供作业 ID 和位置来检查作业状态，另外还应检查 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 参考文档。

如需向 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 标志。bp 工具仅支持向查询作业添加标签。

您也可以在通过 API 提交作业时为该作业添加标签，具体做法是调用 jobs.insert 方法并在作业配置中指定 labels 属性。API 支持为任何类型的作业添加标签。

您不能为待处理、正在运行或已完成的作业添加标签或更新标签。

向作业添加标签后，标签会包含在您的结算数据中。

如需了解详情，请参阅添加作业标签。

后续步骤

请参阅运行查询中展示如何启动和轮询查询作业的代码示例。
如需详细了解如何创建作业资源表示法，请参阅 API 参考中的作业概览页。