Cloud Storage 전송

Cloud Storage용 BigQuery Data Transfer Service를 사용하면 Cloud Storage에서 BigQuery로 반복되는 데이터 로드를 예약할 수 있습니다.

시작하기 전에

Cloud Storage 전송을 만들기 전에 다음을 수행하세요.

제한사항

Cloud Storage에서 BigQuery로 반복되는 전송에는 다음과 같은 제한사항이 적용됩니다.

  • 전송에 와일드 카드 또는 런타임 매개변수로 정의한 패턴과 일치하는 모든 파일은 대상 테이블에 정의한 것과 동일한 스키마를 공유해야 합니다. 그렇지 않으면 전송이 실패합니다. 실행 사이에 테이블 스키마를 변경해도 전송이 실패합니다.
  • Cloud Storage 객체는 버전을 지정할 수 있으므로 보관처리된 Cloud Storage 객체는 BigQuery 전송에서 지원되지 않는다는 점에 유의해야 합니다. 객체를 전송하려면 활성 상태여야 합니다.
  • 지속적인 전송의 경우 Cloud Storage에서 BigQuery로 개별적으로 로드되는 데이터와 달리 전송을 설정하기 전에 대상 테이블과 스키마를 생성해야 합니다. BigQuery에서는 반복되는 데이터 전송 프로세스 중에 테이블을 만들 수 없습니다.
  • Cloud Storage에서 전송은 항상 대상 테이블에 데이터를 추가하는 WRITE_APPEND 환경설정으로 트리거됩니다. 자세한 내용은 JobConfigurationLoad 객체의 writeDisposition 필드 설명을 참조하세요.
  • 전송 중간에 Cloud Storage 파일이 조작되는 경우 BigQuery Data Transfer Service는 모든 파일이 전송되거나 한 번만 전송된다는 보장을 하지 않습니다.
  • 데이터세트 위치가 US 이외의 값으로 설정된 경우 리전별 또는 멀티 리전 Cloud Storage 버킷이 데이터세트와 동일한 리전에 있어야 합니다.
  • BigQuery Data Transfer Service는 외부 데이터 소스의 데이터 일관성을 보장하지 않습니다. 쿼리가 실행되는 동안 기본 데이터가 변경되면 예상치 못한 동작이 발생할 수 있습니다.

  • Cloud Storage 소스 데이터의 형식에 따라 추가 제한사항이 적용될 수 있습니다. 자세한 내용은 다음을 참조하세요.

  • Cloud Storage 버킷은 BigQuery에서 대상 데이터 세트의 리전 또는 멀티 리전과 호환되는 리전 또는 멀티 리전에 있어야 합니다. 이를 코로케이션이라고 합니다. 자세한 내용은 Cloud Storage 전송 데이터 위치를 참조하세요.

최소 간격

  • 전송하려는 Cloud Storage 소스 파일은 만든지 1시간 이상 지난 상태여야 합니다.
  • 반복 전송 사이의 최소 간격은 15분입니다. 반복 전송의 기본 간격은 24시간입니다.

필수 권한

BigQuery로 데이터를 로드할 때는 데이터를 신규 또는 기존 BigQuery 테이블과 파티션에 로드할 수 있는 권한이 있어야 합니다. Cloud Storage에서 데이터를 로드하는 경우에는 데이터가 포함된 버킷에 대한 액세스 권한도 필요합니다. 다음과 같은 필수 권한이 있는지 확인합니다.

  • BigQuery: 예약된 전송을 만들 수 있는 bigquery.transfers.update 권한이 필요합니다. 사전 정의된 IAM 역할 bigquery.admin에는 bigquery.transfers.update 권한이 있습니다. BigQuery Data Transfer Service의 IAM 역할에 대한 자세한 내용은 액세스 제어 참조를 확인하세요.
  • Cloud Storage: 개별 버킷에 대한 storage.objects.get 권한 또는 그 이상의 권한이 필요합니다. URI 와일드 카드를 사용 중인 경우에는 storage.objects.list 권한도 있어야 합니다. 전송에 성공할 때마다 소스 파일을 삭제하려는 경우에는 storage.objects.delete 권한도 필요합니다. 사전 정의된 IAM 역할 storage.objectAdmin에 이러한 모든 권한이 포함되어 있습니다.

