Azure Data Factory 또는 Azure Synapse Analytics를 사용하여 Microsoft Fabric 웨어하우스에서 데이터 복사 및 변환

적용 대상: Azure Data Factory Azure Synapse Analytics

이 문서에서는 복사 작업을 사용하여 Microsoft Fabric 웨어하우스에서 데이터를 복사하는 방법을 간략하게 설명합니다. 자세한 내용은 Azure Data Factory 또는 Azure Synapse Analytics의 소개 문서를 참조하세요.

지원되는 기능

이 Microsoft Fabric 웨어하우스 커넥터는 다음 기능을 지원합니다.

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

시작하기

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

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

UI를 사용하여 Microsoft Fabric 웨어하우스 연결된 서비스 만들기

Azure Portal UI에서 Microsoft Fabric 웨어하우스 연결된 서비스를 만들려면 다음 단계를 따릅니다.

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

   • Azure Data Factory
   • Azure Synapse

   

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

   

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

   

커넥터 구성 세부 정보

다음 섹션에서는 Microsoft Fabric 웨어하우스와 관련된 Data Factory 엔터티를 정의하는 데 사용되는 속성에 대한 세부 정보를 제공합니다.

연결된 서비스 속성

Microsoft Fabric 웨어하우스 커넥터는 다음 인증 유형을 지원합니다. 자세한 내용은 해당 섹션을 참조하세요.

• 서비스 주체 인증

서비스 주체 인증

서비스 주체 인증을 사용하려면 다음 단계를 수행합니다.

1. Microsoft ID 플랫폼에 애플리케이션을 등록하고 클라이언트 암호를 추가합니다. 그런 다음 연결된 서비스를 정의하는 데 사용하는 다음 값을 기록해 두세요.

   • 연결된 서비스의 서비스 주체 ID인 애플리케이션(클라이언트) ID입니다.
   • 연결된 서비스의 서비스 주체 키인 클라이언트 암호 값입니다.
   • 테넌트 ID

2. 서비스 주체에게 Microsoft Fabric 작업 영역에서 최소한 기여자 역할을 부여합니다. 다음 단계를 수행합니다.

   1. Microsoft Fabric 작업 영역으로 이동하여 상단 표시줄에서 액세스 관리를 선택합니다. 그런 다음, 사용자 또는 그룹 추가를 선택합니다.

      

      

   2. 사용자 추가 창에서 서비스 주체 이름을 입력하고 드롭다운 목록에서 서비스 주체를 선택합니다.

   3. 역할을 기여자 이상(관리자, 멤버)으로 지정한 다음, 추가를 선택합니다.

      

   4. 서비스 주체가 액세스 관리 창에 표시됩니다.

연결된 서비스에 지원되는 속성은 다음과 같습니다.

예: 서비스 주체 키 인증 사용

Azure Key Vault에 서비스 주체 키를 저장할 수도 있습니다.

