Cloud Storage 전송

콘솔

1. Google Cloud 콘솔의 데이터 전송 페이지로 이동합니다.

   데이터 전송으로 이동

2. add 전송 만들기를 클릭합니다.

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

   

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

   

5. 일정 옵션 섹션에서 다음을 수행합니다.

   • 반복 빈도를 선택합니다. 시간, 일, 주 또는 월을 선택하면 빈도도 지정해야 합니다. 커스텀을 선택하여 커스텀 반복 빈도를 지정할 수도 있습니다. 주문형을 선택한 경우 수동으로 전송을 트리거하면 이 데이터 전송이 실행됩니다.

   • 해당하는 경우 지금 시작 또는 설정 시간에 시작을 선택하고 시작 날짜와 실행 시간을 제공합니다.

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

   

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

   1. 대상 테이블에 대상 테이블 이름을 입력합니다. 대상 테이블은 테이블 이름 지정 규칙을 따라야 합니다. 대상 테이블 이름은 매개변수로도 지정할 수 있습니다.
   2. Cloud Storage URI에 Cloud Storage URI를 입력합니다. 와일드 카드 및 매개변수가 지원됩니다.
   3. 쓰기 환경설정에서 다음을 선택합니다.
      • APPEND: 기존 대상 테이블에 새 데이터를 증분식으로 추가합니다. APPEND는 쓰기 환경설정의 기본값입니다.
      • MIRROR: 각 데이터 전송 실행 중에 대상 테이블의 데이터를 덮어씁니다.

   BigQuery Data Transfer Service가 APPEND 또는 MIRROR를 사용하여 데이터를 수집하는 방법에 대한 자세한 내용은 Cloud Storage 전송을 위한 데이터 수집을 참조하세요. writeDisposition 필드에 대한 자세한 내용은 JobConfigurationLoad를 참조하세요.

   1. 데이터 전송이 성공할 때마다 소스 파일을 삭제하려면 전송 후 소스 파일 삭제 체크박스를 선택합니다. 삭제 작업은 최선의 방식으로 실행됩니다. 소스 파일을 삭제하려는 첫 번째 시도가 실패한 경우 삭제 작업은 재시도되지 않습니다.

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

      1. 모든 형식 아래에서 다음을 수행합니다.
         1. 허용되는 오류 개수에 작업을 실행할 때 BigQuery가 무시할 수 있는 불량 레코드의 최댓값을 입력합니다. 불량 레코드 수가 이 값을 초과하면 작업 결과에 '잘못된' 오류가 반환되고 작업이 실패합니다. 기본값은 0입니다.
         2. (선택사항) 십진수 타겟 유형에 소스 십진수 값을 변환할 수 있는 가능한 SQL 데이터 유형의 쉼표로 구분된 목록을 입력합니다. 변환에 적합한 SQL 데이터 유형은 다음 조건에 따라 달라집니다.
            • 변환에 사용되는 데이터 유형은 다음 목록에서 소스 데이터의 정밀도 및 규모를 지원하는 첫 번째 데이터 유형이 됩니다. 순서는 NUMERIC, BIGNUMERIC, STRING입니다.
            • 나열된 데이터 유형이 정밀도 및 규모를 지원하지 않는 경우 지정된 목록에서 가장 넓은 범위를 지원하는 데이터 유형이 선택됩니다. 소스 데이터를 읽을 때 값이 지원되는 범위를 초과하면 오류가 발생합니다.
            • 데이터 유형 STRING은 모든 정밀도 및 규모 값을 지원합니다.
            • 이 필드를 비워두면 데이터 유형은 기본적으로 ORC의 경우 "NUMERIC,STRING", 다른 파일 형식의 경우 "NUMERIC"으로 설정됩니다.
            • 이 필드에 중복된 데이터 유형이 있으면 안 됩니다.
            • 이 필드에 나열하는 데이터 유형의 순서는 무시됩니다.
      2. JSON, CSV 아래에서 다음을 수행합니다.
         • 데이터 전송 시 대상 테이블의 스키마와 맞지 않는 데이터를 삭제하려면 알 수 없는 값 무시 체크박스를 선택합니다.
      3. AVRO에서 다음을 수행합니다.
         • 데이터 전송에서 Avro 논리 유형을 해당하는 BigQuery 데이터 유형으로 변환하려면 avro 논리 유형 사용 체크박스를 선택합니다. 기본 동작은 대부분의 유형에 대해 logicalType 속성을 무시하고 대신 기본 Avro 유형을 사용합니다.

      4. CSV 아래에서 다음을 수행합니다.

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

