BigQuery 배치 소스

이 페이지에서는 Cloud Data Fusion에서 BigQuery 배치 소스 플러그인을 구성하는 방법을 안내합니다.

BigQuery 소스 플러그인을 사용하면 BigQuery 테이블에서 데이터를 연결하고 로드할 수 있습니다. BigQuery 테이블의 데이터는 Cloud Storage의 임시 위치로 내보내진 후 여기에서 파이프라인으로 읽히게 됩니다.

시작하기 전에

Cloud Data Fusion에는 일반적으로 두 개의 서비스 계정이 있습니다.

• 설계 시점 서비스 계정: Cloud Data Fusion API 서비스 에이전트
• 실행 시간 서비스 계정: Compute Engine 서비스 계정

BigQuery 배치 소스 플러그인을 사용하기 전에 각 서비스 계정에 다음 역할 또는 권한을 부여합니다.

Cloud Data Fusion API 서비스 에이전트

이 서비스 계정에는 이미 필요한 모든 권한이 있으므로 추가 권한을 추가할 필요가 없습니다. 참고로, 여기에는 다음 권한이 포함됩니다.

• bigquery.datasets.get
• bigquery.tables.create
• bigquery.tables.get
• bigquery.tables.updateData
• bigquery.tables.update
• bigquery.tables.export

기본 설계 시 서비스 계정 외에 네임스페이스 서비스 계정을 사용하는 경우 이전 목록의 권한을 추가하세요.

Compute Engine 서비스 계정

Google Cloud 프로젝트에서 Compute Engine 서비스 계정에 다음 IAM 역할 또는 권한을 부여합니다.

• BigQuery 작업 사용자(roles/bigquery.jobUser). 이 사전 정의된 역할에는 필요한 bigquery.jobs.create 권한이 포함되어 있습니다.

• BigQuery 데이터 편집자(roles/bigquery.dataEditor). 이 사전 정의된 역할에는 다음과 같은 필수 권한이 포함되어 있습니다.

  • bigquery.datasets.get
  • bigquery.tables.create
  • bigquery.tables.get
  • bigquery.tables.updateData
  • bigquery.tables.update
  • bigquery.tables.export

사용 사례에 따라 BigQuery 데이터 세트 또는 테이블에도 이러한 역할 및 권한을 할당할 수 있습니다.

• 스토리지 기존 버킷 작성자(roles/storage.legacyBucketWriter). 이 사전 정의된 역할에는 다음과 같은 필수 권한이 포함되어 있습니다.

  • storage.buckets.get
  • storage.objects.get
  • storage.objects.list

이 역할과 이러한 권한은 사용 사례에 따라 Cloud Storage 버킷에 할당할 수도 있습니다.

참고: 플러그인 속성을 구성할 때 임시 버킷 이름을 제공하지 않으면 storage.buckets.create 및 storage.buckets.delete 권한이 필요합니다. 이 역할은 프로젝트의 스토리지 관리자 역할(roles/storage.admin)을 사용하여 할당할 수 있습니다.

플러그인 구성

1. Cloud Data Fusion 웹 인터페이스로 이동하고 Studio를 클릭하세요.
2. 데이터 파이프라인 - 배치가 선택되었는지 확인합니다(실시간 아님).
3. 소스 메뉴에서 BigQuery를 클릭합니다. BigQuery 노드가 파이프라인에 표시됩니다.
4. 소스를 구성하려면 BigQuery 노드로 이동하고 속성을 클릭합니다.