Cloud Storage 전송 설정

BigQuery Data Transfer Service에서 Cloud Storage 전송을 만들려면 다음 안내를 따르세요.

Console

  1. Cloud Console에서 BigQuery 페이지로 이동합니다.

    BigQuery 페이지로 이동

  2. 전송을 클릭합니다.

  3. 만들기를 클릭합니다.

  4. 전송 만들기 페이지에서 다음을 수행합니다.

    • 소스 유형 섹션의 소스Cloud Storage를 선택합니다.

      전송 소스

    • 전송 구성 이름 섹션의 표시 이름에 전송 이름(예: My Transfer)을 입력합니다. 전송 이름은 나중에 수정해야 할 경우에 대비해 전송을 식별할 수 있는 값이면 됩니다.

      전송 이름

    • 일정 옵션 섹션의 일정에서 기본값(지금 시작)을 유지하거나 설정 시간에 시작을 클릭합니다.

      • 반복 빈도에서 전송을 실행할 빈도 옵션을 선택합니다. 최소 간격은 1시간입니다.
        • 매일(기본값)
        • 매주
        • 매월
        • 커스텀. 커스텀 일정에 커스텀 빈도를 입력합니다. 예를 들면 every day 00:00입니다. 일정 형식 지정을 참조하세요.
        • 주문형
      • 시작일 및 실행 시간에 전송을 시작할 날짜 및 시간을 입력합니다. 지금 시작을 선택하면 이 옵션은 사용 중지됩니다.

        전송 일정

    • 대상 설정 섹션의 대상 데이터세트에서 데이터를 저장하기 위해 만든 데이터세트를 선택합니다.

      전송 데이터세트

    • 데이터 소스 세부정보 섹션에서 다음을 수행합니다.

      • 대상 테이블에 대상 테이블 이름을 입력합니다. 대상 테이블은 테이블 이름 지정 규칙을 따라야 합니다. 대상 테이블 이름은 매개변수로도 지정할 수 있습니다.
      • Cloud Storage URICloud Storage URI를 입력합니다. 와일드 카드매개변수가 지원됩니다.
      • 쓰기 환경설정에서 다음을 선택합니다.

        • APPEND: 기존 대상 테이블에 새 데이터 추가 또는
        • MIRROR: 대상 테이블 내의 데이터를 새로고침하여 소스의 수정된 데이터를 반영. MIRROR는 대상 테이블의 새 데이터 복사본을 덮어씁니다.
      • 전송이 성공할 때마다 소스 파일을 삭제하려면 전송 후 소스 파일 삭제 체크박스를 선택합니다. 삭제 작업은 최선의 방식으로 실행됩니다. (소스 파일을 삭제하려는 첫 번째 시도가 실패한 경우 삭제 작업은 재시도되지 않습니다.)

      • 전송 옵션 섹션에서 다음을 수행합니다.

        • 모든 형식 아래에서 다음을 수행합니다.
          • 허용되는 오류 개수에 작업을 실행할 때 BigQuery가 무시할 수 있는 불량 레코드의 최댓값을 입력합니다. 불량 레코드 수가 이 값을 초과하면 작업 결과에 '잘못된' 오류가 반환되고 작업이 실패합니다. 기본값은 0입니다.
        • JSON, CSV 아래에서 다음을 수행합니다.
          • 전송 시 대상 테이블의 스키마와 맞지 않는 데이터를 삭제하려면 알 수 없는 값 무시 체크박스를 선택합니다.
        • CSV 아래에서 다음을 수행합니다.

          • 필드 구분 기호에 필드를 구분하는 문자를 입력합니다. 기본값은 쉼표입니다.
          • 건너뛸 헤더 행에 가져오지 않으려는 소스 파일의 헤더 행 수를 입력합니다. 기본값은 0입니다.
          • 따옴표가 있는 필드 안에서 줄바꿈을 허용하려면 따옴표 안에 줄바꿈 허용 체크박스를 선택합니다.
          • 누락된 NULLABLE 열이 있는 행을 전송하려면 불균일 행 허용 체크박스를 선택합니다.

      Cloud Storage 소스 세부정보

    • (선택사항) 알림 옵션 섹션에서 다음을 수행합니다.

      • 전환을 클릭해서 이메일 알림을 사용 설정합니다. 이 옵션을 사용 설정하면 전송 실행이 실패할 때 전송 관리자에게 이메일 알림이 발송됩니다.
      • Pub/Sub 주제 선택에서 주제 이름을 선택하거나 주제 만들기를 클릭합니다. 이 옵션은 전송에 대한 Pub/Sub 실행 알림을 구성합니다.
  5. 저장을 클릭합니다.

