Azure Data Factory 또는 Synapse Analytics를 사용하여 Amazon S3 Compatible Storage에서 데이터 복사

  • 아티클

적용 대상: Azure Data Factory Azure Synapse Analytics

팁

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

이 문서에서는 Amazon S3(Amazon Simple Storage Service) Compatible Storage에서 데이터를 복사하는 방법을 설명합니다. 자세한 내용은 Azure Data Factory 및 Synapse Analytics의 소개 문서를 참조하세요.

지원되는 기능

이 Amazon S3 Compatible Storage 커넥터는 다음 기능에 대해 지원됩니다.

지원되는 기능 IR
복사 작업(원본/-) ① ②
조회 작업 ① ②
GetMetadata 작업 ① ②
삭제 작업 ① ②

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

특히, Amazon S3 Compatible Storage 커넥터는 이 파일을 있는 그대로 복사하거나 지원되는 파일 형식 및 압축 코덱으로 파일 구문 분석하는 기능을 지원합니다. 커넥터는 AWS Signature 버전 4를 사용하여 S3에 요청을 인증합니다. 이 Amazon S3 Compatible Storage 커넥터를 사용하여 S3 호환 가능 스토리지 공급자의 데이터를 복사할 수 있습니다. 연결된 서비스 구성에서 해당 서비스 URL을 지정합니다.

필요한 사용 권한

Amazon S3 Compatible Storage에서 데이터를 복사하려면 Amazon S3 개체 작업에 대한 s3:GetObject와 s3:GetObjectVersion의 사용 권한이 부여되었는지 확인합니다.

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

Amazon S3 사용 권한의 전체 목록은 AWS 웹 사이트에서 정책에서 사용 권한 지정을 참조하세요.

시작하기

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

UI를 사용하여 Amazon S3 호환 스토리지에 연결된 서비스 만들기

다음 단계를 사용하여 Azure Portal UI에서 Amazon S3 호환 스토리지에 연결된 서비스를 만듭니다.

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

  2. Amazon을 검색하고 Amazon S3 호환 스토리지 커넥터를 선택합니다.

    Select the Amazon S3 Compatible Storage connector.

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

    Configure a linked service to Amazon S3 Compatible Storage.

커넥터 구성 세부 정보

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

연결된 서비스 속성

Amazon S3 Compatible 연결된 서비스에 다음 속성이 지원됩니다.

속성 설명 필수
type type 속성은 AmazonS3Compatible로 설정되어야 합니다. 예
accessKeyId 비밀 액세스 키의 ID입니다. 예
secretAccessKey 비밀 액세스 키 자체입니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다. 예
ServiceUrl 사용자 지정 S3 엔드포인트 https://<service url>를 지정합니다. 아니요
forcePathStyle 가상 호스트 스타일 액세스 대신 S3 경로 스타일 액세스를 사용할지를 나타냅니다. 허용되는 값은 false(기본값), true입니다.
경로 스타일 액세스가 필요한지 여부는 각 데이터 저장소의 설명서를 참조하세요.		 아니요
connectVia 데이터 저장소에 연결하는 데 사용할 통합 런타임입니다. Azure 통합 런타임 또는 자체 호스팅 통합 런타임(데이터 저장소가 프라이빗 네트워크에 있는 경우)을 사용할 수 있습니다. 해당 속성을 지정하지 않으면 서비스는 기본 Azure 통합 런타임을 사용합니다. 아니요

예제:

