프로그래매틱 방식으로 작업 실행

REST API나 클라이언트 라이브러리를 사용하여 프로그래매틱 방식으로 BigQuery 작업을 실행하려면 다음 안내를 따르세요.

1. jobs.insert 메서드를 호출합니다.
2. 주기적으로 작업 리소스를 요청하고 상태 속성을 검토하여 작업 완료 시기 확인
3. 작업이 성공적으로 완료되었는지 확인

시작하기 전에

사용자에게 이 문서의 각 작업을 수행하는 데 필요한 권한을 부여하는 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 역할과 권한에 대한 자세한 내용은 사전 정의된 역할 및 권한을 참조하세요.

작업 실행

프로그래매틱 방식으로 작업을 실행하는 방법은 다음과 같습니다.

1. jobs.insert 메서드를 호출하여 작업을 시작합니다. jobs.insert 메서드를 호출할 때 작업 리소스 표현을 포함합니다.

2. 작업 리소스의 configuration 섹션에서 load, query, extract 또는 copy와 같은 작업 유형을 지정하는 하위 속성을 포함합니다.

3. jobs.insert 메서드를 호출한 후에는 작업 ID와 위치로 jobs.get을 호출하여 작업 상태를 확인하고 status.state 값을 확인하여 작업 상태를 확인합니다. status.state가 DONE이면 작업 실행이 중지된 것입니다. 하지만 DONE 상태는 작업이 성공적으로 완료되었다는 것이 아니라 더 이상 실행되지 않는다는 의미입니다.

   참고: 사용자의 작업 상태 요청을 관리하는 래퍼 함수도 있습니다. 예를 들어 jobs.query를 실행하면 작업이 생성되고 지정된 시간 동안 주기적으로 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 도구는 쿼리 작업에만 라벨 추가를 지원합니다.

또한 jobs.insert 메서드를 호출할 때 작업 구성에서 labels 속성을 지정하면 API를 통해 작업을 제출할 때 작업에 라벨을 추가할 수 있습니다. API를 사용하면 모든 작업 유형에 라벨을 추가할 수 있습니다.

대기 중이거나 실행 중이거나 완료된 작업에는 라벨을 추가하거나 업데이트할 수 없습니다.

작업에 라벨을 추가하면 라벨이 결제 데이터에 포함됩니다.

자세한 내용은 작업 라벨 추가를 참조하세요.

다음 단계

• 쿼리 작업을 시작하고 폴링하는 코드의 예시는 쿼리 실행을 참조하세요.
• 작업 리소스 표현 작성에 대한 자세한 내용은 API 참조의 작업 개요 페이지를 참조하세요.