Azure Data Factory를 사용하여 Azure Files에서 또는 Azure Files로부터 데이터 복사

적용 대상: Azure Data Factory Azure Synapse Analytics

이 문서에서는 Azure Files에서 또는 Azure Files로 데이터를 복사하는 방법을 설명합니다. Azure Data Factory에 대해 자세히 알아보려면 소개 문서를 참조하세요.

지원되는 기능

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

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

Azure Files에서 지원되는 싱크 데이터 저장소로 데이터를 복사하거나 지원되는 원본 데이터 저장소에서 Azure Files로 데이터를 복사할 수 있습니다. 복사 작업에서 원본 및 싱크로 지원되는 데이터 저장소의 목록은 지원되는 데이터 저장소 및 형식을 참조하세요.

특히 이 Azure Files 커넥터는 다음을 지원합니다.

• 계정 키 또는 서비스 SAS(공유 액세스 서명) 인증을 사용하여 파일을 복사합니다.
• 파일을 있는 그대로 복사하거나 지원되는 파일 형식 및 압축 코덱을 사용하여 파일을 붙여넣거나 생성합니다.

시작하기

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

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

UI를 사용하여 Azure Files에 연결된 서비스 만들기

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

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

   • Azure Data Factory
   • Azure Synapse

   

2. 파일을 검색하고 레이블이 Azure File Storage인 Azure Files 커넥터를 선택합니다.

   

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

   

커넥터 구성 세부 정보

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

연결된 서비스 속성

이 Azure Files 커넥터는 다음 인증 유형을 지원합니다. 자세한 내용은 해당 섹션을 참조하세요.

• 계정 키 인증
• 공유 액세스 서명 인증
• 시스템이 할당한 관리 ID 인증
• 사용자가 할당한 관리 ID 인증

계정 키 인증

Data Factory는 Azure Files 계정 키 인증에 대해 다음 속성을 지원합니다.

예제:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "connectionString": "DefaultEndpointsProtocol=https;AccountName=<accountName>;AccountKey=<accountKey>;EndpointSuffix=core.windows.net;",
            "fileShare": "<file share name>"
        },
        "connectVia": {
          "referenceName": "<name of Integration Runtime>",
          "type": "IntegrationRuntimeReference"
        }
    }
}

예: Azure Key Vault에 계정 키 저장

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "connectionString": "DefaultEndpointsProtocol=https;AccountName=<accountname>;",
            "fileShare": "<file share name>",
            "accountKey": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<Azure Key Vault linked service name>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<secretName>" 
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }            
    }
}

공유 액세스 서명 인증

공유 액세스 서명은 스토리지 계정의 리소스에 대한 위임된 권한을 제공합니다. 공유 액세스 서명을 사용하여 스토리지 계정의 개체에 대해 지정된 시간 동안 제한된 권한을 클라이언트에 부여할 수 있습니다. 공유 액세스 서명에 대한 자세한 내용은 공유 액세스 서명: 공유 액세스 서명 모델 이해를 참조하세요.

서비스는 공유 액세스 서명 인증을 사용하기 위해 다음 속성을 지원합니다.

예제:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "sasUri": {
                "type": "SecureString",
                "value": "<SAS URI of the resource e.g. https://<accountname>.file.core.windows.net/?sv=<storage version>&st=<start time>&se=<expire time>&sr=<resource>&sp=<permissions>&sip=<ip range>&spr=<protocol>&sig=<signature>>"
            },
            "fileShare": "<file share name>",
            "snapshot": "<snapshot version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

예: Azure Key Vault에 SAS 토큰 저장

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "sasUri": {
                "type": "SecureString",
                "value": "<SAS URI of the Azure Storage resource without token e.g. https://<accountname>.file.core.windows.net/>"
            },
            "sasToken": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<Azure Key Vault linked service name>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<secretName with value of SAS token e.g. ?sv=<storage version>&st=<start time>&se=<expire time>&sr=<resource>&sp=<permissions>&sip=<ip range>&spr=<protocol>&sig=<signature>>" 
            },
            "fileShare": "<file share name>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

시스템이 할당한 관리 ID 인증

데이터 팩터리 또는 Synapse 파이프라인은 다른 Azure 서비스에 대한 인증을 위해 해당 리소스를 나타내는 Azure 리소스용 시스템 할당 관리 ID와 연결될 수 있습니다. Azure Files 인증에 시스템에서 할당한 이 관리 ID를 사용할 수 있습니다. Azure 리소스에 대한 관리 ID에 대한 자세한 내용은 Azure 리소스에 대한 관리 ID란?을 참조하세요.

