Blob Storage 전송

Azure Blob Storage용 BigQuery Data Transfer Service를 사용하면 Blob Storage에서 BigQuery로 반복되는 로드 작업을 자동으로 예약하고 관리할 수 있습니다.

시작하기 전에

Blob Storage 전송을 만들기 전에 다음을 수행합니다.

BigQuery Data Transfer Service 사용 설정에 필요한 모든 작업을 완료했는지 확인합니다.
기존 BigQuery 데이터 세트를 선택하거나 데이터를 저장할 새 데이터 세트를 만듭니다.
전송하려는 기존 BigQuery 테이블을 선택하거나 새 대상 테이블을 만들고 스키마 정의를 지정합니다. 대상 테이블은 테이블 이름 지정 규칙을 따라야 합니다. 대상 테이블 이름은 매개변수로도 지정할 수 있습니다.
Blob Storage 스토리지 계정 이름, 컨테이너 이름, 데이터 경로(선택사항), SAS 토큰을 검색합니다. 공유 액세스 서명(SAS)을 사용하여 Blob Storage에 대한 액세스 권한을 부여하는 방법은 공유 액세스 서명(SAS)을 참조하세요.
Azure Storage 방화벽을 사용하여 Azure 리소스에 대한 액세스를 제한하는 경우 허용된 IP 목록에 BigQuery Data Transfer Service 작업자를 추가합니다.
고객 관리 암호화 키(CMEK)를 지정하려는 경우 서비스 계정에 암호화 및 복호화 권한이 있어야하며, Cloud KMS 키 리소스 ID가 필요합니다. CMEK가 BigQuery Data Transfer Service에서 작동하는 방식에 대한 자세한 내용은 전송에 암호화 키 지정을 참조하세요.

필수 권한

Blob 스토리지 전송을 만들려면 bigquery.transfers.update Identity and Access Management(IAM) 권한이 필요합니다. 또한 대상 데이터 세트에 대한 bigquery.datasets.get 및 bigquery.datasets.update 권한이 필요합니다.

사전 정의된 bigquery.admin IAM 역할에는 Blob Storage 전송을 만드는 데 필요한 권한이 포함되어 있습니다.

BigQuery IAM에 대한 자세한 내용은 IAM으로 액세스 제어를 참조하세요.

Blob Storage에서 전송을 사용 설정하기 위한 올바른 권한이 있는지 확인하려면 공유 액세스 서명(SAS)을 참조하세요.

Pub/Sub의 전송 실행 알림을 설정하려면 pubsub.topics.setIamPolicy 권한이 있어야 합니다. 이메일 알림만 받는 경우에는 Pub/Sub 권한은 필요 없습니다. 자세한 내용은 BigQuery Data Transfer Service 실행 알림을 참조하세요.

제한사항

Blob Storage 전송에는 다음과 같은 제한사항이 적용됩니다.

반복 전송 사이의 최소 간격은 1시간입니다. 기본 간격은 24시간입니다.
Blob Storage 소스 데이터의 형식에 따라 추가 제한사항이 적용될 수 있습니다.
BigQuery Omni 위치로의 전송은 지원되지 않습니다.

Blob Storage 데이터 전송 설정

다음 옵션 중 하나를 선택합니다.

콘솔

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

BigQuery로 이동
BigQuery 탐색 메뉴에서 데이터 전송을 클릭합니다.
전송 만들기를 클릭합니다.
전송 만들기 페이지에서 다음을 수행합니다.
- 소스 유형 섹션의 소스에서 Azure Blob Storage를 선택합니다.
- 전송 구성 이름 섹션의 표시 이름에 전송 이름을 입력합니다.
- 일정 옵션 섹션에서 다음을 수행합니다.
  - 반복 빈도를 선택합니다. 시간, 일, 주 또는 월을 선택하면 빈도도 지정해야 합니다. 커스텀을 선택하여 커스텀 반복 빈도를 지정할 수도 있습니다. 주문형을 선택한 경우 수동으로 전송을 트리거하면 이 전송이 실행됩니다.
  - 해당하는 경우 지금 시작 또는 설정 시간에 시작을 선택하고 시작 날짜와 실행 시간을 제공합니다.
