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

다음과 같은 방법으로 REST API나 클라이언트 라이브러리를 사용하여 프로그래매틱 방식으로 BigQuery 작업을 실행할 수 있습니다.

  1. 클라이언트 코드에서 생성된 고유한 작업 ID를 사용하여 jobs.insert 메서드 호출
  2. 주기적으로 작업 리소스를 요청하고 상태 속성을 검토하여 작업 완료 시기 확인
  3. 작업이 성공적으로 완료되었는지 확인

필수 권한

BigQuery 작업을 실행하려면 최소한 bigquery.jobs.create 권한을 부여받아야 합니다. 다음과 같은 사전 정의된 Cloud IAM 역할에는 bigquery.jobs.create 권한이 포함되어 있습니다.

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

BigQuery의 Cloud IAM 역할 및 권한에 대한 자세한 내용은 사전 정의된 역할 및 권한을 참조하세요.

작업 실행

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

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

    • jobReference 섹션의 location 속성 위치
    • 클라이언트 코드에서 생성한 작업 ID. 작업 ID를 생략하면 서버에서 자동으로 생성되지만 jobs.insert 호출을 안정적으로 재시도할 수 있도록 클라이언트 측에서 작업 ID를 생성하는 것이 좋습니다.

      예:

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

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

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

  4. 작업 성공 여부를 확인합니다. 작업에 errorResult 속성이 있으면 작업이 실패한 것입니다. status.errorResult 속성에는 작업이 실패한 원인을 설명하는 정보가 포함되어 있습니다. status.errorResult가 없으면 작업은 성공적으로 완료되었지만 로드 작업 시 일부 행을 가져오지 못하는 등 심각하지 않은 오류가 발생했을 수 있다는 의미입니다. 심각하지 않은 오류는 작업의 status.errors 목록에 반환됩니다.

Python을 사용하여 작업 실행

Python을 사용하여 작업을 만들고 실행하려면 다음 단계를 따르세요.

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), 밑줄(_) 또는 대시(-)로 구성된 문자열이며 최대 1,024자가 허용됩니다. 작업 ID는 프로젝트 내에서 고유해야 합니다.

고유한 작업 ID를 생성하는 일반적인 방법은 타임스탬프 또는 GUID로 구성되고 사람이 읽을 수 있는 프리픽스와 서픽스를 사용하는 것입니다(예: daily_import_job_1447971251).

GUID를 생성하는 메서드의 예시는 Python UUID 모듈을 참조하세요. Python uuid4() 메서드를 jobs.insert와 함께 사용하는 예시는 Cloud Storage에서 데이터 로드를 참조하세요.

다음 단계

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