Azure Data Factory 또는 Synapse Analytics를 사용하여 Google Cloud Storage에서 데이터 복사

  • 아티클

적용 대상: Azure Data Factory Azure Synapse Analytics

팁

기업용 올인원 분석 솔루션인 Microsoft Fabric의 Data Factory를 사용해 보세요. Microsoft Fabric은 데이터 이동부터 데이터 과학, 실시간 분석, 비즈니스 인텔리전스 및 보고에 이르기까지 모든 것을 다룹니다. 무료로 새 평가판을 시작하는 방법을 알아봅니다!

이 문서에서는 GCS(Google Cloud Storage)에서 데이터를 복사하는 방법을 간략하게 설명합니다. 자세한 내용은 Azure Data Factory 및 Synapse Analytics의 소개 문서를 참조하세요.

지원되는 기능

이 Google Cloud Storage 커넥터는 다음과 같은 기능에 지원됩니다.

지원되는 기능 IR
복사 작업(원본/-) ① ②
매핑 데이터 흐름(원본/-) ①
조회 작업 ① ②
GetMetadata 작업 ① ②
삭제 작업 ① ②

① Azure 통합 런타임 ② 자체 호스팅 통합 런타임

특히, Google Cloud Storage 커넥터는 이 파일을 있는 그대로 복사 또는 지원되는 파일 형식 및 압축 코덱을 사용한 파일 구문 분석을 지원합니다. 이는 GCS의 S3 호환 상호 운용성을 활용합니다.

필수 조건

Google Cloud Storage 계정에는 다음 설정이 필요합니다.

  1. Google Cloud Storage 계정에 대한 상호 운용성 사용
  2. 대상 GCS 버킷에서 복사할 데이터가 포함된 기본 프로젝트를 설정합니다.
  3. GCP에서 클라우드 IAM을 사용하여 서비스 계정을 만들고 적절한 수준의 권한을 정의합니다.
  4. 이 서비스 계정에 대한 액세스 키를 생성합니다.

Retrieve access key for Google Cloud Storage

필요한 사용 권한

Google Cloud Storage에서 데이터를 복사하려면 개체 작업에 대한 storage.objects.get과 storage.objects.list의 사용 권한이 부여되었는지 확인합니다.

UI를 사용하여 작성하는 경우 연결된 서비스에 대한 연결 테스트, 루트에서 검색 등의 작업을 수행하려면 추가 storage.buckets.list 권한이 필요합니다. 이러한 권한을 부여하지 않으려면 UI에서 "파일 경로에 대한 연결 테스트" 또는 "지정된 경로에서 찾아보기" 옵션을 선택할 수 있습니다.

Google Cloud Storage 역할 및 관련 사용 권한의 전체 목록은 Google Cloud 사이트의 클라우드 저장소에 대한 IAM 역할을 참조하세요.

시작하기

파이프라인에 복사 작업을 수행하려면 다음 도구 또는 SDK 중 하나를 사용하면 됩니다.

UI를 사용하여 Google Cloud Storage에 연결된 서비스 만들기

다음 단계를 사용하여 Azure Portal UI에서 Google Cloud Storage에 연결된 서비스를 만듭니다.

  1. Azure Data Factory 또는 Synapse 작업 영역에서 관리 탭으로 이동하여 연결된 서비스를 선택하고 새로 만들기를 클릭합니다.

  2. Google을 검색하고 Google Cloud Storage(S3 API) 커넥터를 선택합니다.

    Select the Google Cloud Storage (S3 API) connector.

  3. 서비스 세부 정보를 구성하고, 연결을 테스트하고, 새로운 연결된 서비스를 만듭니다.

    Configure a linked service to Google Cloud Storage.

커넥터 구성 세부 정보

다음 섹션에서는 Google Cloud Storage에 한정된 Data Factory 엔터티를 정의하는 데 사용되는 속성에 대해 자세히 설명합니다.

연결된 서비스 속성

Google Cloud Storage 연결된 서비스에 다음 속성이 지원됩니다.