- 대상 설정 섹션의 데이터 세트에서 데이터를 저장하기 위해 만든 데이터 세트를 선택합니다.
- 데이터 소스 세부정보 섹션에서 다음을 수행합니다.
  - 대상 테이블에 BigQuery에 데이터를 저장하기 위해 만든 테이블의 이름을 입력합니다. 대상 테이블 이름은 매개변수로 지정할 수 있습니다.
  - Azure 스토리지 계정 이름에 Blob 스토리지 계정 이름을 입력합니다.
  - 컨테이너 이름에 Blob Storage 컨테이너 이름을 입력합니다.
  - 데이터 경로에 전송할 파일을 필터링할 경로를 입력합니다. 예시 보기
  - SAS 토큰에 Azure SAS 토큰을 입력합니다.
  - 파일 형식에서 소스 데이터 형식을 선택합니다.
  - 쓰기 처리에서 대상 테이블에 새 데이터를 증분식으로 추가하려면 WRITE_APPEND를 선택하고 전송을 실행할 때마다 대상 테이블의 데이터를 덮어쓰려면 WRITE_TRUNCATE를 선택합니다. WRITE_APPEND는 쓰기 처리의 기본값입니다.
  BigQuery Data Transfer Service가 WRITE_APPEND 또는 WRITE_TRUNCATE를 사용하여 데이터를 수집하는 방법에 대한 자세한 내용은 Amazon Blob 전송을 위한 데이터 수집을 참조하세요. writeDisposition 필드에 대한 자세한 내용은 JobConfigurationLoad를 참조하세요.
- 전송 옵션 섹션에서 다음을 수행합니다.
  - 허용되는 오류 개수에 무시할 수 있는 최대 오류 레코드 수를 정수 값으로 입력합니다. 기본값은 0입니다.
  - (선택사항) 십진수 타겟 유형에 소스 데이터의 십진수 값이 변환되는 가능한 SQL 데이터 유형의 쉼표로 구분된 목록을 입력합니다. 변환에 적합한 SQL 데이터 유형은 다음 조건에 따라 달라집니다.
    - NUMERIC, BIGNUMERIC, STRING 순서의 경우 지정된 목록에 포함되고 정밀도와 규모를 지원하면 유형이 선택됩니다.
    - 나열된 데이터 유형이 정밀도 및 소수 자릿수를 지원하지 않는 경우 지정된 목록에서 가장 넓은 범위를 지원하는 데이터 유형이 선택됩니다. 소스 데이터를 읽을 때 값이 지원되는 범위를 초과하면 오류가 발생합니다.
    - 데이터 유형 STRING은 모든 정밀도 및 규모 값을 지원합니다.
    - 이 필드를 비워 두면 데이터 유형은 기본적으로 숫자, ORC의 경우 NUMERIC,STRING, 기타 파일 형식의 경우 NUMERIC으로 설정됩니다.
    - 이 필드에 중복된 데이터 유형이 있으면 안 됩니다.
    - 나열하는 데이터 유형의 순서는 무시됩니다.
- 파일 형식으로 CSV 또는 JSON을 선택한 경우, JSON, CSV 섹션에서 알 수 없는 값 무시를 선택하면 스키마와 일치하지 않는 값이 포함된 행이 허용됩니다.
- 파일 형식으로 CSV를 선택한 경우, CSV 섹션에 데이터 로드와 관련된 추가 CSV 옵션을 입력합니다.
- 알림 옵션 섹션에서 이메일 알림 및 Pub/Sub 알림을 사용 설정할 수 있습니다.
  - 이메일 알림을 사용 설정하면 전송 실행이 실패할 때 전송 관리자에게 이메일 알림이 발송됩니다.
  - Pub/Sub 알림을 사용 설정하면 게시할 주제 이름을 선택하거나 주제 만들기를 클릭하여 만듭니다.