5. 다음 속성을 입력합니다. 전체 목록은 속성을 참조하세요.

   1. BigQuery 노드의 라벨을 입력합니다(예: BigQuery tables).

   2. 다음 연결 세부정보를 입력합니다. 새로운 일회성 연결 또는 재사용 가능한 기존의 연결을 설정할 수 있습니다.

      새로운 연결

      BigQuery에 일회성 연결을 추가하려면 다음 단계를 따르세요.

      1. 프로젝트 ID 필드에서 값을 자동 감지로 둡니다.
      2. BigQuery 데이터 세트가 다른 프로젝트에 있으면 데이터 세트 프로젝트 ID 필드에 ID를 입력합니다.

      3. 서비스 계정 유형 필드에서 다음 중 하나를 선택하고 다음 필드에 콘텐츠를 입력합니다.

         • 파일 경로
         • JSON

      재사용 가능한 연결

      기존 연결을 재사용하려면 다음 단계를 따르세요.

      1. 연결 사용을 사용 설정합니다.
      2. 연결 찾아보기를 클릭합니다.

      3. 연결 이름(예: BigQuery 기본값)을 클릭합니다.

         참고: 연결을 탐색할 때 표시되는 연결을 추가, 가져오기, 수정하는 방법에 대한 자세한 내용은 연결 관리를 참조하세요.

      4. (선택사항) 연결이 존재하지 않고 재사용 가능한 새 연결을 만들려면 연결 추가를 클릭하고 이 페이지의 새 연결 탭의 단계를 참조하세요.

   3. 참조 이름 필드에 계보에 사용할 이름을 입력합니다.

   4. (선택사항) 인스턴스에서 데이터 세트를 이미 사용할 수 있으면 찾아보기를 클릭하고 읽을 데이터를 선택합니다.

   5. 데이터 세트 필드에 테이블이 포함된 데이터 세트의 이름을 입력합니다.

   6. 테이블 필드에 테이블 이름을 입력합니다.

   7. 연결을 테스트하려면 스키마 가져오기를 클릭합니다.

   8. (선택사항) 파티션 시작일 필드에 포함된 시작일 문자열(예: 2021-01-11)을 입력합니다.

   9. (선택사항) 파티션 종료일 필드에 종료일 포함 문자열을 입력합니다(예: 2024-01-11).

   10. (선택사항) 필터 필드에 BigQuery WHERE 절을 입력합니다.

   11. (선택사항) 임시 버킷 이름 필드에 Cloud Storage 버킷의 이름을 입력합니다.

   12. (선택사항) 암호화 키 이름 필드에 Cloud Key Management Service(Cloud KMS) 암호화 키 이름을 입력합니다. 자세한 내용은 키의 리소스 이름 가져오기를 참조하세요.

   13. (선택사항) 쿼리 뷰 사용 설정을 사용 설정합니다. 이를 사용 설정하는 경우 다음을 수행하세요.

       • 임시 테이블 만들기 프로젝트 필드에 임시 테이블이 생성되는 프로젝트 이름을 입력합니다.
       • 임시 테이블 만들기 데이터 세트 필드에 임시 테이블이 생성되는 데이터 세트 이름을 입력합니다.

   14. (선택사항) 검증을 클릭하고 발견된 오류를 해결합니다.

   15. 닫기를 클릭합니다. 속성은 저장되고 Cloud Data Fusion 웹 인터페이스에서 데이터 파이프라인을 계속 빌드할 수 있습니다.

속성

