Menjalankan tugas secara terprogram

Untuk menjalankan tugas BigQuery secara terprogram menggunakan REST API atau library klien, Anda:

Panggil metode jobs.insert.
Minta resource tugas secara berkala dan periksa properti status untuk mengetahui kapan tugas selesai.
Periksa apakah tugas berhasil diselesaikan.

Sebelum memulai

Berikan peran Identity and Access Management (IAM) yang memberi pengguna izin yang diperlukan untuk melakukan setiap tugas dalam dokumen ini.

Izin yang diperlukan

Untuk menjalankan tugas BigQuery, Anda memerlukan izin IAM bigquery.jobs.create.

Setiap peran IAM yang telah ditetapkan berikut menyertakan izin yang Anda perlukan untuk menjalankan tugas:

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

Selain itu, saat membuat tugas, Anda otomatis diberi izin berikut untuk tugas tersebut:

bigquery.jobs.get
bigquery.jobs.update

Untuk informasi lebih lanjut tentang peran dan izin IAM di BigQuery, lihat Peran dan izin bawaan.

Tugas yang berjalan

Untuk menjalankan tugas secara terprogram:

Mulai tugas dengan memanggil metode jobs.insert. Saat Anda memanggil metode jobs.insert, sertakan representasi resource tugas.
Di bagian configuration pada resource tugas, sertakan properti turunan yang menentukan jenis tugas, yaitu load, query, extract, atau copy.
Setelah memanggil metode jobs.insert, periksa status tugas dengan memanggil jobs.get menggunakan ID tugas dan lokasi, lalu periksa nilai status.state untuk melihat status tugas. Jika status.state adalah DONE, tugas telah berhenti berjalan. Namun, status DONE tidak berarti tugas berhasil diselesaikan, hanya saja tugas tersebut tidak lagi berjalan.

Catatan: Ada beberapa fungsi wrapper yang mengelola permintaan status tugas untuk Anda. Misalnya, menjalankan jobs.query akan membuat tugas dan secara berkala melakukan polling untuk status DONE selama jangka waktu tertentu.
Memeriksa keberhasilan tugas. Tugas gagal diselesaikan jika memiliki properti errorResult. Properti status.errorResult menyimpan informasi yang menjelaskan kesalahan dalam tugas yang gagal. Jika status.errorResult tidak ada, tugas berhasil diselesaikan, meskipun mungkin ada beberapa error tidak fatal, seperti masalah saat mengimpor beberapa baris dalam tugas pemuatan. Error tidak fatal ditampilkan dalam daftar status.errors tugas.

Menjalankan tugas menggunakan library klien

Untuk membuat dan menjalankan tugas menggunakan Library Klien Cloud untuk BigQuery:

C#

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C# di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery C# API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.


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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Java API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Python API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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))

Menambahkan label tugas

Label dapat ditambahkan ke tugas kueri melalui command line menggunakan flag --label pada alat command line bq. Alat bq mendukung penambahan label hanya ke tugas kueri.

Anda juga dapat menambahkan label ke tugas saat dikirim melalui API dengan menentukan properti labels dalam konfigurasi tugas saat Anda memanggil metode jobs.insert. API ini dapat digunakan untuk menambahkan label ke jenis tugas apa pun.

Anda tidak dapat menambahkan label ke atau memperbarui label pada tugas yang tertunda, sedang berjalan, atau telah selesai.

Saat Anda menambahkan label ke pekerjaan, label tersebut akan disertakan dalam data penagihan Anda.

Untuk informasi selengkapnya, lihat Menambahkan label tugas.

Langkah selanjutnya

Lihat Menjalankan kueri untuk contoh kode yang memulai dan melakukan polling tugas kueri.
Untuk informasi selengkapnya tentang cara membuat representasi resource tugas, lihat halaman ringkasan Tugas dalam referensi API.