Cloud Storage 일괄 소스

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

Cloud Storage 일괄 소스 플러그인을 사용하면 Cloud Storage 버킷에서 데이터를 읽고 추가 처리 및 변환을 위해 Cloud Data Fusion으로 가져올 수 있습니다. 다음과 같은 여러 파일 형식의 데이터를 로드할 수 있습니다.

정형: CSV, Avro, Parquet, ORC
반정형: JSON, XML
기타: 텍스트, 바이너리

시작하기 전에

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

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

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

Cloud Data Fusion API 서비스 에이전트

이 서비스 계정에는 이미 필요한 모든 권한이 있으므로 추가 권한을 추가할 필요가 없습니다.

Compute Engine 서비스 계정

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

스토리지 기존 버킷 리더(roles/storage.legacyBucketReader). 이 사전 정의된 역할에는 필요한 storage.buckets.get 권한이 포함되어 있습니다.
스토리지 객체 뷰어(roles/storage.legacyBucketReader). 이 사전 정의된 역할에는 다음과 같은 필수 권한이 포함되어 있습니다.
- storage.objects.get
- storage.objects.list

플러그인 구성

Cloud Data Fusion 웹 인터페이스로 이동하고 Studio를 클릭하세요.
데이터 파이프라인 - 배치가 선택되었는지 확인합니다(실시간 아님).
소스 메뉴에서 GCS를 클릭합니다. Cloud Storage 노드가 파이프라인에 표시됩니다.
소스를 구성하려면 Cloud Storage 노드로 이동하고 속성을 클릭합니다.
다음 속성을 입력합니다. 전체 목록은 속성을 참조하세요.
1. Cloud Storage 노드의 라벨을 입력합니다(예: Cloud Storage tables).
2. 다음 연결 세부정보를 입력합니다. 새로운 일회성 연결 또는 재사용 가능한 기존의 연결을 설정할 수 있습니다.
  새로운 연결
  Cloud Storage에 일회성 연결을 추가하려면 다음 단계를 수행합니다.
  1. 연결 사용을 사용 중지된 상태로 유지합니다.
  2. 프로젝트 ID 필드에서 값을 자동 감지로 둡니다.
  3. 서비스 계정 유형 필드에서 값을 파일 경로로, 서비스 계정 파일 경로를 자동 감지로 둡니다.
    
    참고: 플러그인이 Dataproc 클러스터에서 실행되지 않으면 서비스 계정 유형 및 서비스 계정 파일 경로의 값을 입력합니다. 자세한 내용은 속성을 참조하세요.
  재사용 가능한 연결
  기존 연결을 재사용하려면 다음 단계를 따르세요.
  1. 연결 사용을 사용 설정합니다.
  2. 연결 찾아보기를 클릭합니다.
  3. 연결 이름(예: Cloud Storage 기본값)을 클릭합니다.
    
    참고: 연결을 탐색할 때 표시되는 연결을 추가, 가져오기, 수정하는 방법에 대한 자세한 내용은 연결 관리를 참조하세요.
  4. 선택사항: 연결이 존재하지 않고 재사용 가능한 새 연결을 만들려면 연결 추가를 클릭하고 이 페이지의 새 연결 탭의 단계를 참조하세요.