속성	매크로 사용 설정	필수 속성	설명
라벨	아니요	예	데이터 파이프라인의 노드 이름
연결 사용	아니요	아니요	소스에 대한 재사용 가능한 연결을 찾습니다. 연결을 탐색할 때 표시되는 연결을 추가, 가져오기, 수정하는 방법에 대한 자세한 내용은 연결 관리를 참조하세요.
연결	예	예	연결 사용이 사용 설정되면 선택한 재사용 가능한 연결의 이름이 이 필드에 표시됩니다.
프로젝트 ID	예	아니요	연결 사용이 사용 중지된 경우에만 사용됩니다. BigQuery 작업이 실행되는 프로젝트의 전역 고유 식별자입니다. 기본값은 auto-detect입니다.
데이터 세트 프로젝트 ID	예	아니요	연결 사용이 사용 중지된 경우에만 사용됩니다. 데이터 세트가 BigQuery 작업이 실행되는 프로젝트와 다른 프로젝트에 있으면 이 값은 BigQuery 데이터 세트가 있는 프로젝트의 전역 고유 식별자입니다. 값을 지정하지 않으면 필드의 기본값은 프로젝트 ID입니다. 프로젝트에서 BigQuery 데이터를 읽으려면 BigQuery 데이터 뷰어 역할을 지정된 서비스 계정에 부여해야 합니다.
서비스 계정 유형	예	아니요	다음 옵션 중 하나를 선택합니다. 파일 경로: 서비스 계정이 있는 파일 경로입니다. JSON: 서비스 계정의 JSON 콘텐츠입니다.
서비스 계정 파일 경로	예	아니요	서비스 계정 유형 값이 파일 경로인 경우에만 사용됩니다. 로컬 파일 시스템에서 승인에 사용되는 서비스 계정 키의 경로입니다. 작업이 Dataproc 클러스터에서 실행되는 경우 값을 자동 감지로 설정합니다. 작업이 다른 유형의 클러스터에서 실행되는 경우 파일이 클러스터의 모든 노드에 있어야 합니다. 기본값은 auto-detect입니다.
서비스 계정 JSON	예	아니요	서비스 계정 유형 값이 JSON인 경우에만 사용됩니다. 서비스 계정의 JSON 파일 콘텐츠입니다.
참조 이름	아니요	예	계보 및 주석 메타데이터와 같이 다른 서비스에서 이 소스를 고유하게 식별하는 이름입니다.
데이터 세트	예	예	테이블이 속한 데이터 세트입니다. 데이터 세트는 특정 프로젝트에 포함됩니다. 데이터 세트는 테이블과 뷰에 대한 액세스를 구성하고 제어하는 최상위 컨테이너입니다.
표	예	예	읽을 테이블입니다. 테이블에는 행으로 구성된 개별 레코드가 포함됩니다. 각 레코드는 열(또는 필드라고도 부름)로 구성됩니다. 모든 테이블은 열 이름, 데이터 유형, 기타 정보를 설명하는 스키마로 정의됩니다.
파티션 시작일	예	아니요	yyyy-mm-dd로 지정된 포괄적 파티션 시작일입니다. 값을 지정하지 않으면 파티션 종료일까지의 모든 파티션을 읽습니다.
파티션 종료일	예	아니요	yyyy-mm-dd로 지정된 제외 파티션 종료일입니다. 값을 지정하지 않으면 파티션 시작일 이후의 모든 파티션을 읽습니다.
필터	예	아니요	지정된 조건을 필터링하는 SQL 쿼리 예를 들어 이 쿼리는 Roster 테이블의 모든 행을 반환합니다. 여기서 SchoolID 열에ㄴ,는 SchoolID > 52: SELECT * FROM Roster WHERE SchoolID > 52; 값이 포함됩니다. 이는 BigQuery의 WHERE 절과 동일합니다.
임시 버킷 이름	예	아니요	임시 데이터 스토리지를 위한 Cloud Storage 버킷입니다. 프로필이 없으면 자동으로 생성됩니다. 읽은 후에는 임시 데이터가 삭제됩니다. 이름이 제공되지 않았으면 고유 버킷이 생성된 후 실행이 완료된 후 삭제됩니다.
암호화 키 이름	예	아니요	플러그인에서 생성되는 모든 버킷에 기록되는 데이터를 암호화하는 키입니다. 버킷이 이미 있으면 이 값을 무시합니다. 자세한 내용은 CMEK를 참조하세요.
쿼리 뷰 사용 설정	예	아니요	BigQuery 논리 및 구체화된 뷰를 허용할지 여부입니다. BigQuery 뷰는 기본적으로 사용 설정되지 않으므로 쿼리하면 성능 오버헤드가 발생할 수 있습니다. 기본값은 아니요입니다.
임시 테이블 만들기 프로젝트	예	아니요	쿼리 뷰 사용 설정이 사용 설정된 경우에만 사용됩니다. 임시 테이블을 만들 프로젝트 이름입니다. 기본적으로 테이블이 있는 동일한 프로젝트로 지정됩니다.
임시 테이블 만들기 데이터 세트	예	아니요	임시 테이블을 만들어야 하는 지정된 프로젝트의 데이터 세트입니다. 기본값은 테이블이 있는 동일한 데이터 세트입니다.
출력 스키마	예	예	읽을 테이블의 스키마입니다. 스키마 가져오기를 클릭하여 가져올 수 있습니다.

데이터 유형 매핑

다음 표에는 BigQuery 데이터 유형과 해당 CDAP 유형이 나와 있습니다.

BigQuery 데이터 유형	CDAP 스키마 데이터 유형
BOOL	boolean
BYTES	bytes
DATE	date
DATETIME	datetime, string
FLOAT64	double
GEO	unsupported
INT64	long
NUMERIC	decimal
BIGNUMERIC	decimal
REPEATED	array
STRING	string, datetime(ISO 8601 형식)
STRUCT	record
TIME	time(마이크로초)
TIMESTAMP	timestamp(마이크로초)
JSON	unsupported

출시 노트

• 2024년 2월 8일
• 2024년 1월 16일
• 2023년 9월 6일
• 2023년 6월 14일
• 2022년 12월 6일

다음 단계

• Cloud Data Fusion의 플러그인에 대해 자세히 알아보기