Azure Data Factory 또는 Azure Synapse Analytics를 사용하여 SFTP 서버에서 데이터 복사 및 변환

적용 대상: Azure Data Factory Azure Synapse Analytics

팁

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

이 문서에서는 복사 작업을 사용하여 보안 FTP(SFTP) 서버에서 데이터를 복사하고 Data Flow를 사용하여 SFTP 서버에서 데이터를 변환하는 방법을 간략하게 설명합니다. 자세한 내용은 Azure Data Factory 또는 Azure Synapse Analytics의 소개 문서를 참조하세요.

지원되는 기능

이 SFTP 커넥터는 다음 기능에 대해 지원됩니다.

지원되는 기능	IR
복사 작업(원본/싱크)	3,4
매핑 데이터 흐름(원본/싱크)	9
조회 작업	3,4
GetMetadata 작업	3,4
삭제 작업	3,4

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

특히 SFTP 커넥터는 다음을 지원합니다.

• 기본, SSH 퍼블릭 키 또는 다단계 인증을 사용하여 SFTP 서버에서 파일을 복사합니다.
• 파일을 있는 그대로 복사하거나 지원되는 파일 형식 및 압축 코덱을 사용하여 파일을 구문 분석 또는 생성합니다.

필수 조건

데이터 저장소가 온-프레미스 네트워크, Azure 가상 네트워크 또는 Amazon Virtual Private Cloud 내에 있는 경우 자체 호스팅된 통합 런타임을 구성하여 연결해야 합니다.

데이터 저장소가 관리형 클라우드 데이터 서비스인 경우 Azure Integration Runtime을 사용할 수 있습니다. 액세스가 방화벽 규칙에서 승인된 IP로 제한되는 경우 허용 목록에 Azure Integration Runtime IP를 추가할 수 있습니다.

또한 Azure Data Factory의 관리형 가상 네트워크 통합 런타임 기능을 사용하면 자체 호스팅 통합 런타임을 설치하고 구성하지 않고도 온-프레미스 네트워크에 액세스할 수 있습니다.

Data Factory에서 지원하는 네트워크 보안 메커니즘 및 옵션에 대한 자세한 내용은 데이터 액세스 전략을 참조하세요.

시작하기

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

• 데이터 복사 도구
• Azure Portal
• .NET SDK
• Python SDK
• Azure PowerShell
• REST API
• Azure Resource Manager 템플릿

UI를 사용하여 SFTP 연결된 서비스 만들기

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

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

   Azure Data Factory

   

   Azure Synapse

   

2. SFTP를 검색하고 SFTP 커넥터를 선택합니다.

   

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

   

커넥터 구성 세부 정보

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

연결된 서비스 속성

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

속성	설명	필수
type	type 속성은 Sftp로 설정해야 합니다.	예
host	SFTP 서버의 이름 또는 IP 주소입니다.	예
port	SFTP 서버가 수신하는 포트입니다. 허용되는 값은 정수이며 기본값은 22입니다.	아니요
skipHostKeyValidation	호스트 키 유효성 검사를 건너뛸지 여부를 지정합니다. 허용되는 값은 true 및 false(기본값)입니다.	아니요
hostKeyFingerprint	호스트 키의 지문을 지정합니다.	예(“skipHostKeyValidation”이 false로 설정된 경우)
authenticationType	인증 유형을 지정합니다. 허용되는 값은 Basic, SshPublicKey 및 MultiFactor입니다. 자세한 속성은 기본 인증 사용 섹션을 참조하세요. JSON 예는 SSH 퍼블릭 키 인증 사용 섹션을 참조하세요.	예
connectVia	데이터 저장소에 연결하는 데 사용할 통합 런타임입니다. 자세한 내용은 사전 요구 사항 섹션을 참조하세요. 통합 런타임이 지정되지 않은 경우 서비스는 기본 Azure Integration Runtime을 사용합니다.	아니요

기본 인증 사용

기본 인증을 사용하려면 authenticationType 속성을 Basic으로 설정하고 이전 섹션에서 도입된 SFTP 커넥터 일반 속성 외에 다음 속성을 지정합니다.