{
    "name": "MicrosoftFabricWarehouseLinkedService",
    "properties": {
        "type": "Warehouse",
        "typeProperties": {
            "endpoint": "<Microsoft Fabric Warehouse server endpoint>",
            "workspaceId": "<Microsoft Fabric workspace ID>",
            "artifactId": "<Microsoft Fabric Warehouse object ID>",
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalKey",
            "servicePrincipalCredential": {
                "type": "SecureString",
                "value": "<service principal key>"
            }   
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

데이터 세트 속성

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

Microsoft Fabric 웨어하우스 데이터 세트에는 다음 속성이 지원됩니다.

데이터 세트 속성 예제

{
    "name": "FabricWarehouseTableDataset",
    "properties": {
        "type": "WarehouseTable",
        "linkedServiceName": {
            "referenceName": "<Microsoft Fabric Warehouse linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, retrievable during authoring >
        ],
        "typeProperties": {
            "schema": "<schema_name>",
            "table": "<table_name>"
        }
    }
}

복사 작업 속성

작업 정의에 사용할 수 있는 섹션 및 속성의 전체 목록은 복사 작업 구성과 파이프라인 및 작업 문서를 참조하세요. 이 섹션에서는 Microsoft Fabric 웨어하우스 원본 및 싱크에서 지원되는 속성 목록을 제공합니다.

Microsoft Fabric 웨어하우스를 원본으로 사용

Microsoft Fabric 웨어하우스에서 데이터를 복사하려면 복사 작업 원본의 type 속성을 WarehouseSource로 설정합니다. 복사 작업 source 섹션에서 지원되는 속성은 다음과 같습니다.

예: SQL 쿼리 사용

"activities":[
    {
        "name": "CopyFromMicrosoftFabricWarehouse",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Microsoft Fabric Warehouse input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "WarehouseSource",
                "sqlReaderQuery": "SELECT * FROM MyTable"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

예: 저장 프로시저 사용

"activities":[
    {
        "name": "CopyFromMicrosoftFabricWarehouse",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Microsoft Fabric Warehouse input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "WarehouseSource",
                "sqlReaderStoredProcedureName": "CopyTestSrcStoredProcedureWithParameters",
                "storedProcedureParameters": {
                    "stringData": { "value": "str3" },
                    "identifier": { "value": "$$Text.Format('{0:yyyy}', <datetime parameter>)", "type": "Int"}
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

샘플 저장 프로시저:

CREATE PROCEDURE CopyTestSrcStoredProcedureWithParameters
(
    @stringData varchar(20),
    @identifier int
)
AS
SET NOCOUNT ON;
BEGIN
    select *
    from dbo.UnitTestSrcTable
    where dbo.UnitTestSrcTable.stringData != stringData
    and dbo.UnitTestSrcTable.identifier != identifier
END
GO

싱크 형식의 Microsoft Fabric 웨어하우스

Azure Data Factory 및 Synapse 파이프라인은 Microsoft Fabric 웨어하우스에 데이터를 로드하기 위해 COPY 문 사용을 지원합니다.

데이터를 Microsoft Fabric 웨어하우스에 복사하려면 복사 작업에서 싱크 유형을 WarehouseSink로 설정합니다. 복사 작업 sink 섹션에서 지원되는 속성은 다음과 같습니다.

예: Microsoft Fabric 웨어하우스 싱크

"activities":[
    {
        "name": "CopyToMicrosoftFabricWarehouse",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Microsoft Fabric Warehouse output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "WarehouseSink",
                "allowCopyCommand": true,
                "tableOption": "autoCreate",
                "disableMetricsCollection": false
            }
        }
    }
]

Microsoft Fabric 웨어하우스의 병렬 복사

복사 작업의 Microsoft Fabric 웨어하우스 커넥터는 데이터를 병렬로 복사하기 위한 기본 제공 데이터 분할을 제공합니다. 복사 작업의 원본 탭에서 데이터 분할 옵션을 찾을 수 있습니다.

분할된 복사를 사용하도록 설정하면 복사 작업은 Microsoft Fabric 웨어하우스 원본에 대해 병렬 쿼리를 실행하여 파티션별로 데이터를 로드합니다. 병렬 수준은 복사 작업의 parallelCopies 설정에 의해 제어됩니다. 예를 들어, parallelCopies를 4로 설정하면 서비스는 지정된 파티션 옵션 및 설정을 기반으로 4개의 쿼리를 동시에 생성하고 실행하며, 각 쿼리는 Microsoft Fabric 웨어하우스에서 데이터의 일부를 쿼리합니다.

특히 Microsoft Fabric 웨어하우스에서 대량의 데이터를 로드하는 경우 데이터 분할을 통해 병렬 복사를 사용하도록 설정하는 것이 좋습니다. 다양한 시나리오에 대해 권장되는 구성은 다음과 같습니다. 파일 기반 데이터 저장소에 데이터를 복사할 때 여러 파일로 폴더에 쓰는 것이 좋습니다(폴더 이름만 지정). 이 경우 단일 파일에 쓰는 것보다 성능이 좋습니다.

파티션 옵션을 사용하여 데이터를 로드하는 모범 사례:

• 데이터 기울이기를 방지하려면 고유한 열(예: 기본 키 또는 고유 키)을 분할 열로 선택합니다.
• Azure Integration Runtime을 사용하여 데이터를 복사하는 경우 더 많은 컴퓨팅 리소스를 활용할 수 있도록 더 큰 “DIU(데이터 통합 ​​단위)”(>4)를 설정할 수 있습니다. 여기서 적용 가능한 시나리오를 확인합니다.
• "복사 병렬 처리 수준"은 파티션 수를 제어합니다. 이 수를 너무 크게 설정하면 성능이 저하되는 경우가 있습니다. 이 수를 (DIU 또는 자체 호스팅 IR 노드 수) * (2~4)로 설정하는 것이 좋습니다.
• Microsoft Fabric 웨어하우스는 한 번에 최대 32개의 쿼리를 실행할 수 있으므로 "복사 병렬 처리 수준"을 너무 크게 설정하면 Warehouse 제한 문제가 발생할 수 있습니다.

예: 동적 범위 파티션이 있는 쿼리

"source": {
    "type": "WarehouseSource",
    "query": "SELECT * FROM <TableName> WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause>",
    "partitionOption": "DynamicRange",
    "partitionSettings": {
        "partitionColumnName": "<partition_column_name>",
        "partitionUpperBound": "<upper_value_of_partition_column (optional) to decide the partition stride, not as data filter>",
        "partitionLowerBound": "<lower_value_of_partition_column (optional) to decide the partition stride, not as data filter>"
    }
}

COPY 문을 사용하여 Microsoft Fabric 웨어하우스에 데이터 로드

COPY 문을 사용하면 높은 처리량으로 Microsoft Fabric 웨어하우스에 데이터를 로드할 수 있는 간단하고 유연한 방법입니다. 자세한 내용을 보려면 COPY 문을 사용하여 데이터 대량 로드를 확인합니다.

• 원본 데이터가 Azure Blob 또는 Azure Data Lake Storage Gen2이고 형식이 COPY 문과 호환인 경우 복사 작업을 사용하여 COPY 문을 직접 호출하여 Microsoft Fabric 웨어하우스가 원본에서 데이터를 가져오도록 합니다. 자세한 내용은 COPY 문을 사용하여 직접 복사를 참조하세요.
• 원본 데이터 저장소와 형식이 COPY 문에서 원래 지원되지 않는 경우, 대신 COPY 문을 사용한 준비된 복사 기능을 사용합니다. 또한 단계적 복사 기능은 더 나은 처리량을 제공합니다. 자동으로 데이터를 COPY 문 호환 형식으로 변환하고, Azure Blob Storage에 데이터를 저장한 다음, COPY 문을 호출하여 데이터를 Microsoft Fabric 웨어하우스에 로드합니다.

COPY 문을 사용하여 직접 복사

Microsoft Fabric 웨어하우스 COPY 문은 Azure Blob, Azure Data Lake Storage Gen1 및 Azure Data Lake Storage Gen2를 직접 지원합니다. 원본 데이터가 이 섹션에 설명된 기준을 충족하는 경우 COPY 문을 사용하여 원본 데이터 저장소에서 Microsoft Fabric 웨어하우스로 직접 복사합니다. 그렇지 않은 경우, COPY 문을 사용한 준비된 복사를 사용합니다. 이 서비스는 설정을 확인하고 조건이 충족되지 않으면 복사 작업 실행에 실패합니다.

• 원본 연결된 서비스 및 형식은 다음과 같은 유형 및 인증 방법을 사용합니다.

  지원되는 원본 데이터 저장소 형식	지원되는 형식	지원되는 원본 인증 유형
  Azure Blob	구분된 텍스트	계정 키 인증, 공유 액세스 서명 인증
  	Parquet	계정 키 인증, 공유 액세스 서명 인증
  Azure Data Lake Storage Gen2	구분된 텍스트 Parquet	계정 키 인증, 공유 액세스 서명 인증

• 형식 설정에는 다음이 포함됩니다.

  • Parquet의 경우: compression은 압축 없음, Snappy 또는 GZip일 수 있습니다.
  • 구분 된 텍스트의 경우:
    • rowDelimiter는 단일 문자 또는 "\r\n"으로 명시적으로 설정됩니다. 기본값은 지원되지 않습니다.
    • nullValue는 기본값으로 남아 있거나 빈 문자열("")로 설정됩니다.
    • encodingName는 기본값으로 남아 있거나 utf-8 또는 utf-16으로 설정됩니다.
    • escapeChar는 quoteChar와 동일해야 하며 비어 있지 않습니다.
    • skipLineCount는 기본값으로 남아 있거나 0으로 설정됩니다.
    • compression는 압축 안 함 또는 GZip일 수 있습니다.

• 원본이 폴더인 경우 복사 작업의 recursive를 true로 설정해야 하며 wildcardFilename는 * 또는 *.*이어야 합니다.

• wildcardFolderPath, wildcardFilename(* 또는 *.* 이외), modifiedDateTimeStart, modifiedDateTimeEnd, prefix, enablePartitionDiscovery 및 additionalColumns는 지정되지 않습니다.

복사 작업의 allowCopyCommand에서 다음 COPY 문 설정이 지원됩니다.

"activities":[
    {
        "name": "CopyFromAzureBlobToMicrosoftFabricWarehouseViaCOPY",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "ParquetDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "MicrosoftFabricWarehouseDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "ParquetSource",
                "storeSettings":{
                    "type": "AzureBlobStorageReadSettings",
                    "recursive": true
                }
            },
            "sink": {
                "type": "WarehouseSink",
                "allowCopyCommand": true,
                "copyCommandSettings": {
                    "defaultValues": [
                        {
                            "columnName": "col_string",
                            "defaultValue": "DefaultStringValue"
                        }
                    ],
                    "additionalOptions": {
                        "MAXERRORS": "10000",
                        "DATEFORMAT": "'ymd'"
                    }
                }
            },
            "enableSkipIncompatibleRow": true
        }
    }
]

COPY 문을 사용한 준비된 복사

원본 데이터가 COPY 문과 기본적으로 호환되지 않는 경우 중간 준비 Azure Blob 또는 Azure Data Lake Storage Gen2(Azure Premium Storage일 수 없음)를 통해 데이터 복사를 사용하도록 설정합니다. 이 경우, 이 서비스는 COPY 문의 데이터 형식 요구 사항을 충족하도록 데이터를 자동으로 변환합니다. 그런 다음 COPY 문을 호출하여 Microsoft Fabric 웨어하우스에 데이터를 로드합니다. 마지막으로 스토리지에서 임시 데이터를 정리합니다. 스테이징을 통한 데이터 복사에 대한 자세한 내용은 스테이징된 복사본을 참조하세요.

이 기능을 사용하려면 Azure Storage 계정을 중간 스토리지로 참조하는 계정 키 또는 시스템 관리 ID 인증으로 Azure Blob Storage에 연결된 서비스 또는 Azure Data Lake Storage Gen2에 연결된 서비스를 만듭니다.

"activities":[
    {
        "name": "CopyFromSQLServerToMicrosoftFabricWarehouseViaCOPYstatement",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "SQLServerDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "MicrosoftFabricWarehouseDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SqlSource",
            },
            "sink": {
                "type": "WarehouseSink",
                "allowCopyCommand": true
            },
            "stagingSettings": {
                "linkedServiceName": {
                    "referenceName": "MyStagingStorage",
                    "type": "LinkedServiceReference"
                }
            }
        }
    }
]

매핑 데이터 흐름 속성

매핑 데이터 흐름에서 데이터를 변환할 때 Microsoft Fabric Warehouse에서 테이블을 읽고 쓸 수 있습니다. 자세한 내용은 매핑 데이터 흐름에서 원본 변환 및 싱크 변환을 참조하세요.

Microsoft Fabric 웨어하우스를 원본으로 사용

Microsoft Fabric Warehouse에 특정한 설정은 원본 변환의 원본 옵션 탭에서 사용할 수 있습니다.

Microsoft Fabric Warehouse를 싱크로

Microsoft Fabric Warehouse에 특정한 설정은 싱크 변환의 설정 탭에서 사용할 수 있습니다.

오류 행 처리

기본적으로 첫 번째 오류가 발생할 때 데이터 흐름 실행이 실패합니다. 개별 행에 오류가 있는 경우에도 데이터 흐름이 완료될 수 있도록 오류 발생 시 계속을 선택할 수 있습니다. 서비스는 이러한 오류 행을 처리하는 다양한 옵션을 제공합니다.

트랜잭션 커밋: 데이터를 단일 트랜잭션으로 쓸지 또는 일괄로 쓸지를 선택합니다. 단일 트랜잭션은 더 나은 성능을 제공하며 트랜잭션이 완료될 때까지 기록된 데이터가 다른 사용자에게 표시되지 않습니다. 일괄 처리 트랜잭션은 성능이 저하되지만 큰 데이터 세트에 대해 작동할 수 있습니다.

거부된 데이터 출력: 사용하도록 설정된 경우 선택한 Azure Blob Storage 또는 선택한 Azure Data Lake Storage Gen2 계정의 csv 파일에 오류 행을 출력할 수 있습니다. 이렇게 하면 세 개의 추가 열, 즉 INSERT 또는 UPDATE와 같은 SQL 작업, 데이터 흐름 오류 코드 및 오류 메시지를 포함하는 오류 행이 기록됩니다.

오류 발생 시 성공 보고: 사용하도록 설정된 경우 오류 행이 있는 경우에도 데이터 흐름이 성공으로 표시됩니다.

조회 작업 속성

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

GetMetadata 작업 속성

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

Microsoft Fabric 웨어하우스에 대한 데이터 형식 매핑

Microsoft Fabric 웨어하우스에서 데이터를 복사하는 경우 Microsoft Fabric 웨어하우스 데이터 형식에서 내부적으로 서비스 내의 중간 데이터 형식으로 다음 매핑이 사용됩니다. 복사 활동에서 원본 스키마와 데이터 형식을 싱크에 매핑하는 방법에 대한 자세한 내용은 스키마 및 데이터 형식 매핑을 참조하세요.

다음 단계

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