以编程方式运行作业

如需使用 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 调用的重试操作安全可靠。

      例如:

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

  2. 在作业资源的 configuration 部分中,添加一个用于指定作业类型(loadqueryextractcopy)的子属性。

  3. 调用 jobs.insert 方法之后,通过调用 jobs.get 并提供作业 ID 和位置来检查作业状态,另外还应检查 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,BigQuery 会为您创建一个作业 ID,但在调用返回之前,您无法检查该作业的状态。同样,您可能很难判断该作业是否已成功插入。如果您使用自己的任务 ID,则可以随时检查作业状态,并且可以重试相同的任务 ID,以确保作业只启动一次。

任务 ID 是一个字符串,由字母(a-z、A-Z)、数字 (0-9)、下划线 (_) 或短划线 (-) 组成,最大长度是 1024 个字符。作业 ID 在项目中必须是独一无二的。

为了生成独一无二的作业 ID,一种常用方法就是使用人类可读的前缀和由时间戳或 GUID 构成的后缀。例如:daily_import_job_1447971251

您可以在 Python UUID 模块中找到生成 GUID 的一个方法的示例。 如需查看将 Python uuid4() 方法与 jobs.insert 配合使用的示例,请参阅从 Cloud Storage 加载数据

后续步骤

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