bq

bq mk 명령어를 입력하고 전송 생성 플래그 --transfer_config를 지정합니다. 다음 플래그도 필요합니다.

  • --data_source
  • --display_name
  • --target_dataset
  • --params
bq mk \
--transfer_config \
--project_id=project_id \
--data_source=data_source \
--display_name=name \
--target_dataset=dataset \
--params='parameters'

각 항목의 의미는 다음과 같습니다.

  • project_id는 프로젝트 ID입니다. 특정 프로젝트를 지정하는 --project_id가 입력되지 않으면 기본 프로젝트가 사용됩니다.
  • data_source는 데이터 소스(google_cloud_storage)입니다.
  • name은 전송 구성의 표시 이름입니다. 전송 이름은 나중에 수정해야 할 경우에 전송을 식별할 수 있는 값이면 됩니다.
  • dataset는 전송 구성 대상 데이터 세트입니다.
  • parameters에는 JSON 형식으로 생성된 전송 구성의 매개변수가 있습니다. 예를 들면 --params='{"param":"param_value"}'입니다.
    • Cloud Storage에서 data_path_template, destination_table_name_template, file_format 매개변수를 지정해야 합니다. data_path_template은 전송할 파일이 포함된 Cloud Storage URI로, 와일드 카드 1개를 포함할 수 있습니다. destination_table_name_template은 대상 테이블의 이름입니다. file_format에서 전송하려는 파일의 형식을 지정합니다(CSV, JSON, AVRO, PARQUET, ORC). 기본값은 CSV입니다.
    • 모든 file_format 값에 선택적 매개변수 max_bad_records를 포함할 수 있습니다. 기본값은 0입니다.
    • file_format의 JSON 또는 CSV 값에 선택적 매개변수 ignore_unknown_values를 포함할 수 있습니다. file_format으로 CSV 또는 JSON을 선택하지 않은 경우 이 매개변수는 무시됩니다.
    • CSV file_format에 필드를 구분하는 문자에 해당하는 선택적 매개변수 field_delimiter를 포함할 수 있습니다. 기본값은 쉼표입니다. file_formatCSV를 선택하지 않은 경우 이 매개변수가 무시됩니다.
    • CSV file_format에 가져오려는 헤더 행을 나타내는 선택적 매개변수 skip_leading_rows를 포함할 수 있습니다. 기본값은 0입니다. file_formatCSV를 선택하지 않은 경우 이 매개변수가 무시됩니다.
    • CSV file_format에서 따옴표가 있는 필드 내 줄바꿈을 허용하려면 선택적 매개변수 allow_quoted_newlines를 포함할 수 있습니다. file_formatCSV를 선택하지 않은 경우 이 매개변수가 무시됩니다.
    • CSV file_format에서 후행 선택 열이 누락된 행을 허용하려면 선택적 매개변수 allow_jagged_rows를 포함할 수 있습니다. 누락된 값은 NULL로 채워집니다. file_formatCSV를 선택하지 않은 경우 이 매개변수가 무시됩니다.
    • 전송이 성공할 때마다 선택적 매개변수 delete_source_files가 소스 파일을 삭제합니다. (소스 파일을 삭제하려는 첫 번째 시도가 실패한 경우 삭제 작업은 재시도되지 않습니다.) delete_source_files의 기본값은 false입니다.