시스템이 할당한 관리 ID 인증을 사용하려면 다음 단계를 수행합니다.

1. 팩터리 또는 Synapse 작업 영역과 함께 생성된 시스템 할당 관리 ID 개체 ID 값을 복사하여 시스템 할당 관리 ID 정보를 검색합니다.

2. Azure Files에서 관리 ID 권한을 부여합니다. 역할에 대한 자세한 내용은 이 문서를 참조하세요.

   • 원본의 경우 액세스 제어(IAM)에서 최소한 스토리지 파일 데이터 권한이 있는 읽기 권한자 역할을 부여합니다.
   • 싱크의 경우 액세스 제어(IAM)에서 최소한 스토리지 파일 데이터 권한 있는 기여자 역할을 부여합니다.

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

예제:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {            
            "serviceEndpoint": "https://<accountName>.file.core.windows.net/",
            "fileShare": "<file share name>",
            "snapshot": "<snapshot version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

사용자가 할당한 관리 ID 인증

데이터 팩터리는 하나 이상의 사용자가 할당한 관리 ID로 할당할 수 있습니다. Azure Files 인증에 사용자가 할당한 관리 ID를 사용하면 Azure Files에 액세스하고 데이터를 복사할 수 있습니다. Azure 리소스에 대한 관리 ID에 대한 자세한 내용은 Azure 리소스에 대한 관리 ID란?을 참조하세요.

사용자가 할당한 관리 ID 인증을 사용하려면 다음 단계를 수행합니다.

1. 사용자가 할당한 관리 ID를 하나 이상 만들고 Azure Files에서 권한을 부여합니다. 역할에 대한 자세한 내용은 이 문서를 참조하세요.

   • 원본의 경우 액세스 제어(IAM)에서 최소한 스토리지 파일 데이터 권한이 있는 읽기 권한자 역할을 부여합니다.
   • 싱크의 경우 액세스 제어(IAM)에서 최소한 스토리지 파일 데이터 권한 있는 기여자 역할을 부여합니다.

2. 하나 이상의 사용자가 할당한 관리 ID를 데이터 팩터리에 할당하고 각 사용자가 할당한 관리 ID에 대한 자격 증명을 만듭니다.

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

예제:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {            
            "serviceEndpoint": "https://<accountName>.file.core.windows.net/",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            },
            "fileShare": "<file share name>",
            "snapshot": "<snapshot version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

레거시 모델

예제:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "host": "\\\\<storage name>.file.core.windows.net\\<file service name>",
            "userid": "AZURE\\<storage name>",
            "password": {
                "type": "SecureString",
                "value": "<storage access key>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

데이터 세트 속성

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

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

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

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

예제:

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

복사 작업 속성

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

원본 파일 형태의 Azure Files

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

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

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

예제:

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

싱크로서의 Azure Files

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

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

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

예제:

"activities":[
    {
        "name": "CopyToAzureFileStorage",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Parquet output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "ParquetSink",
                "storeSettings":{
                    "type": "AzureFileStorageWriteSettings",
                    "copyBehavior": "PreserveHierarchy"
                }
            }
        }
    }
]

폴더 및 파일 필터 예제

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

파일 목록 예

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

원본 폴더 구조가 다음과 같고 굵게 표시된 파일을 복사하려는 것으로 가정합니다.

recursive 및 copyBehavior 예제

이 섹션에서는 다양한 recursive 및 copyBehavior 값 조합에 대한 복사 작업의 결과 동작을 설명합니다.

조회 작업 속성

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

GetMetadata 작업 속성

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

삭제 작업 속성

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

레거시 모델

레거시 데이터 세트 모델

예제:

{
    "name": "AzureFileStorageDataset",
    "properties": {
        "type": "FileShare",
        "linkedServiceName":{
            "referenceName": "<Azure File Storage 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"
            }
        }
    }
}

레거시 복사 작업 원본 모델

예제:

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

레거시 복사 작업 싱크 모델

예제:

"activities":[
    {
        "name": "CopyToAzureFileStorage",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Azure File Storage output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "FileSystemSink",
                "copyBehavior": "PreserveHierarchy"
            }
        }
    }
]

관련 콘텐츠

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