- CMEK를 사용하는 경우 고급 옵션 섹션에서 고객 관리 키를 선택합니다. 선택할 수 있는 CMEK 목록이 표시됩니다. CMEK가 BigQuery Data Transfer Service에서 작동하는 방식에 대한 자세한 내용은 전송에 암호화 키 지정을 참조하세요.
저장을 클릭합니다.

bq

bq mk --transfer_config 명령어를 사용하여 Blob Storage 전송을 만듭니다.

bq mk \
  --transfer_config \
  --project_id=PROJECT_ID \
  --data_source=DATA_SOURCE \
  --display_name=DISPLAY_NAME \
  --target_dataset=DATASET \
  --destination_kms_key=DESTINATION_KEY \
  --params=PARAMETERS

다음을 바꿉니다.

PROJECT_ID: (선택사항) 대상 데이터 세트가 포함된 프로젝트 ID입니다. 지정하지 않으면 기본 프로젝트가 사용됩니다.
DATA_SOURCE: azure_blob_storage.
DISPLAY_NAME: 전송 구성의 표시 이름입니다. 전송 이름은 나중에 수정해야 할 경우에 전송을 쉽게 식별할 수 있는 값이면 됩니다.
DATASET. 전송 구성의 대상 데이터 세트입니다.
DESTINATION_KEY: (선택사항) Cloud KMS 키 리소스 ID입니다(예: projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name).
PARAMETERS: JSON 형식으로 나열된 전송 구성의 매개변수입니다. 예를 들면 --params={"param1":"value1", "param2":"value2"}입니다. 다음은 Blob Storage 전송의 매개변수입니다.
- destination_table_name_template: 필수. 대상 테이블의 이름입니다.
- storage_account: 필수. Blob Storage 계정 이름입니다.
- container: 필수. Blob Storage 컨테이너 이름입니다.
- data_path: 선택사항. 전송할 파일을 필터링하는 경로입니다. 예시 보기
- sas_token: 필수. Azure SAS 토큰
- file_format: 선택사항. 전송할 파일 유형(CSV, JSON, AVRO, PARQUET 또는 ORC)을 나타냅니다. 기본값은 CSV입니다.
- write_disposition: 선택사항. WRITE_APPEND를 선택하여 대상 테이블에 데이터를 추가하거나 WRITE_TRUNCATE를 선택하여 대상 테이블의 데이터를 덮어씁니다. 기본값은 WRITE_APPEND입니다.
- max_bad_records: 선택사항. 허용되는 불량 레코드 수입니다. 기본값은 0입니다.
- decimal_target_types: 선택사항. 소스 데이터의 십진수 값이 변환되는 가능한 SQL 데이터 유형의 쉼표로 구분된 목록입니다. 이 필드가 제공되지 않은 경우 데이터 유형이 기본적으로 ORC의 경우 NUMERIC,STRING으로, 다른 파일 형식의 경우 NUMERIC으로 설정됩니다.
- ignore_unknown_values: 선택사항이며 file_format이 JSON 또는 CSV가 아닌 경우 무시됩니다. 스키마와 일치하지 않는 값이 포함된 행을 허용하려면 true로 설정합니다.
- field_delimiter: 선택사항이며 file_format이 CSV인 경우에만 적용됩니다. 필드를 구분하는 문자입니다. 기본값은 ,입니다.
- skip_leading_rows: 선택사항이며 file_format이 CSV인 경우에만 적용됩니다. 가져오지 않으려는 헤더 행 수를 나타냅니다. 기본값은 0입니다.
- allow_quoted_newlines: 선택사항이며 file_format이 CSV인 경우에만 적용됩니다. 따옴표가 있는 필드 안에서 줄바꿈을 허용할지 여부를 나타냅니다.
- allow_jagged_rows: 선택사항이며 file_format이 CSV인 경우에만 적용됩니다. 뒤에 오는 선택적인 열이 누락된 행을 허용할지 여부를 나타냅니다. 누락된 값은 NULL로 채워집니다.