3. 참조 이름 필드에 계보에 사용할 이름을 입력합니다(예: data-fusion-gcs-campaign).
4. 경로 필드에 읽을 경로를 입력합니다(예: gs://BUCKET_PATH).
5. 형식 필드에서 읽는 데이터에 대해 다음 파일 형식 중 하나를 선택합니다.
  - avro
  - blob(blob 형식에는 바이트 유형의 본문이라는 필드를 포함하는 스키마 필요)
  - csv
  - delimited
  - json
  - parquet
  - text(텍스트 형식에는 문자열 유형의 본문이라는 필드를 포함하는 스키마 필요)
  - tsv
  - 환경에 배포한 형식 플러그인의 이름
  참고: 이 필드에 매크로를 사용하는 경우 사전 정의된 형식 중 하나를 사용해야 합니다. 매크로는 플러그인으로 추가된 형식을 지원하지 않습니다.
6. 선택사항: 연결을 테스트하려면 스키마 가져오기를 클릭합니다.
7. 선택사항: 샘플 크기 필드에 선택한 데이터 유형에 대해 확인할 최대 행을 입력합니다(예: 1000).
8. 선택사항: 재정의 필드에 건너뛸 열 이름과 각 데이터 유형을 입력합니다.
9. 선택사항: 최소 분할 크기 또는 정규 표현식 경로 필터와 같은 고급 속성을 입력합니다(속성 참조).
10. 선택사항: 임시 버킷 이름 필드에 Cloud Storage 버킷의 이름을 입력합니다.
선택사항: 검증을 클릭하고 발견된 오류를 해결합니다.
닫기를 클릭합니다. 속성은 저장되고 Cloud Data Fusion Studio에서 데이터 파이프라인을 계속 빌드할 수 있습니다.

속성

속성	매크로 사용 설정	필수 속성	설명
라벨	아니요	예	데이터 파이프라인의 노드 이름
연결 사용	아니요	아니요	소스에 대한 재사용 가능한 연결을 찾습니다. 연결을 탐색할 때 표시되는 연결을 추가, 가져오기, 수정하는 방법에 대한 자세한 내용은 연결 관리를 참조하세요.
연결	예	예	연결 사용이 사용 설정되면 선택한 재사용 가능한 연결의 이름이 이 필드에 표시됩니다.
프로젝트 ID	예	No	연결 사용이 사용 중지된 경우에만 사용됩니다. 프로젝트의 전역 고유 식별자입니다. 기본값은 `auto-detect`입니다.
서비스 계정 유형	예	아니요	다음 옵션 중 하나를 선택합니다. 파일 경로: 서비스 계정이 있는 파일 경로입니다. JSON: 서비스 계정의 JSON 콘텐츠입니다.
서비스 계정 파일 경로	예	아니요	서비스 계정 유형 값이 파일 경로인 경우에만 사용됩니다. 로컬 파일 시스템에서 승인에 사용되는 서비스 계정 키의 경로입니다. 작업이 Dataproc 클러스터에서 실행되는 경우 값을 자동 감지로 설정합니다. 작업이 다른 유형의 클러스터에서 실행되는 경우 파일이 클러스터의 모든 노드에 있어야 합니다. 기본값은 `auto-detect`입니다.
서비스 계정 JSON	예	아니요	서비스 계정 유형 값이 JSON인 경우에만 사용됩니다. 서비스 계정의 JSON 파일 콘텐츠입니다.
참조 이름	아니요	예	계보 및 주석 메타데이터와 같이 다른 서비스에서 이 소스를 고유하게 식별하는 이름입니다.
경로	예	예	읽을 파일의 경로입니다. 디렉터리가 지정된 경우 백슬래시(`/`)로 경로를 종료합니다(예: `gs://bucket/path/to/directory/`). 파일 이름 패턴과 일치시키려면 별표(`*`)를 와일드 카드로 사용하면 됩니다. 찾거나 일치하는 파일이 없으면 파이프라인이 실패합니다.
형식	No	예	읽을 데이터의 형식입니다. 형식은 다음 중 하나가 되어야 합니다. avro blob(blob 형식에는 바이트 유형의 본문이라는 필드를 포함하는 스키마 필요) csv delimited json parquet text(텍스트 형식에는 문자열 유형의 본문이라는 필드를 포함하는 스키마 필요) tsv 환경에 배포한 형식 플러그인의 이름 형식이 매크로인 경우 사전 패키징된 형식만 사용할 수 있습니다.
샘플 크기	예	No	자동 데이터 유형 감지에 대해 조사되는 최대 행 수입니다. 기본값은 1,000입니다.
재정의	예	No	자동 데이터 유형 감지를 건너뛸 해당 데이터가 있는 열 목록입니다.
구분 기호	예	No	형식이 구분된 경우 사용할 구분 기호입니다. 이 속성은 다른 형식에서 무시됩니다.
따옴표로 묶인 값 사용 설정	예	No	따옴표 사이의 콘텐츠를 값으로 취급할지 여부입니다. 이 속성은 csv, csv 또는 delimited 형식에만 사용됩니다. 예를 들어 이 속성이 true로 설정된 경우 `1, "a, b, c"`는 두 개의 필드를 출력합니다. 첫 번째 필드에는 값이 `1`입니다. 두 번째는 `a, b, c`입니다. 따옴표 문자는 잘립니다. 줄바꿈 구분 기호는 따옴표 안에 있을 수 없습니다. 이 플러그인은 따옴표가 올바르게 묶여 있다고 가정합니다(예: `"a, b, c"`). 따옴표(`"a,b,c,`)를 닫지 않으면 오류가 발생합니다. 기본값은 False입니다.
첫 번째 행을 헤더로 사용	예	No	각 파일의 첫 번째 줄을 열 헤더로 사용할지 여부입니다. 지원되는 형식은 text, csv, tsv, delimited입니다. 기본값은 False입니다.
최소 분할 크기	예	No	각 입력 파티션의 최소 크기(바이트)입니다. 분할이 작을수록 동시 로드 수준이 늘어나지만 리소스와 오버헤드가 더 많이 필요합니다. 형식 값이 `blob`인 경우 데이터를 분할할 수 없습니다.
최대 분할 크기	예	No	각 입력 파티션의 최대 크기(바이트)입니다. 분할이 작을수록 동시 로드 수준이 늘어나지만 리소스와 오버헤드가 더 많이 필요합니다. 형식 값이 `blob`인 경우 데이터를 분할할 수 없습니다. 기본값은 128MB입니다.
정규식 경로 필터	예	No	입력에 포함되기 위해 파일 경로가 일치해야 하는 정규 표현식입니다. 파일 이름뿐만 아니라 전체 경로가 비교됩니다. 파일을 지정하지 않으면 파일 필터링이 수행되지 않습니다. 정규 표현식 구문에 대한 자세한 내용은 패턴을 참조하세요.
경로 필드	예	No	레코드를 읽은 파일의 경로를 배치하는 출력 필드입니다. 지정하지 않으면 경로가 출력 레코드에 포함되지 않습니다. 지정된 경우 필드가 출력 스키마에 문자열로 존재해야 합니다.
경로 파일 이름만	예	No	경로 필드 속성이 설정된 경우 경로의 URI가 아닌 파일 이름만 사용합니다. 기본값은 False입니다.
재귀적으로 파일 읽기	예	No	경로에서 파일을 재귀적으로 읽을지 여부입니다. 기본값은 False입니다.
빈 입력 허용	예	No	데이터가 없는 입력 경로를 허용할지 여부입니다. False로 설정하면 읽을 데이터가 없을 때 플러그인에서 오류가 발생합니다. True로 설정하면 오류가 발생하지 않고 레코드가 0개 읽힙니다. 기본값은 False입니다.
데이터 파일 암호화됨	예	No	파일 암호화 여부입니다. 자세한 내용은 데이터 파일 암호화를 참조하세요. 기본값은 False입니다.
암호화 메타데이터 파일 서픽스	예	No	암호화 메타데이터 파일의 파일 이름 서픽스입니다. 기본값은 메타데이터입니다.
파일 시스템 속성	예	No	데이터를 읽을 때 InputFormat과 함께 사용할 추가 속성입니다.
파일 인코딩	예	No	읽을 파일의 문자 인코딩입니다. 기본값은 UTF-8입니다.
출력 스키마	예	No	경로 필드 속성이 설정된 경우 이 속성이 스키마에 문자열로 존재해야 합니다.

데이터 파일 암호화

이 섹션에서는 데이터 파일 암호화 속성을 설명합니다. 이를 true로 설정하면 Tink 라이브러리에서 제공하는 스트리밍 AEAD를 사용하여 파일이 복호화됩니다. 각 데이터 파일은 암호화 정보가 포함된 메타데이터 파일과 함께 제공되어야 합니다. 예를 들어 gs://BUCKET/PATH_TO_DIRECTORY/file1.csv.enc에 있는 암호화된 데이터 파일은 gs://BUCKET/ PATH_TO_DIRECTORY/file1.csv.enc.metadata에 메타데이터 파일이 있어야 합니다. 메타데이터 파일에는 다음 속성이 있는 JSON 객체가 포함됩니다.

속성	설명
`kms`	데이터 암호화 키를 암호화하는 데 사용된 Cloud Key Management Service URI입니다.
`aad`	암호화에 사용되는 Base64로 인코딩된 추가 인증 데이터입니다.
`key set`	Tink 라이브러리의 직렬화된 키 세트 정보를 나타내는 JSON 객체입니다.

예시

    /* Counting example */
    {

      "kms": "gcp-kms://projects/my-key-project/locations/us-west1/keyRings/my-key-ring/cryptoKeys/mykey",

      "aad": "73iT4SUJBM24umXecCCf3A==",

      "keyset": {

          "keysetInfo": {

              "primaryKeyId": 602257784,

              "keyInfo": [{

                  "typeUrl": "type.googleapis.com/google.crypto.tink.AesGcmHkdfStreamingKey",

                  "outputPrefixType": "RAW",

                  "keyId": 602257784,

                  "status": "ENABLED"

              }]

          },

          "encryptedKeyset": "CiQAz5HH+nUA0Zuqnz4LCnBEVTHS72s/zwjpcnAMIPGpW6kxLggSrAEAcJKHmXeg8kfJ3GD4GuFeWDZzgGn3tfolk6Yf5d7rxKxDEChIMWJWGhWlDHbBW5B9HqWfKx2nQWSC+zjM8FLefVtPYrdJ8n6Eg8ksAnSyXmhN5LoIj6az3XBugtXvCCotQHrBuyoDY+j5ZH9J4tm/bzrLEjCdWAc+oAlhsUAV77jZhowJr6EBiyVuRVfcwLwiscWkQ9J7jjHc7ih9HKfnqAZmQ6iWP36OMrEn"

      }

    }

출시 노트

2023년 9월 6일

다음 단계

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