속성	설명	필수
userName	SFTP 서버에 대한 액세스 권한이 있는 사용자입니다.	예
password	사용자(userName)의 암호입니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다.	예

예제:

{
    "name": "SftpLinkedService",
    "properties": {
        "type": "Sftp",
        "typeProperties": {
            "host": "<sftp server>",
            "port": 22,
            "skipHostKeyValidation": false,
            "hostKeyFingerPrint": "ssh-rsa 2048 xx:00:00:00:xx:00:x0:0x:0x:0x:0x:00:00:x0:x0:00",
            "authenticationType": "Basic",
            "userName": "<username>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of integration runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

SSH 퍼블릭 키 인증을 사용합니다.

SSH 공개 키 인증을 사용하려면 “authenticationType” 속성을 SshPublicKey로 설정하고, 마지막 섹션에서 소개한 SFTP 커넥터 일반 속성 외에 다음 속성을 지정합니다.

속성	설명	필수
userName	SFTP 서버에 대한 액세스 권한이 있는 사용자입니다.	예
privateKeyPath	통합 런타임에서 액세스할 수 있는 프라이빗 키 파일의 절대 경로를 지정합니다. 이는 자체 호스팅 형식의 통합 런타임이 “connectVia”에 지정된 경우에만 적용됩니다.	privateKeyPath 또는 privateKeyContent를 지정합니다.
privateKeyContent	Base64 인코딩된 SSH 프라이빗 키 콘텐츠입니다. SSH 프라이빗 키가 OpenSSH 형식이어야 합니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다.	privateKeyPath 또는 privateKeyContent를 지정합니다.
passPhrase	키 파일이나 키 콘텐츠가 암호에 의해 보호되는 경우 프라이빗 키의 암호를 해독하기 위한 암호를 지정합니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다.	예(프라이빗 키 파일 또는 키 콘텐츠가 암호에 의해 보호되는 경우)

참고 항목

SFTP 커넥터는 RSA/DSA OpenSSH 키를 지원합니다. 키 파일 콘텐츠는 “-----BEGIN [RSA/DSA] PRIVATE KEY-----”로 시작되어야 합니다. 프라이빗 키 파일이 PPK 형식 파일인 경우 PuTTY 도구를 사용하여 PPK를 OpenSSH 형식으로 변환합니다.

예 1: 프라이빗 키 filePath를 사용하여 SshPublicKey 인증

{
    "name": "SftpLinkedService",
    "properties": {
        "type": "Sftp",
        "typeProperties": {
            "host": "<sftp server>",
            "port": 22,
            "skipHostKeyValidation": true,
            "authenticationType": "SshPublicKey",
            "userName": "xxx",
            "privateKeyPath": "D:\\privatekey_openssh",
            "passPhrase": {
                "type": "SecureString",
                "value": "<pass phrase>"
            }
        },
        "connectVia": {
            "referenceName": "<name of integration runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

예 2: 프라이빗 키 콘텐츠를 사용하여 SshPublicKey 인증

{
    "name": "SftpLinkedService",
    "type": "Linkedservices",
    "properties": {
        "type": "Sftp",
        "typeProperties": {
            "host": "<sftp server>",
            "port": 22,
            "skipHostKeyValidation": true,
            "authenticationType": "SshPublicKey",
            "userName": "<username>",
            "privateKeyContent": {
                "type": "SecureString",
                "value": "<base64 string of the private key content>"
            },
            "passPhrase": {
                "type": "SecureString",
                "value": "<pass phrase>"
            }
        },
        "connectVia": {
            "referenceName": "<name of integration runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

다단계 인증 사용

기본 및 SSH 퍼블릭 키 인증의 조합인 다단계 인증을 사용하려면 위의 섹션에서 설명하는 사용자 이름, 암호 및 프라이빗 키 정보를 지정합니다.

예: 다단계 인증

{
    "name": "SftpLinkedService",
    "properties": {
        "type": "Sftp",
        "typeProperties": {
            "host": "<host>",
            "port": 22,
            "authenticationType": "MultiFactor",
            "userName": "<username>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            },
            "privateKeyContent": {
                "type": "SecureString",
                "value": "<base64 encoded private key content>"
            },
            "passPhrase": {
                "type": "SecureString",
                "value": "<passphrase for private key>"
            }
        },
        "connectVia": {
            "referenceName": "<name of integration runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

데이터 세트 속성

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

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

• Avro 형식
• 이진 형식
• 구분된 텍스트 형식
• Excel 형식
• JSON 형식
• ORC 형식
• Parquet 형식
• XML 형식

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

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

예제:

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

복사 작업 속성

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

SFTP를 원본으로

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

• Avro 형식
• 이진 형식
• 구분된 텍스트 형식
• Excel 형식
• JSON 형식
• ORC 형식
• Parquet 형식
• XML 형식

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

속성	설명	필수
type	storeSettings 아래의 type 속성은 SftpReadSettings로 설정해야 합니다.	예
복사할 파일 찾기
옵션 1: 정적 경로	데이터 세트에 지정된 폴더/파일 경로에서 복사합니다. 폴더의 모든 파일을 복사하려면 wildcardFileName을 *로 지정합니다.
옵션 2: 와일드카드 - wildcardFolderPath	원본 폴더를 필터링할 와일드카드 문자가 포함된 폴더 경로입니다. 허용되는 와일드카드는 *(0자 이상 일치) 및 ?(0자 또는 1자 일치)입니다. 실제 폴더 이름에 와일드카드 또는 이 이스케이프 문자가 있는 경우 ^를 사용하여 이스케이프합니다. 더 많은 예를 보려면 폴더 및 파일 필터 예를 참조하세요.	아니요
옵션 2: 와일드카드 - wildcardFileName	원본 파일을 필터링하기 위해 지정된 folderPath/wildcardFolderPath 아래의 와일드카드 문자가 포함된 파일 이름입니다. 허용되는 와일드카드는 *(0자 이상 일치) 및 ?(0자 또는 1자 일치)입니다. 실제 파일 이름에 와일드카드 또는 이 이스케이프 문자가 있는 경우 ^를 사용하여 이스케이프합니다. 더 많은 예를 보려면 폴더 및 파일 필터 예를 참조하세요.	예
옵션 3: 파일 목록 - fileListPath	지정된 파일 집합을 복사하도록 나타냅니다. 복사할 파일 목록이 포함된 텍스트 파일을 가리킵니다(데이터 세트에 구성된 경로에 대한 상대 경로를 사용하여 한 줄에 하나의 파일). 이 옵션을 사용하는 경우 데이터 세트에서 파일 이름을 지정하지 마세요. 더 많은 예를 보려면 파일 목록 예를 참조하세요.	아니요
추가 설정
재귀	하위 폴더 또는 지정된 폴더에서만 데이터를 재귀적으로 읽을지 여부를 나타냅니다. recursive를 true로 설정하고 싱크가 파일 기반 저장소인 경우 빈 폴더 또는 하위 폴더가 싱크에 복사되거나 만들어지지 않습니다. 허용되는 값은 true(기본값) 및 false입니다. fileListPath를 구성하는 경우에는 이 속성이 적용되지 않습니다.	아니요
deleteFilesAfterCompletion	대상 저장소로 이동한 후에 원본 저장소에서 이진 파일을 삭제할지를 나타냅니다. 파일 삭제는 파일 단위로 이루어지므로 복사 작업에 실패하면 일부 파일은 대상에 복사되고 원본에서 삭제된 반면, 다른 파일은 원본 저장소에 계속 남아 있는 것을 확인할 수 있습니다. 이 속성은 이진 파일 복사 시나리오에서만 유효합니다. 기본값은 false입니다.	아니요
modifiedDatetimeStart	파일은 Last Modified 특성을 기준으로 필터링됩니다. 파일의 마지막 수정 시간이 modifiedDatetimeStart보다 이후이거나 같고 modifiedDatetimeEnd보다 이전이면 파일이 선택됩니다. 시간은 UTC 표준 시간대에 2018-12-01T05:00:00Z 형식으로 적용됩니다. 속성은 NULL일 수 있습니다. 이 경우 파일 특성 필터가 데이터 세트에 적용되지 않습니다. modifiedDatetimeStart에 datetime 값이 있지만 modifiedDatetimeEnd가 NULL이면, 마지막으로 수정된 특성이 datetime 값보다 크거나 같은 파일이 선택됩니다. modifiedDatetimeEnd에 datetime 값이 있지만 modifiedDatetimeStart가 NULL이면, 마지막으로 수정된 특성이 datetime 값보다 작은 파일이 선택됩니다. fileListPath를 구성하는 경우에는 이 속성이 적용되지 않습니다.	아니요
modifiedDatetimeEnd	위와 동일합니다.	아니요
enablePartitionDiscovery	분할된 파일의 경우 파일 경로에서 파티션을 구문 분석할지를 지정하고 추가 원본 열로 추가합니다. 허용되는 값은 false(기본값) 및 true입니다.	아니요
partitionRootPath	파티션 검색을 사용하는 경우 분할된 폴더를 데이터 열로 읽도록 절대 루트 경로를 지정합니다. 지정되지 않은 경우 기본적으로 다음과 같이 지정됩니다. - 데이터 세트의 파일 경로 또는 원본의 파일 목록을 사용하는 경우 파티션 루트 경로는 데이터 세트에 구성된 경로입니다. - 와일드카드 폴더 필터를 사용하는 경우 파티션 루트 경로는 첫 번째 와일드카드 앞의 하위 경로입니다. 예를 들어 데이터 세트의 경로를 “root/folder/year=2020/month=08/day=27”로 구성한다고 가정합니다. - 파티션 루트 경로를 “root/folder/year=2020”으로 지정하는 경우 복사 작업은 파일 내의 열 외에도 각각 값이 “08” 및 “27”인 두 개의 열(month 및 day)을 생성합니다. - 파티션 루트 경로가 지정되지 않은 경우 추가 열이 생성되지 않습니다.	아니요
maxConcurrentConnections	작업 실행 중 데이터 저장소에 설정된 동시 연결의 상한입니다. 동시 연결을 제한하려는 경우에만 값을 지정합니다.	아니요
disableChunking	SFTP에서 데이터를 복사할 때 서비스는 파일 길이를 먼저 가져온 다음, 해당 파일을 여러 부분으로 나누어 병렬로 읽습니다. SFTP 서버에서 파일 길이 가져오기 또는 특정 오프셋에서 읽기를 지원하는지 여부를 지정합니다. 허용되는 값은 false(기본값), true입니다.	아니요

예제:

"activities":[
    {
        "name": "CopyFromSFTP",
        "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": "SftpReadSettings",
                    "recursive": true,
                    "wildcardFolderPath": "myfolder*A",
                    "wildcardFileName": "*.csv",
                    "disableChunking": false
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

싱크로서의 SFTP

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

• Avro 형식
• 이진 형식
• 구분된 텍스트 형식
• JSON 형식
• ORC 형식
• Parquet 형식

형식 기반 복사 싱크의 storeSettings 설정에서 SFTP에 다음 속성이 지원됩니다.

속성	설명	필수
type	storeSettings 아래의 type 속성은 SftpWriteSettings로 설정해야 합니다.	예
copyBehavior	원본이 파일 기반 데이터 저장소의 파일인 경우 복사 동작을 정의합니다. 허용된 값은 다음과 같습니다. - PreserveHierarchy(기본값): 대상 폴더에서 파일 계층 구조를 유지합니다. 원본 폴더의 원본 파일 상대 경로는 대상 폴더의 대상 파일 상대 경로와 동일합니다. - FlattenHierarchy: 원본 폴더의 모든 파일이 대상 폴더의 첫 번째 수준에 있게 됩니다. 대상 파일은 자동 생성된 이름을 갖습니다. - MergeFiles: 원본 폴더의 모든 파일을 하나의 파일로 병합합니다. 파일 이름이 지정된 경우 병합되는 파일 이름은 지정된 이름입니다. 그렇지 않으면 자동 생성되는 파일 이름이 적용됩니다.	아니요
maxConcurrentConnections	작업 실행 중 데이터 저장소에 설정된 동시 연결의 상한입니다. 동시 연결을 제한하려는 경우에만 값을 지정합니다.	아니요
useTempFileRename	임시 파일에 업로드하고 이름을 바꾸거나 대상 폴더 또는 파일 위치에 직접 쓸지를 나타냅니다. 기본적으로 이 서비스는 먼저 임시 파일에 쓴 다음 업로드가 완료되면 이름을 바꿉니다. 이 시퀀스는 (1) 다른 프로세스가 동일한 파일에 쓰는 경우 파일이 손상될 수 있는 충돌을 방지하고 (2) 전송 중에 파일의 원래 버전이 존재하는지 확인하는 데 도움이 됩니다. SFTP 서버에서 이름 바꾸기 작업을 지원하지 않는 경우 이 옵션을 사용하지 않도록 설정하고 대상 파일에 동시 쓰기가 수행되지 않도록 합니다. 자세한 내용은 이 표의 끝에 나오는 문제 해결을 참조하세요.	아니요. 기본값은 True입니다.
operationTimeout	SFTP 서버에 대한 각각의 쓰기 요청이 시간 초과되기까지의 대기 시간입니다. 기본값은60분(01:00:00)입니다.	아니요

팁

SFTP에 데이터를 쓸 때 “UserErrorSftpPathNotFound”, “UserErrorSftpPermissionDenied” 또는 “SftpOperationFail” 오류가 표시되고 사용하는 SFTP 사용자에게 적절한 권한이 있는 경우 SFTP 서버 지원 파일 이름 바꾸기 작업이 작동하는지 확인합니다. 그렇지 않으면 임시 파일 업로드(useTempFileRename) 옵션을 사용하지 않도록 설정하고 다시 시도하세요. 이 속성에 대해 자세히 알아보려면 위의 표를 참조하세요. 복사 작업에 자체 호스팅 통합 런타임을 사용하는 경우 버전 4.6 이상을 사용해야 합니다.

예제:

"activities":[
    {
        "name": "CopyToSFTP",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "BinarySink",
                "storeSettings":{
                    "type": "SftpWriteSettings",
                    "copyBehavior": "PreserveHierarchy"
                }
            }
        }
    }
]

폴더 및 파일 필터 예제

이 섹션에서는 폴더 경로 및 파일 이름에 와일드카드 필터를 사용할 때 발생하는 동작을 설명합니다.

folderPath	fileName	재귀	원본 폴더 구조 및 필터 결과(굵게 표시된 파일이 검색됨)
Folder*	(비어 있음, 기본값 사용)	false	FolderA     File1.csv     File2.json     Subfolder1         File3.csv         File4.json         File5.csv AnotherFolderB     File6.csv
Folder*	(비어 있음, 기본값 사용)	true	FolderA     File1.csv     File2.json     Subfolder1         File3.csv         File4.json         File5.csv AnotherFolderB     File6.csv
Folder*	*.csv	false	FolderA     File1.csv     File2.json     Subfolder1         File3.csv         File4.json         File5.csv AnotherFolderB     File6.csv
Folder*	*.csv	true	FolderA     File1.csv     File2.json     Subfolder1         File3.csv         File4.json         File5.csv AnotherFolderB     File6.csv

파일 목록 예

다음 표에서는 복사 활동 원본에서 파일 목록 경로를 사용할 때 발생하는 동작을 설명합니다. 원본 폴더 구조가 다음과 같고 굵게 표시된 파일을 복사하려는 것으로 가정합니다.

샘플 원본 구조	FileListToCopy.txt의 콘텐츠	Azure Data Factory 구성
root     FolderA         File1.csv         File2.json         Subfolder1             File3.csv             File4.json             File5.csv     메타데이터         FileListToCopy.txt	File1.csv Subfolder1/File3.csv Subfolder1/File5.csv	데이터 세트: - 폴더 경로: root/FolderA 복사 작업 원본: - 파일 목록 경로: root/Metadata/FileListToCopy.txt 파일 목록 경로는 복사하려는 파일 목록이 포함된 동일한 데이터 저장소의 텍스트 파일을 가리키며, 데이터 세트에 구성된 경로의 상대 경로를 사용하여 한 줄에 하나의 파일을 가리킵니다.

매핑 데이터 흐름 속성

데이터 흐름 매핑에서 데이터를 변환할 때 SFTP에서 다음 형식으로 파일을 읽고 쓸 수 있습니다.

• Avro
• 구분된 텍스트
• Excel
• JSON
• ORC
• Parquet
• XML

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

참고 항목

SSH 호스트 키 유효성 검사는 현재 매핑 데이터 흐름에서 지원되지 않습니다.

참고 항목

온-프레미스 SFTP 서버에 액세스하려면 프라이빗 엔드포인트를 사용하여 Azure Data Factory 또는 Synapse 작업 영역 관리되는 가상 네트워크를 사용해야 합니다. 자세한 단계는 이 자습서를 참조하세요.

원본 변환

다음 표에는 SFTP 원본에서 지원하는 속성이 나열되어 있습니다. 이러한 속성은 원본 옵션 탭에서 편집할 수 있습니다. 인라인 데이터 세트를 사용하는 경우 데이터 세트 속성 섹션에 설명된 속성과 동일한 추가 설정이 표시됩니다.

이름	설명	필수	허용된 값	데이터 흐름 스크립트 속성
와일드카드 경로	와일드카드 패턴을 사용하면 ADF가 일치하는 각 폴더와 파일을 단일 원본 변환에서 반복하도록 지시합니다. 이는 단일 흐름 내에서 여러 파일을 처리하는 효과적인 방법입니다.	아니요	String[]	wildcardPaths
파티션 루트 경로	파일 원본에 key=value 형식으로 분할된 폴더(예: year=2019)가 있는 경우 해당 파티션 폴더 트리의 최상위 수준을 데이터 흐름 데이터 스트림의 열 이름에 할당할 수 있습니다.	아니요	문자열	partitionRootPath
파일을 찾을 수 없음 허용	true이면 파일이 없는 경우 오류가 throw되지 않습니다.	아니요	true 또는 false	ignoreNoFilesFound
파일 목록	파일 집합입니다. 처리할 상대 경로 파일 목록이 포함된 텍스트 파일을 만듭니다. 이 텍스트 파일을 가리킵니다.	아니요	true 또는 false	fileList
파일 이름을 저장할 열	원본 파일의 이름을 데이터 열에 저장합니다. 파일 이름 문자열을 저장하려면 여기에 새 열 이름을 입력합니다.	아니요	문자열	rowUrlColumn
완료 후	데이터 흐름이 실행된 후 원본 파일을 사용해 아무 작업도 수행하지 않도록 선택하거나, 원본 파일을 삭제 또는 이동합니다. 이동 경로는 상대 경로입니다.	아니요	삭제: true 또는 false 이동: ['<from>', '<to>']	purgeFiles moveFiles
마지막으로 수정한 시간으로 필터링	마지막으로 수정된 날짜 범위를 지정하여 처리하는 파일을 필터링할 수 있습니다. 모든 날짜-시간은 UTC 기준입니다.	아니요	타임스탬프	modifiedAfter modifiedBefore

SFTP 원본 스크립트 예제

SFTP 데이터 세트를 원본 유형으로 사용하는 경우 연결된 데이터 흐름 스크립트는 다음과 같습니다.

source(allowSchemaDrift: true,
	validateSchema: false,
	ignoreNoFilesFound: true,
	purgeFiles: true,
	fileList: true,
	modifiedAfter: (toTimestamp(1647388800000L)),
	modifiedBefore: (toTimestamp(1647561600000L)),
	partitionRootPath: 'partdata',
	wildcardPaths:['partdata/**/*.csv']) ~> SFTPSource

싱크 변환

다음 표에는 SFTP 싱크에서 지원하는 속성이 나열되어 있습니다. 이러한 속성은 설정 탭에서 편집할 수 있습니다. 인라인 데이터 세트를 사용하는 경우 데이터 세트 속성 섹션에 설명된 속성과 동일한 추가 설정이 표시됩니다.

이름	설명	필수	허용된 값	데이터 흐름 스크립트 속성
폴더 지우기	데이터를 쓰기 전에 대상 폴더를 지울 것인지 여부를 결정합니다.	아니요	true 또는 false	truncate
파일 이름 옵션	작성된 데이터의 명명 형식입니다. 기본적으로 파티션당 파일 하나이고 형식은 part-#####-tid-<guid>입니다.	아니요	패턴: String 파티션당: String[] 열 데이터로 파일 이름 지정: String 열 데이터로 폴더 이름 지정: String 단일 파일로 출력: ['<fileName>']	filePattern partitionFileNames rowUrlColumn rowFolderUrlColumn partitionFileNames
모두 따옴표로 묶기	모든 값을 따옴표로 묶을 것인지 여부를 결정합니다.	아니요	true 또는 false	quoteAll

SFTP 싱크 스크립트 예제

SFTP 데이터 세트를 싱크 유형으로 사용하는 경우 연결된 데이터 흐름 스크립트는 다음과 같습니다.

IncomingStream sink(allowSchemaDrift: true,
	validateSchema: false,
	filePattern:'loans[n].csv',
	truncate: true,
	skipDuplicateMapInputs: true,
	skipDuplicateMapOutputs: true) ~> SFTPSink

조회 작업 속성

조회 작업 속성에 대한 자세한 내용은 조회 작업을 참조하세요.

GetMetadata 작업 속성

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

삭제 작업 속성

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

레거시 모델

참고 항목

다음 모델은 이전 버전과의 호환성을 위해 그대로 계속 지원됩니다. 작성 UI가 새 모델을 생성하도록 전환되었으므로 앞에서 설명한 새 모델을 사용하는 것이 좋습니다.

레거시 데이터 세트 모델

속성	설명	필수
type	데이터 세트의 type 속성을 FileShare로 설정해야 합니다.	예
folderPath	파일 경로입니다. 와일드카드 필터가 지원됩니다. 허용되는 와일드카드는 *(0자 이상 일치) 및 ?(0자 또는 1자 일치)입니다. 실제 파일 이름에 와일드카드 또는 이 이스케이프 문자가 있는 경우 ^을 사용하여 이스케이프합니다. 예: rootfolder/subfolder/(더 많은 예제는 폴더 및 파일 필터 예제 참조)	예
fileName	지정된 “folderPath” 아래의 파일에 대한 이름 또는 와일드카드 필터입니다. 이 속성의 값을 지정하지 않으면 데이터 세트는 폴더에 있는 모든 파일을 가리킵니다. 필터에 허용되는 와일드카드는 *(0자 이상 일치) 및 ?(0자 또는 1자 일치)입니다. - 예 1: "fileName": "*.csv" - 예 2: "fileName": "???20180427.txt" 실제 폴더 이름에 와일드카드 또는 이 이스케이프 문자가 있는 경우 ^을 사용하여 이스케이프합니다.	아니요
modifiedDatetimeStart	파일은 Last Modified 특성을 기준으로 필터링됩니다. 파일의 마지막 수정 시간이 modifiedDatetimeStart보다 이후이거나 같고 modifiedDatetimeEnd보다 이전이면 파일이 선택됩니다. 시간은 UTC 시간대에 2018-12-01T05:00:00Z 형식으로 적용됩니다. 많은 수의 파일에서 파일을 필터링하려는 경우 이 설정을 사용하면 데이터 이동의 전반적인 성능에 영향을 줄 수 있습니다. 속성은 NULL일 수 있습니다. 이 경우 파일 특성 필터가 데이터 세트에 적용되지 않습니다. modifiedDatetimeStart에 datetime 값이 있지만 modifiedDatetimeEnd가 NULL이면, 마지막으로 수정된 특성이 datetime 값보다 크거나 같은 파일이 선택됩니다. modifiedDatetimeEnd에 datetime 값이 있지만 modifiedDatetimeStart가 NULL이면, 마지막으로 수정된 특성이 datetime 값보다 작은 파일이 선택됩니다.	아니요
modifiedDatetimeEnd	파일은 Last Modified 특성을 기준으로 필터링됩니다. 파일의 마지막 수정 시간이 modifiedDatetimeStart보다 이후이거나 같고 modifiedDatetimeEnd보다 이전이면 파일이 선택됩니다. 시간은 UTC 시간대에 2018-12-01T05:00:00Z 형식으로 적용됩니다. 많은 수의 파일에서 파일을 필터링하려는 경우 이 설정을 사용하면 데이터 이동의 전반적인 성능에 영향을 줄 수 있습니다. 속성은 NULL일 수 있습니다. 이 경우 파일 특성 필터가 데이터 세트에 적용되지 않습니다. modifiedDatetimeStart에 datetime 값이 있지만 modifiedDatetimeEnd가 NULL이면, 마지막으로 수정된 특성이 datetime 값보다 크거나 같은 파일이 선택됩니다. modifiedDatetimeEnd에 datetime 값이 있지만 modifiedDatetimeStart가 NULL이면, 마지막으로 수정된 특성이 datetime 값보다 작은 파일이 선택됩니다.	아니요
format	파일 기반 저장소(이진 복사) 간에 파일을 있는 그대로 복사하려는 경우 입력 및 출력 데이터 세트 정의 둘 다에서 형식 섹션을 건너뜁니다. 특정 형식의 파일을 구문 분석하려는 경우 TextFormat, JsonFormat, AvroFormat, OrcFormat, ParquetFormat과 같은 파일 형식 유형이 지원됩니다. 이 값 중 하나로 서식에서 type 속성을 설정합니다. 자세한 내용은 텍스트 형식, Json 형식, Avro 형식, Orc 형식 및 Parquet 형식 섹션을 참조하세요.	아니요(이진 복사 시나리오에만 해당)
압축	데이터에 대한 압축 유형 및 수준을 지정합니다. 자세한 내용은 지원되는 파일 형식 및 압축 코덱을 참조하세요. 지원되는 형식은 GZip, Deflate, BZip2 및 ZipDeflate입니다. Optimal 및 Fastest 수준이 지원됩니다.	아니요

팁

폴더 아래에서 모든 파일을 복사하려면 folderPath만을 지정합니다.
특정 이름의 단일 파일을 복사하려면 폴더 부분으로 folderPath를, 파일 이름으로 fileName을 지정합니다.
폴더 아래에서 파일의 하위 집합을 복사하려면 폴더 부분으로 folderPath를, 와일드카드 필터로 fileName을 지정합니다.

참고 항목

파일 필터에 fileFilter 속성을 사용하는 경우 이 속성은 여전히 그대로 지원되지만 이제부터는 fileName에 추가된 새 필터 기능을 사용하는 것이 좋습니다.

예제:

{
    "name": "SFTPDataset",
    "type": "Datasets",
    "properties": {
        "type": "FileShare",
        "linkedServiceName":{
            "referenceName": "<SFTP linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "folderPath": "folder/subfolder/",
            "fileName": "*",
            "modifiedDatetimeStart": "2018-12-01T05:00:00Z",
            "modifiedDatetimeEnd": "2018-12-01T06:00:00Z",
            "format": {
                "type": "TextFormat",
                "columnDelimiter": ",",
                "rowDelimiter": "\n"
            },
            "compression": {
                "type": "GZip",
                "level": "Optimal"
            }
        }
    }
}

레거시 복사 작업 원본 모델

속성	설명	필수
type	복사 작업 원본의 type 속성을 FileSystemSource로 설정해야 합니다.	예
재귀	하위 폴더 또는 지정된 폴더에서만 데이터를 재귀적으로 읽을지 여부를 나타냅니다. recursive가 true로 설정되고 싱크가 파일 기반 저장소인 경우 빈 폴더 또는 하위 폴더가 싱크에 복사되거나 만들어지지 않습니다. 허용되는 값은 true(기본값) 및 false입니다.	아니요
maxConcurrentConnections	작업 실행 중 데이터 저장소에 설정된 동시 연결의 상한입니다. 동시 연결을 제한하려는 경우에만 값을 지정합니다.	아니요

예제:

"activities":[
    {
        "name": "CopyFromSFTP",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<SFTP input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "FileSystemSource",
                "recursive": true
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

관련 콘텐츠

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