Cloud Storage 전송

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

시작하기 전에

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

제한사항

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

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

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

필수 권한

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

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

Cloud Storage 전송 설정

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

콘솔

  1. BigQuery 웹 UI로 이동합니다.

    BigQuery 웹 UI로 이동

  2. 전송을 클릭합니다.

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

  4. 전송 만들기 페이지에서 다음 안내를 따릅니다.

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

      전송 소스

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

      전송 이름

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

      • 반복에서 전송을 실행하는 빈도 옵션을 선택합니다.
        • 일별(기본값)
        • 주별
        • 월별
        • 커스텀
        • 주문형
      • 시작일 및 실행 시간에 전송을 시작할 날짜 및 시간을 입력합니다. 지금 시작을 선택하면 이 옵션이 중지됩니다.

        전송 일정

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

      전송 데이터세트

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

      • 대상 테이블에 대상 테이블 이름을 입력합니다. 대상 테이블은 테이블 이름 지정 규칙을 따라야 합니다. 대상 테이블 이름은 매개변수도 지원합니다.
      • Cloud Storage URICloud Storage URI를 입력합니다. 와일드 카드매개변수가 지원됩니다.
      • 전송이 성공할 때마다 소스 파일을 삭제하려면 전송 후 소스 파일 삭제 체크박스를 선택합니다. 삭제 작업은 최선의 방식으로 실행됩니다. (소스 파일을 삭제하려는 첫 번째 시도가 실패한 경우 삭제 작업은 재시도되지 않습니다.)
      • 전송 옵션 섹션에서 다음을 수행합니다.

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

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

      Cloud Storage 소스 세부정보

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

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

기본 UI

  1. BigQuery 웹 UI로 이동합니다.

    BigQuery 웹 UI로 이동

  2. 전송을 클릭합니다.

  3. 전송 추가를 클릭합니다.

  4. 새 전송 페이지:

    • 소스에서 Cloud Storage를 선택합니다.
    • 표시 이름에 전송 이름을 입력합니다(예: My Transfer). 표시 이름은 나중에 수정해야 할 경우에 대비해 전송을 식별할 수 있는 값이면 됩니다.
    • (선택사항) 일정의 경우 기본값인 매일(만든 시간을 기준으로 24시간마다)을 그대로 두거나 수정을 클릭하여 시간을 변경합니다. 간격을 매주, 매월, 커스텀으로 변경할 수도 있습니다. 커스텀을 선택할 경우 크론과 유사한 방식으로 시간을 지정해야 합니다(예: every 12 hours). 지정할 수 있는 최단 시간은 12시간입니다. 그 밖의 유효한 API 값은 TransferConfig 아래의 schedule 필드를 참조하세요.

      전송 일정

    • 대상 데이터세트에서 적절한 데이터세트를 선택합니다.

    • 대상 테이블에 대상 테이블 이름을 입력합니다. 대상 테이블은 테이블 이름 지정 규칙을 따라야 합니다. 대상 테이블 이름은 매개변수도 지원합니다.

    • Cloud Storage URICloud Storage URI를 입력합니다. 와일드 카드매개변수가 지원됩니다.

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

    • 파일 형식에 전송할 파일 유형을 선택합니다.

    • 전송 옵션 - 모든 형식 섹션 아래에서 다음을 수행하세요.

      • 허용되는 오류 개수에 작업을 실행할 때 BigQuery가 무시할 수 있는 불량 레코드의 최댓값을 입력합니다. 불량 레코드 수가 이 값을 초과하면 작업 결과에 '잘못된' 오류가 반환되고 작업이 실패합니다. 기본값은 0입니다.
    • 전송 옵션 - JSON, CSV 섹션 아래에서 다음을 수행합니다.

      • 전송 시 대상 테이블의 스키마와 맞지 않는 데이터를 삭제하려면 알 수 없는 값 무시 체크박스를 선택합니다.
    • 전송 옵션 - CSV 섹션 아래에서 다음을 수행합니다.

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

      새 Cloud Storage 전송

    • (선택사항) 고급 섹션을 펼치면 전송의 실행 알림을 구성할 수 있습니다. 전송 실행 알림은 현재 알파 버전입니다.

    • Cloud Pub/Sub 주제에 Cloud Pub/Sub 주제 이름을 입력합니다(예: projects/myproject/topics/mytopic).

    • 전송 실행 실패 시 이메일 알림을 허용하려면 이메일 알림 보내기를 확인 표시합니다.

      Cloud Pub/Sub 주제

  5. 추가를 클릭합니다.

명령줄

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입니다.
  • --display_name은 전송 구성 표시 이름입니다. 전송 이름은 나중에 수정해야 할 경우에 전송을 식별할 수 있는 값이면 됩니다.
  • --target_dataset는 전송 구성 대상 데이터세트입니다.
  • --params에는 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입니다.
    • 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와 연관된 선택적 매개변수의 기본값이 아닌 값을 포함합니다.

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

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 리소스의 인스턴스를 제공합니다.

전송 새로고침 실행 설정

Cloud Storage에서 반복되는 전송을 설정하는 것 외에 추가 데이터 파일을 가져오도록 새로고침 실행도 설정할 수 있습니다.

전송 구성이 날짜와 관련(매개변수화)이 있거나, Cloud Storage URI가 매개변수화되었거나, 아니면 둘 다인 경우 특정 날짜에 전송을 실행할 수 있습니다.

새로고침 전송을 설정하려면 다음 안내를 따르세요.

콘솔

  1. GCP Console에서 BigQuery 웹 UI를 엽니다.

    BigQuery 웹 UI로 이동

  2. 전송을 클릭합니다.

  3. 전송을 클릭합니다.

  4. 더보기 메뉴를 클릭한 후 전송 새로고침을 선택합니다.

  5. 백필 실행 예약 대화상자에서 시작일종료일을 선택합니다. 기본 BigQuery 웹 UI를 사용하여 세부적인 시간 제한을 설정할 수 있습니다.

    새로고침 날짜 설정

기본 UI

  1. BigQuery 웹 UI로 이동합니다.

    BigQuery 웹 UI로 이동

  2. 전송을 클릭합니다.

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

  4. 전송 새로고침을 클릭합니다.

    전송 새로고침

  5. 전송 실행 시작 대화상자에서 시작 시간종료 시간을 선택합니다.

    새로고침 날짜 설정

    Cloud Storage 전송 구성이 매개변수화되지 않은 경우 전송 새로고침을 클릭할 때 날짜 옵션이 제공되지 않습니다. 대신에 새로고침이 즉시 수행됩니다.

    즉시 새로고침

  6. 확인을 클릭합니다.

다음 단계

이 페이지가 도움이 되었나요? 평가를 부탁드립니다.

다음에 대한 의견 보내기...

도움이 필요하시나요? 지원 페이지를 방문하세요.