8. 서비스 계정 메뉴에서 Google Cloud 프로젝트와 연결된 서비스 계정의 서비스 계정을 선택합니다. 사용자 인증 정보를 사용하는 대신 서비스 계정을 데이터 전송에 연결할 수 있습니다. 데이터 전송에서 서비스 계정을 사용하는 방법에 대한 자세한 내용은 서비스 계정 사용을 참조하세요.

   • 제휴 ID로 로그인한 경우 서비스 계정이 데이터 전송을 만드는 데 필요합니다. Google 계정으로 로그인한 경우 데이터 전송에 사용되는 서비스 계정은 선택사항입니다.
   • 서비스 계정에는 BigQuery 및 Cloud Storage에 대한 필수 권한이 있어야 합니다.

9. 선택사항: 알림 옵션 섹션에서 다음을 수행합니다.

   1. 전환을 클릭하여 이메일 알림을 사용 설정합니다. 이 옵션을 사용 설정하면 전송 실행이 실패할 때 데이터 전송 구성의 소유자에게 이메일 알림이 발송됩니다.
   2. Pub/Sub 주제 선택에서 주제 이름을 선택하거나 주제 만들기를 클릭합니다. 이 옵션은 전송에 대한 Pub/Sub 실행 알림을 구성합니다.

10. 선택사항: 고급 옵션 섹션에서 다음을 수행합니다.

    • CMEK를 사용하는 경우 고객 관리 키를 선택합니다. 선택할 수 있는 CMEK 목록이 표시됩니다.

    CMEK가 BigQuery Data Transfer Service에서 작동하는 방식에 대한 자세한 내용은 전송에 암호화 키 지정을 참조하세요.

11. 저장을 클릭합니다.

bq

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

• --data_source
• --display_name
• --target_dataset
• --params

선택적 플래그:

• --destination_kms_key: 이 데이터 전송에 고객 관리 암호화 키(CMEK)를 사용하는 경우 Cloud KMS 키의 키 리소스 ID를 지정합니다. CMEK가 BigQuery Data Transfer Service에서 작동하는 방식에 대한 자세한 내용은 전송에 암호화 키 지정을 참조하세요.
• --service_account_name - 사용자 계정 대신 Cloud Storage 전송 인증에 사용할 서비스 계정을 지정합니다.

bq mk \
--transfer_config \
--project_id=PROJECT_ID \
--data_source=DATA_SOURCE \
--display_name=NAME \
--target_dataset=DATASET \
--destination_kms_key="DESTINATION_KEY" \
--params='PARAMETERS' \
--service_account_name=SERVICE_ACCOUNT_NAME

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