예를 들어 다음은 mytransfer이라는 Blob Storage 전송을 만듭니다.

bq mk \
  --transfer_config \
  --data_source=azure_blob_storage \
  --display_name=mytransfer \
  --target_dataset=mydataset \
  --destination_kms_key=projects/myproject/locations/us/keyRings/mykeyring/cryptoKeys/key1
  --params={"destination_table_name_template":"mytable",
      "storage_account":"myaccount",
      "container":"mycontainer",
      "data_path":"myfolder/*.csv",
      "sas_token":"my_sas_token_value",
      "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"}

Java

이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.


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 azure blob storage transfer config.
public class CreateAzureBlobStorageTransfer {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    final String displayName = "MY_TRANSFER_DISPLAY_NAME";
    final String datasetId = "MY_DATASET_ID";
    String tableId = "MY_TABLE_ID";
    String storageAccount = "MY_AZURE_STORAGE_ACCOUNT_NAME";
    String containerName = "MY_AZURE_CONTAINER_NAME";
    String dataPath = "MY_AZURE_FILE_NAME_OR_PREFIX";
    String sasToken = "MY_AZURE_SAS_TOKEN";
    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("storage_account", Value.newBuilder().setStringValue(storageAccount).build());
    params.put("container", Value.newBuilder().setStringValue(containerName).build());
    params.put("data_path", Value.newBuilder().setStringValue(dataPath).build());
    params.put("sas_token", Value.newBuilder().setStringValue(sasToken).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());
    createAzureBlobStorageTransfer(projectId, displayName, datasetId, params);
  }

  public static void createAzureBlobStorageTransfer(
      String projectId, String displayName, String datasetId, Map<String, Value> params)
      throws IOException {
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName(displayName)
            .setDataSourceId("azure_blob_storage")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    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("Azure Blob Storage transfer created successfully: " + config.getName());
    } catch (ApiException ex) {
      System.out.print("Azure Blob Storage transfer was not created." + ex.toString());
    }
  }
}

전송을 통한 암호화 키 지정

고객 관리 암호화 키(CMEK)를 지정하여 전송 실행의 데이터를 암호화할 수 있습니다. CMEK를 사용하여 Azure Blob Storage에서의 전송을 지원할 수 있습니다.

전송에 CMEK를 지정하면 BigQuery Data Transfer Service는 CMEK를 수집된 데이터의 모든 중간 디스크 캐시에 적용하여 전체 데이터 전송 워크플로가 CMEK를 준수하도록 합니다.

원래 CMEK를 사용해 생성되지 않은 전송의 경우 기존 전송을 업데이트하여 CMEK를 추가할 수 없습니다. 예를 들어 원래 기본적으로 암호화된 대상 테이블을 지금 CMEK로 암호화되도록 변경할 수 없습니다. 반대로 CMEK로 암호화된 대상 테이블을 다른 유형의 암호화가 적용되도록 변경할 수도 없습니다.

전송 구성이 원래 CMEK 암호화를 사용하여 생성된 경우 전송에 대해 CMEK를 업데이트할 수 있습니다. 전송 구성에 대해 CMEK를 업데이트하면 BigQuery Data Transfer Service는 전송의 다음 실행 시 CMEK를 대상 테이블에 전파하는데, 여기서 BigQuery Data Transfer Service는 전송 실행 중 오래된 CMEK를 새 CMEK로 대체합니다. 자세한 내용은 전송 업데이트를 참조하세요.

프로젝트 기본 키를 사용할 수도 있습니다. 전송에 프로젝트 기본 키를 지정하면 BigQuery Data Transfer Service는 프로젝트 기본 키를 새 전송 구성의 기본 키로 사용합니다.

전송 설정 문제 해결

전송을 설정하는 데 문제가 있으면 Blob Storage 전송 문제를 참조하세요.

다음 단계

전송의 런타임 매개변수 자세히 알아보기
BigQuery Data Transfer Service 자세히 알아보기
교차 클라우드 작업으로 데이터를 로드하는 방법을 알아보세요.