예를 들어 다음 명령어는 gs://mybucket/myfile/*.csvdata_path_template 값, 대상 데이터 세트 mydataset, file_format CSV를 사용하여 My Transfer라는 Cloud Storage 전송을 만듭니다. 이 예시에는 CSV file_format과 연관된 선택적 매개변수의 기본값이 아닌 값이 포함되어 있습니다.

기본 프로젝트에 전송이 생성됩니다.

bq mk --transfer_config \
--target_dataset=mydataset \
--display_name='My Transfer' \
--params='{"data_path_template":"gs://mybucket/myfile/*.csv",
"destination_table_name_template":"MyTable",
"file_format":"CSV",
"max_bad_records":"1",
"ignore_unknown_values":"true",
"field_delimiter":"|",
"skip_leading_rows":"1",
"allow_quoted_newlines":"true",
"allow_jagged_rows":"false",
"delete_source_files":"true"}' \
--data_source=google_cloud_storage

명령어를 실행한 후 다음과 같은 메시지가 수신됩니다.

[URL omitted] Please copy and paste the above URL into your web browser and follow the instructions to retrieve an authentication code.

안내에 따라 인증 코드를 명령줄에 붙여넣습니다.

API

projects.locations.transferConfigs.create 메서드를 사용하고 TransferConfig 리소스의 인스턴스를 지정합니다.

자바

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create google cloud storage transfer config
public class CreateCloudStorageTransfer {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    String datasetId = "MY_DATASET_ID";
    String tableId = "MY_TABLE_ID";
    // GCS Uri
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
    String fileFormat = "CSV";
    String fieldDelimiter = ",";
    String skipLeadingRows = "1";
    Map<String, Value> params = new HashMap<>();
    params.put(
        "destination_table_name_template", Value.newBuilder().setStringValue(tableId).build());
    params.put("data_path_template", Value.newBuilder().setStringValue(sourceUri).build());
    params.put("write_disposition", Value.newBuilder().setStringValue("APPEND").build());
    params.put("file_format", Value.newBuilder().setStringValue(fileFormat).build());
    params.put("field_delimiter", Value.newBuilder().setStringValue(fieldDelimiter).build());
    params.put("skip_leading_rows", Value.newBuilder().setStringValue(skipLeadingRows).build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Google Cloud Storage Config Name")
            .setDataSourceId("google_cloud_storage")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createCloudStorageTransfer(projectId, transferConfig);
  }

  public static void createCloudStorageTransfer(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = client.createTransferConfig(request);
      System.out.println("Cloud storage transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Cloud storage transfer was not created." + ex.toString());
    }
  }
}

수동으로 전송 트리거

Cloud Storage에서 자동으로 예약된 전송 외에도 수동으로 추가 데이터 파일을 로드하는 전송을 트리거할 수 있습니다.

전송 구성이 런타임 매개변수화된 경우 추가 전송을 시작할 기간을 지정해야 합니다.

전송을 수동으로 트리거하려면 다음 안내를 따르세요.

Console

  1. Cloud Console에서 BigQuery 페이지로 이동합니다.

    BigQuery 페이지로 이동

  2. 데이터 전송을 클릭합니다.

  3. 원하는 전송을 클릭합니다.

  4. 지금 전송 실행 또는 백필 예약(런타임 매개변수화된 전송 구성)을 클릭합니다.

  5. 해당하는 경우 시작일종료일을 선택한 후 확인을 클릭하여 확인합니다.

    지금 전송 실행

    런타임 매개변수화된 전송 구성의 경우 백필 예약을 클릭하면 날짜 옵션이 표시됩니다.

    백필 예약

다음 단계