• PROJECT_ID는 프로젝트 ID입니다. 특정 프로젝트를 지정하는 --project_id가 입력되지 않으면 기본 프로젝트가 사용됩니다.
• DATA_SOURCE는 데이터 소스입니다(예: google_cloud_storage).
• NAME은 데이터 전송 구성의 표시 이름입니다. 전송 이름은 나중에 수정해야 할 경우를 대비해 전송을 식별할 수 있는 값이면 됩니다.
• DATASET는 전송 구성 대상 데이터 세트입니다.
• DESTINATION_KEY: Cloud KMS 키 리소스 ID입니다(예: projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name).
• PARAMETERS에는 JSON 형식으로 생성된 전송 구성의 매개변수가 있습니다. 예를 들면 --params='{"param":"param_value"}'입니다.
  • destination_table_name_template: 대상 BigQuery 테이블의 이름입니다.
  • data_path_template: 전송할 파일이 포함된 Cloud Storage URI입니다. 와일드 카드 1개를 포함할 수 있습니다.
  • write_disposition: 일치하는 파일이 대상 테이블에 추가되는지 또는 전체적으로 미러링되는지 결정합니다. 지원되는 값은 APPEND 또는 MIRROR입니다. BigQuery Data Transfer Service가 Cloud Storage 전송에서 데이터를 추가하거나 미러링하는 방법은 Cloud Storage 전송을 위한 데이터 수집을 참조하세요.
  • file_format: 전송할 파일의 형식입니다. 형식은 CSV, JSON, AVRO, PARQUET, ORC입니다. 기본값은 CSV입니다.
  • max_bad_records: 모든 file_format 값에 대해 무시할 수 있는 잘못된 레코드의 최대 개수입니다. 기본값은 0입니다.
  • decimal_target_types: 모든 file_format 값에 대해 소스 십진수 값을 변환할 수 있는 가능한 SQL 데이터 유형의 쉼표로 구분된 목록입니다. 이 필드가 제공되지 않은 경우 데이터 유형이 기본적으로 "NUMERIC,STRING"(ORC) 및 "NUMERIC"(다른 파일 형식)으로 설정됩니다.
  • ignore_unknown_values: 모든 file_format 값에 대해 스키마와 일치하지 않는 값이 포함된 행을 수락하도록 TRUE로 설정합니다. 자세한 내용은 JobConfigurationLoad 참조 테이블에서 ignoreUnknownvalues 필드 세부정보를 참조하세요.
  • use_avro_logical_types: AVRO file_format 값에 대해 원시 유형만 사용하는 대신(예: INTEGER) 논리적 유형을 해당 유형으로 해석하도록(예: TIMESTAMP) TRUE로 설정합니다.
  • parquet_enum_as_string: PARQUET file_format 값의 경우 PARQUET ENUM 논리적 유형을 기본 BYTES 대신 STRING으로 유추하도록 TRUE로 설정합니다.
  • parquet_enable_list_inference: PARQUET file_format 값의 경우 특히 PARQUET LIST 논리적 유형에 대해 스키마 추론을 사용하도록 TRUE로 설정합니다.
  • reference_file_schema_uri: 읽기 스키마가 있는 참조 파일에 대한 URI 경로입니다.
  • field_delimiter: CSV file_format 값의 경우 필드를 구분하는 문자입니다. 기본값은 쉼표입니다.
  • quote: CSV file_format 값의 경우 CSV 파일에서 데이터 섹션을 인용하는 데 사용되는 문자입니다. 기본값은 큰 따옴표(")입니다.
  • skip_leading_rows: CSV file_format 값의 경우 가져오지 않으려는 선행 헤더 행의 수를 나타냅니다. 기본값은 0입니다.
  • allow_quoted_newlines: CSV file_format 값의 경우 인용된 필드 내의 줄바꿈을 허용하도록 TRUE로 설정합니다.
  • allow_jagged_rows : CSV file_format 값의 경우 선택적인 후행 열이 누락된 행을 수락하도록 TRUE로 설정합니다. 누락된 값은 NULL로 채워집니다.
  • preserve_ascii_control_characters: CSV file_format 값의 경우 임베딩된 ASCII 제어 문자를 보존하도록 TRUE로 설정합니다.
  • encoding: CSV 인코딩 유형을 지정합니다. 지원되는 값은 UTF8, ISO_8859_1, UTF16BE, UTF16LE, UTF32BE, UTF32LE입니다.
  • delete_source_files: 각 전송이 성공한 후 소스 파일을 삭제하도록 TRUE로 설정합니다. 소스 파일을 삭제하려는 첫 번째 시도가 실패할 경우 삭제 작업이 다시 실행되지 않습니다. 기본값은 FALSE입니다.
• SERVICE_ACCOUNT_NAME은 전송을 인증하는 데 사용되는 서비스 계정 이름입니다. 서비스 계정은 전송을 만드는 데 사용한 것과 동일한 project_id가 소유해야 하며 모든 필수 권한이 있어야 합니다.

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

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

bq mk --transfer_config \
--target_dataset=mydataset \
--project_id=myProject \
--display_name='My Transfer' \
--destination_kms_key=projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey \
--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":"|",
"quote":";",
"skip_leading_rows":"1",
"allow_quoted_newlines":"true",
"allow_jagged_rows":"false",
"delete_source_files":"true"}' \
--data_source=google_cloud_storage \
--service_account_name=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com projects/862514376110/locations/us/transferConfigs/ 5dd12f26-0000-262f-bc38-089e0820fe38

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

[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());
    }
  }
}

콘솔

1. Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.

   BigQuery 페이지로 이동

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

3. 목록에서 데이터 전송을 선택합니다.

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

   • 지금 전송 실행을 클릭한 경우 일회성 전송 실행 또는 특정 날짜에 실행(해당하는 경우)을 선택합니다. 특정 날짜에 실행을 선택한 경우 특정 날짜와 시간을 선택합니다.

     

   • 백필 예약을 클릭한 경우 일회성 전송 실행 또는 특정 기간에 실행(해당하는 경우)을 선택합니다. 기간 실행을 선택한 경우 시작 및 종료 날짜와 시간을 선택합니다.

     

5. 확인을 클릭합니다.

bq

bq mk 명령어를 입력하고 --transfer_run 플래그를 제공합니다. --run_time 플래그 또는 --start_time 및 --end_time 플래그를 사용할 수 있습니다.

bq mk \
--transfer_run \
--start_time='START_TIME' \
--end_time='END_TIME' \
RESOURCE_NAME

bq mk \
--transfer_run \
--run_time='RUN_TIME' \
RESOURCE_NAME

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

• START_TIME과 END_TIME은 Z로 끝나거나 유효한 시간대 오프셋을 포함하는 타임스탬프입니다. 예를 들면 다음과 같습니다.

  • 2017-08-19T12:11:35.00Z
  • 2017-05-25T00:00:00+00:00

• RUN_TIME은 데이터 전송 실행을 예약할 시간을 지정하는 타임스탬프입니다. 현재 시간으로 일회성 전송을 실행하려면 --run_time 플래그를 사용하면 됩니다.

• RESOURCE_NAME은 전송 리소스 이름(또는 전송 구성이라고 함)입니다(예: projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7). 전송의 리소스 이름을 모르면 bq ls --transfer_config --transfer_location=LOCATION 명령어를 실행하여 리소스 이름을 찾습니다.

API

projects.locations.transferConfigs.startManualRuns 메서드를 사용하고 parent 매개변수를 사용하여 전송 구성 리소스를 제공합니다.