{
    "name": "AmazonS3CompatibleLinkedService",
    "properties": {
        "type": "AmazonS3Compatible",
        "typeProperties": {
            "accessKeyId": "<access key id>",
            "secretAccessKey": {
                "type": "SecureString",
                "value": "<secret access key>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

데이터 세트 속성

데이터 세트 정의에 사용할 수 있는 섹션 및 속성의 전체 목록은 데이터 세트 문서를 참조하세요.

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

형식 기반 데이터 세트의 location 설정에서 Amazon S3 호환 가능에 다음 속성이 지원됩니다.

속성 설명 필수
type 데이터 세트의 location에서 속성 type은 AmazonS3CompatibleLocation으로 설정되어야 합니다. 예
bucketName S3 Compatible Storage 버킷 이름입니다. 예
folderPath 지정된 버킷 아래의 폴더 경로입니다. 와일드카드를 사용하여 폴더를 필터링하려면 이 설정을 건너뛰고 작업 원본 설정에서 지정합니다. 아니요
fileName 지정된 버킷 및 폴더 경로 아래에 있는 파일 이름입니다. 와일드카드를 사용하여 파일을 필터링하려면 이 설정을 건너뛰고 작업 원본 설정에서 지정합니다. 아니요
version S3 Compatible Storage 버전을 사용하도록 설정한 경우 S3 Compatible Storage 개체의 버전입니다. 지정하지 않으면 최신 버전을 가져옵니다. 아니요

예제:

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

복사 작업 속성

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

원본 유형으로서의 Amazon S3 Compatible Storage

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

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

속성 설명 필수
type storeSettings의 type 속성은 AmazonS3CompatibleReadSettings로 설정되어야 합니다. 예
복사할 파일 찾기:
옵션 1: 정적 경로
 지정된 버킷 또는 데이터 세트에 지정된 폴더/파일 경로에서 복사합니다. 버킷 또는 폴더의 모든 파일을 복사하려면 추가로 wildcardFileName을 *로 지정합니다.
옵션 2: S3 Compatible Storage 접두사
- 접두사		 원본 S3 Compatible Storage 파일을 필터링하기 위해 데이터 세트에 구성된 지정된 버킷 아래의 S3 Compatible Storage 키 이름에 대한 접두사입니다. 이름이 bucket_in_dataset/this_prefix로 시작하는 S3 Compatible Storage 키가 선택되었습니다. 와일드카드 필터보다 나은 성능을 제공하는 S3 Compatible Storage의 서비스 쪽 필터를 활용합니다.

접두사를 사용하고 계층 구조를 유지하는 파일 기반 싱크로 복사하도록 선택하는 경우 접두사의 마지막 “/” 뒤에 하위 경로가 유지됩니다. 예를 들어 원본 bucket/folder/subfolder/file.txt가 있고 접두사를 folder/sub로 구성하면 유지되는 파일 경로는 subfolder/file.txt입니다.		 아니요
옵션 3: 와일드카드
- wildcardFolderPath		 원본 폴더를 필터링하도록 데이터 세트에 구성된 지정된 버킷 아래에 와일드카드 문자가 포함된 폴더 경로입니다.
허용되는 와일드카드는 *(문자 0자 이상 일치) 및 ?(문자 0자 또는 1자 일치)입니다. 폴더 이름에 와일드카드 또는 이 이스케이프 문자가 있는 경우 ^을 사용하여 이스케이프합니다.
더 많은 예는 폴더 및 파일 필터 예제를 참조하세요.		 아니요
옵션 3: 와일드카드
- wildcardFileName		 원본 파일을 필터링하도록 지정된 버킷 및 폴더 경로(또는 와일드카드 폴더 경로) 아래에 와일드카드 문자가 있는 파일 이름입니다.
허용되는 와일드카드는 *(문자 0자 이상 일치) 및 ?(문자 0자 또는 1자 일치)입니다. 파일 이름에 와일드카드 또는 이 이스케이프 문자가 있는 경우 ^을 사용하여 이스케이프합니다. 더 많은 예는 폴더 및 파일 필터 예제를 참조하세요.		 예
옵션 4: 파일 목록
- fileListPath		 지정된 파일 집합을 복사하도록 지정합니다. 복사할 파일 목록이 포함된 텍스트 파일을 가리키며, 데이터 세트에 구성된 경로에 대한 상대 경로를 사용하여 한 줄에 하나의 파일을 가리킵니다.
이 옵션을 사용하는 경우 데이터 세트에 파일 이름을 지정하지 마세요. 파일 목록 예에서 더 많은 예를 참조하세요.		 아니요
추가 설정:
재귀 하위 폴더 또는 지정된 폴더에서만 데이터를 재귀적으로 읽을지 여부를 나타냅니다. recursive를 true로 설정하고 싱크가 파일 기반 저장소인 경우 빈 폴더 또는 하위 폴더가 싱크에 복사되거나 생성되지 않습니다.
허용되는 값은 true(기본값) 및 false입니다.
fileListPath를 구성하는 경우에는 이 속성이 적용되지 않습니다.		 아니요
deleteFilesAfterCompletion 대상 저장소로 이동한 후에 원본 저장소에서 이진 파일을 삭제할지를 나타냅니다. 파일 삭제는 파일 단위로 이루어지므로 복사 작업에 실패하면 일부 파일은 대상에 복사되고 원본에서 삭제된 반면, 다른 파일은 원본 저장소에 계속 남아 있는 것을 확인할 수 있습니다.
이 속성은 이진 파일 복사 시나리오에서만 유효합니다. 기본값은 false입니다.		 아니요
modifiedDatetimeStart 파일은 마지막으로 수정된 특성을 기준으로 필터링됩니다.
마지막 수정 시간이 modifiedDatetimeStart 이상 modifiedDatetimeEnd 미만인 경우 파일이 선택됩니다. 시간은 “2018-12-01T05:00:00Z” 형식의 UTC 표준 시간대에 적용됩니다.
속성은 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": "CopyFromAmazonS3CompatibleStorage",
        "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": "AmazonS3CompatibleReadSettings",
                    "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

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

조회 작업 속성

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

GetMetadata 작업 속성

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

삭제 작업 속성

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

관련 콘텐츠

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