속성 설명 필수
type type 속성은 GoogleCloudStorage로 설정해야 합니다. 예
accessKeyId 비밀 액세스 키의 ID입니다. 액세스 키와 비밀을 찾으려면 필수 구성 요소를 참조하세요. 예
secretAccessKey 비밀 액세스 키 자체입니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나 Azure Key Vault에 저장된 비밀을 참조합니다. 예
ServiceUrl 사용자 지정 GCS 엔드포인트를 https://storage.googleapis.com으로 지정합니다. 예
connectVia 데이터 저장소에 연결하는 데 사용할 통합 런타임입니다. Azure 통합 런타임 또는 자체 호스팅 통합 런타임(데이터 저장소가 프라이빗 네트워크에 있는 경우)을 사용할 수 있습니다. 해당 속성을 지정하지 않으면 서비스는 기본 Azure 통합 런타임을 사용합니다. 아니요

예를 들면 다음과 같습니다.

{
    "name": "GoogleCloudStorageLinkedService",
    "properties": {
        "type": "GoogleCloudStorage",
        "typeProperties": {
            "accessKeyId": "<access key id>",
            "secretAccessKey": {
                "type": "SecureString",
                "value": "<secret access key>"
            },
            "serviceUrl": "https://storage.googleapis.com"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

데이터 세트 속성

Azure Data Factory는 다음과 같은 파일 형식을 지원합니다. 형식 기반 설정에 대한 각 문서를 참조하세요.

형식 기반 데이터 세트의 location 설정에서 Google Cloud Storage에 다음 속성이 지원됩니다.

속성 설명 필수
type 데이터 세트의 location 아래 type 속성은 GoogleCloudStorageLocation으로 설정되어야 합니다. 예
bucketName GCS 버킷 이름입니다. 예
folderPath 지정된 버킷 아래의 폴더 경로입니다. 와일드카드를 사용하여 폴더를 필터링하려면 이 설정을 건너뛰고 작업 원본 설정에서 지정합니다. 아니요
fileName 지정된 버킷 및 폴더 경로 아래에 있는 파일 이름입니다. 와일드카드를 사용하여 파일을 필터링하려면 이 설정을 건너뛰고 작업 원본 설정에서 지정합니다. 아니요

예제:

{
    "name": "DelimitedTextDataset",
    "properties": {
        "type": "DelimitedText",
        "linkedServiceName": {
            "referenceName": "<Google Cloud Storage linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, auto retrieved during authoring > ],
        "typeProperties": {
            "location": {
                "type": "GoogleCloudStorageLocation",
                "bucketName": "bucketname",
                "folderPath": "folder/subfolder"
            },
            "columnDelimiter": ",",
            "quoteChar": "\"",
            "firstRowAsHeader": true,
            "compressionCodec": "gzip"
        }
    }
}

복사 작업 속성

작업 정의에 사용할 수 있는 섹션 및 속성의 전체 목록은 파이프라인 문서를 참조하세요. 이 섹션에서는 Google Cloud Storage 원본에서 지원하는 속성 목록을 제공합니다.

원본 유형으로 Google Cloud Storage

Azure Data Factory는 다음과 같은 파일 형식을 지원합니다. 형식 기반 설정에 대한 각 문서를 참조하세요.

형식 기반 복사 원본의 storeSettings 설정에서 Google Cloud Storage에 다음 속성이 지원됩니다.

속성 설명 필수
type storeSettings 아래의 type 속성은 GoogleCloudStorageReadSettings로 설정되어야 합니다. 예
복사할 파일 찾기:
옵션 1: 정적 경로
 지정된 버킷 또는 데이터 세트에 지정된 폴더/파일 경로에서 복사합니다. 버킷 또는 폴더의 모든 파일을 복사하려면 추가로 wildcardFileName을 *로 지정합니다.
옵션 2: GCS 접두사
- 접두사		 원본 GCS 파일을 필터링하기 위해 데이터 세트에 구성된 지정된 버킷의 GCS 키 이름에 대한 접두사입니다. 이름이 bucket_in_dataset/this_prefix로 시작하는 GCS 키가 선택됩니다. 와일드카드 필터보다 나은 성능을 제공하는 GCS의 서비스 필터를 활용합니다. 아니요
옵션 3: 와일드카드
- wildcardFolderPath		 원본 폴더를 필터링하도록 데이터 세트에 구성된 지정된 버킷 아래에 와일드카드 문자가 포함된 폴더 경로입니다.
허용되는 와일드카드는 *(문자 0자 이상 일치) 및 ?(문자 0자 또는 1자 일치)입니다. 폴더 이름에 와일드카드 또는 이 이스케이프 문자가 있는 경우 ^을 사용하여 이스케이프합니다.
더 많은 예는 폴더 및 파일 필터 예제를 참조하세요.		 아니요
옵션 3: 와일드카드
- wildcardFileName		 원본 파일을 필터링하도록 지정된 버킷 및 폴더 경로(또는 와일드카드 폴더 경로) 아래에 와일드카드 문자가 있는 파일 이름입니다.
허용되는 와일드카드는 *(문자 0자 이상 일치) 및 ?(문자 0자 또는 1자 일치)입니다. 파일 이름에 와일드카드 또는 이 이스케이프 문자가 있는 경우 ^을 사용하여 이스케이프합니다. 더 많은 예는 폴더 및 파일 필터 예제를 참조하세요.		 예
옵션 3: 파일 목록
- fileListPath		 지정된 파일 집합을 복사하도록 지정합니다. 복사할 파일 목록이 포함된 텍스트 파일을 가리키며, 데이터 세트에 구성된 경로에 대한 상대 경로를 사용하여 한 줄에 하나의 파일을 가리킵니다.
이 옵션을 사용하는 경우 데이터 세트에 파일 이름을 지정하지 마십시오. 파일 목록 예에서 더 많은 예를 참조하세요.		 아니요
추가 설정:
재귀 하위 폴더 또는 지정된 폴더에서만 데이터를 재귀적으로 읽을지 여부를 나타냅니다. recursive를 true로 설정하고 싱크가 파일 기반 저장소인 경우 빈 폴더 또는 하위 폴더가 싱크에 복사되거나 생성되지 않습니다.
허용되는 값은 true(기본값) 및 false입니다.
fileListPath를 구성하는 경우에는 이 속성이 적용되지 않습니다.		 아니요
deleteFilesAfterCompletion 대상 저장소로 이동한 후에 원본 저장소에서 이진 파일을 삭제할지를 나타냅니다. 파일 삭제는 파일 단위로 이루어지므로 복사 작업에 실패하면 일부 파일은 대상에 복사되고 원본에서 삭제된 반면, 다른 파일은 원본 저장소에 계속 남아 있는 것을 확인할 수 있습니다.
이 속성은 이진 파일 복사 시나리오에서만 유효합니다. 기본값은 false입니다.		 아니요
modifiedDatetimeStart 파일은 마지막으로 수정된 특성을 기준으로 필터링됩니다.
마지막 수정 시간이 modifiedDatetimeStart 이상 modifiedDatetimeEnd 미만인 경우 파일이 선택됩니다. 시간은 UTC 표준 시간대에 "2018-12-01T05:00:00Z" 형식으로 적용됩니다.
속성은 NULL일 수 있습니다. 즉, 파일 특성 필터가 데이터 세트에 적용되지 않습니다. modifiedDatetimeStart에 날짜/시간 값이 있지만 modifiedDatetimeEnd가 NULL이면, 마지막으로 수정된 특성이 날짜/시간 값보다 크거나 같은 파일이 선택됩니다. modifiedDatetimeEnd에 날짜/시간 값이 있지만 modifiedDatetimeStart가 NULL이면, 마지막으로 수정된 특성이 날짜/시간 값보다 작은 파일이 선택됩니다.
fileListPath를 구성하는 경우에는 이 속성이 적용되지 않습니다.		 아니요
modifiedDatetimeEnd 위와 동일합니다. 아니요
enablePartitionDiscovery 분할된 파일의 경우 파일 경로에서 파티션을 구문 분석할지를 지정하고 추가 원본 열로 추가합니다.
허용되는 값은 false(기본값) 및 true입니다.		 아니요
partitionRootPath 파티션 검색을 사용하는 경우 분할된 폴더를 데이터 열로 읽도록 절대 루트 경로를 지정합니다.

지정되지 않은 경우 기본적으로 다음과 같이 지정됩니다.
- 데이터 세트의 파일 경로 또는 원본의 파일 목록을 사용하는 경우 파티션 루트 경로는 데이터 세트에 구성된 경로입니다.
- 와일드카드 폴더 필터를 사용하는 경우 파티션 루트 경로는 첫 번째 와일드카드 앞의 하위 경로입니다.

예를 들어 데이터 세트의 경로를 “root/folder/year=2020/month=08/day=27”로 구성한다고 가정합니다.
- 파티션 루트 경로를 “root/folder/year=2020”으로 지정하는 경우 복사 작업은 파일 내의 열 외에도 각각 값이 “08” 및 “27”인 두 개의 열(month 및 day)을 생성합니다.
- 파티션 루트 경로가 지정되지 않은 경우 추가 열이 생성되지 않습니다.		 아니요
maxConcurrentConnections 작업 실행 중 데이터 저장소에 설정된 동시 연결의 상한입니다. 동시 연결을 제한하려는 경우에만 값을 지정합니다. 아니요

예제:

"activities":[
    {
        "name": "CopyFromGoogleCloudStorage",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Delimited text input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "DelimitedTextSource",
                "formatSettings":{
                    "type": "DelimitedTextReadSettings",
                    "skipLineCount": 10
                },
                "storeSettings":{
                    "type": "GoogleCloudStorageReadSettings",
                    "recursive": true,
                    "wildcardFolderPath": "myfolder*A",
                    "wildcardFileName": "*.csv"
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

폴더 및 파일 필터 예제

이 섹션에서는 와일드카드 필터가 있는 폴더 경로 및 파일 이름의 결과 동작에 대해 설명합니다.

bucket key 재귀 원본 폴더 구조 및 필터 결과(굵게 표시된 파일이 검색됨)
bucket Folder*/* false bucket
    FolderA
        File1.csv
        File2.json
        Subfolder1
            File3.csv
            File4.json
            File5.csv
    AnotherFolderB
        File6.csv
bucket Folder*/* true bucket
    FolderA
        File1.csv
        File2.json
        Subfolder1
            File3.csv
            File4.json
            File5.csv
    AnotherFolderB
        File6.csv
bucket Folder*/*.csv false bucket
    FolderA
        File1.csv
        File2.json
        Subfolder1
            File3.csv
            File4.json
            File5.csv
    AnotherFolderB
        File6.csv
bucket Folder*/*.csv true bucket
    FolderA
        File1.csv
        File2.json
        Subfolder1
            File3.csv
            File4.json
            File5.csv
    AnotherFolderB
        File6.csv

파일 목록 예

이 섹션에서는 복사 작업 원본에서 파일 목록 경로를 사용하는 결과 동작에 대해 설명합니다.

다음 원본 폴더 구조가 있고 굵게 표시된 파일을 복사하려고 한다고 가정합니다.

샘플 원본 구조 FileListToCopy.txt의 콘텐츠 구성
bucket
    FolderA
        File1.csv
        File2.json
        Subfolder1
            File3.csv
            File4.json
            File5.csv
    메타데이터
        FileListToCopy.txt		 File1.csv
Subfolder1/File3.csv
Subfolder1/File5.csv		 데이터 세트:
- 버킷: bucket
- 폴더 경로: FolderA

복사 작업 원본:
- 파일 목록 경로: bucket/Metadata/FileListToCopy.txt

파일 목록 경로는 복사하려는 파일 목록이 포함된 동일한 데이터 저장소의 텍스트 파일을 가리키며, 데이터 세트에 구성된 경로의 상대 경로를 사용하여 한 줄에 하나의 파일을 가리킵니다.

매핑 데이터 흐름 속성

매핑 데이터 흐름에서 데이터를 변환할 때 Google Cloud Storage에서 다음 형식의 파일을 읽을 수 있습니다.

형식별 설정은 해당 형식에 대한 설명서에 있습니다. 자세한 내용은 매핑 데이터 흐름의 원본 변환을 참조하세요.

원본 변환

원본 변환에서는 Google Cloud Storage의 컨테이너, 폴더, 개별 파일에서 읽을 수 있습니다. 원본 옵션 탭을 사용하여 파일을 읽는 방법을 관리합니다.

Screenshot of Source options.

와일드카드 경로: 와일드카드 패턴을 사용하면 서비스가 일치하는 각 폴더와 파일을 단일 원본 변환에서 반복하도록 지시합니다. 이는 단일 흐름 내에서 여러 파일을 처리하는 효과적인 방법입니다. 기존 와일드카드 패턴을 마우스로 가리키면 표시되는 + 기호를 사용하여 와일드카드 일치 패턴을 여러 개 추가합니다.

원본 컨테이너에서 패턴과 일치하는 일련의 파일을 선택합니다. 데이터 세트에는 컨테이너만 지정할 수 있습니다. 따라서 와일드카드 경로에는 루트 폴더의 폴더 경로도 포함되어야 합니다.

와일드카드 예제:

  • * 모든 문자 집합 나타내기

  • ** 재귀 디렉터리 중첩 나타내기

  • ? 한 문자 바꾸기

  • [] 괄호 안에 있는 하나 이상의 문자와 일치시키기

  • /data/sales/**/*.csv /data/sales에서 .csv 파일 모두 가져오기

  • /data/sales/20??/**/ 20세기의 파일 모두 가져오기

  • /data/sales/*/*/*.csv /data/sales에서 .csv 파일을 두 가지 수준으로 가져오기

  • /data/sales/2004/*/12/[XY]1?.csv X 또는 Y 접두사가 두 자리 숫자로 시작하는 2004년 12월의 .csv 파일 모두 가져오기

파티션 루트 경로: 파일 원본에 key=value 형식으로 분할된 폴더(예: year=2019)가 있는 경우 해당 파티션 폴더 트리의 최상위 수준을 데이터 흐름 데이터 스트림의 열 이름에 할당할 수 있습니다.

먼저 분할된 폴더와 읽을 리프 파일인 모든 경로를 포함하도록 와일드카드를 설정합니다.

Screenshot of partition source file settings.

파티션 루트 경로 설정을 사용하여 폴더 구조의 최상위 수준을 정의합니다. 데이터 미리 보기를 통해 데이터 콘텐츠를 보면 서비스가 각 폴더 수준에서 찾은 해결된 파티션을 추가함을 확인할 수 있습니다.

Screenshot of partition root path.

파일 목록: 파일 집합입니다. 처리할 상대 경로 파일 목록이 포함된 텍스트 파일을 만듭니다. 이 텍스트 파일을 가리킵니다.

파일 이름을 저장할 열: 원본 파일의 이름을 데이터 열에 저장합니다. 파일 이름 문자열을 저장하려면 여기에 새 열 이름을 입력합니다.

완료 후 기간(일): 데이터 흐름이 실행된 후 원본 파일을 사용해 아무 작업도 수행하지 않도록 선택하거나, 원본 파일을 삭제 또는 이동합니다. 이동 경로는 상대 경로입니다.

원본 파일을 다른 위치에 후처리로 이동하려면 먼저 파일 작업에서 "이동"을 선택합니다. 그런 다음, "원본" 디렉터리를 설정합니다. 경로에 와일드카드를 사용하지 않을 경우 "원본" 설정은 원본 폴더와 같은 폴더에 있습니다.

와일드카드가 있는 원본 경로를 사용하는 경우 구문은 다음과 같습니다.

/data/sales/20??/**/*.csv

"원본"은 다음과 같이 지정할 수 있습니다.

/data/sales

그리고 "to"를 다음으로 지정할 수 있습니다.

/backup/priorSales

이 경우 /data/sales에서 제공되는 모든 파일이 /backup/priorSales로 이동됩니다.

참고 항목

파이프라인에서 Data Flow 실행 작업을 사용하는 파이프라인 실행(파이프라인 디버그 또는 실행)에서 데이터 흐름을 시작하는 경우에만 파일 작업이 실행됩니다. Data Flow 디버그 모드에서는 파일 작업이 실행되지 않습니다.

마지막으로 수정한 사람 필터링: 마지막으로 수정된 날짜 범위를 지정하여 처리하는 파일을 필터링할 수 있습니다. 모든 날짜/시간은 UTC 기준입니다.

조회 작업 속성

속성에 대한 자세한 내용을 보려면 조회 작업을 확인하세요.

GetMetadata 작업 속성

속성에 대한 자세한 내용은 GetMetadata 작업을 확인하세요.

삭제 작업 속성

속성에 대한 자세한 내용은 삭제 작업을 확인하세요.

레거시 모델

Amazon S3 커넥터를 사용하여 Google Cloud Storage에서 데이터를 복사하는 경우 이전 버전과의 호환성을 위해 그대로 계속 지원됩니다. 앞서 설명한 새 모델을 사용하는 것이 좋습니다. 새 모델을 생성하도록 작성 UI가 전환되었습니다.

관련 콘텐츠

복사 작업에서 원본 및 싱크로 지원되는 데이터 저장소의 목록은 지원되는 데이터 저장소를 참조하세요.