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

적용 대상: Azure Data Factory Azure Synapse Analytics

팁

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

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

지원되는 기능

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

지원되는 기능	IR	관리형 프라이빗 엔드포인트
복사 작업(원본/싱크)	3,4
매핑 데이터 흐름(원본/싱크)	9
조회 작업	3,4
GetMetadata 작업	3,4
스크립트 작업	3,4
저장 프로시저 작업	3,4

① 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. 서비스 주체가 액세스 관리 창에 표시됩니다.

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

속성	설명	필수
type	type 속성은 Warehouse로 설정되어야 합니다.	예
endpoint	Microsoft Fabric 웨어하우스 서버의 엔드포인트.	예
workspaceId	Microsoft Fabric 작업 영역 ID입니다.	예
artifactId	Microsoft Fabric 웨어하우스 개체 ID.	예
테넌트	애플리케이션이 있는 테넌트 정보(도메인 이름 또는 테넌트 ID)를 지정합니다. Azure 포털의 오른쪽 위 모서리를 마우스로 가리켜 검색합니다.	예
servicePrincipalId	애플리케이션의 클라이언트 ID를 지정합니다.	예
servicePrincipalCredentialType	서비스 주체 인증에 사용할 자격 증명 유형입니다. 허용되는 값은 ServicePrincipalKey 및 ServicePrincipalCert입니다.	예
servicePrincipalCredential	서비스 주체 자격 증명입니다. 자격 증명 형식으로 ServicePrincipalKey를 사용하는 경우 애플리케이션의 클라이언트 암호 값을 지정합니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나 Azure Key Vault에 저장된 비밀을 참조합니다. ServicePrincipalCert를 자격 증명으로 사용하는 경우 Azure Key Vault에서 인증서를 참조하고 인증서 콘텐츠 형식이 PKCS #12인지 확인합니다.	예
connectVia	데이터 저장소에 연결하는 데 사용할 통합 런타임입니다. Azure 통합 런타임 또는 데이터 저장소가 프라이빗 네트워크에 있는 경우 자체 호스팅 통합 런타임을 사용할 수 있습니다. 지정하지 않으면 기본 Azure 통합 런타임이 사용됩니다.	아니요

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

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 웨어하우스 데이터 세트에는 다음 속성이 지원됩니다.

속성	설명	필수
type	데이터 세트의 type 속성은 WarehouseTable로 설정되어야 합니다.	예
schema(스키마)	스키마의 이름입니다.	원본에는 아니요이고 싱크에는 예입니다
table	테이블/뷰의 이름입니다.	원본에는 아니요이고 싱크에는 예입니다

데이터 세트 속성 예제

{
    "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 웨어하우스에서 데이터를 효율적으로 로드하려면 Microsoft Fabric 웨어하우스의 병렬 복사에서 자세히 알아봅니다.

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

속성	설명	필수
type	복사 작업 원본의 type 속성은 WarehouseSource로 설정되어야 합니다.	예
SqlReaderQuery	사용자 지정 SQL 쿼리를 사용하여 데이터를 읽습니다. 예: select * from MyTable	아니요
sqlReaderStoredProcedureName	원본 테이블에서 데이터를 읽는 저장 프로시저의 이름입니다. 마지막 SQL 문은 저장 프로시저의 SELECT 문이어야 합니다.	아니요
storedProcedureParameters	저장 프로시저에 대한 매개 변수입니다. 허용되는 값은 이름 또는 값 쌍입니다. 매개 변수의 이름 및 대소문자와, 저장 프로시저 매개변수의 이름 및 대소문자와 일치해야 합니다.	아니요
queryTimeout	쿼리 명령 실행에 대한 시간 제한을 지정합니다. 기본값은 120분입니다.	아니요
isolationLevel	SQL 원본에 대한 트랜잭션 잠금 동작을 지정합니다. 허용되는 값은 Snapshot입니다. 지정하지 않으면 데이터베이스의 기본 격리 수준이 사용됩니다. 자세한 내용은 system.data.isolationlevel을 참조하세요.	아니요
partitionOptions	Microsoft Fabric 웨어하우스에서 데이터를 로드하는 데 사용되는 데이터 분할 옵션을 지정합니다. 허용되는 값은 None(기본값) 및 DynamicRange입니다. 파티션 옵션이 사용하도록 설정되면(즉, None이 아님), Microsoft Fabric 웨어하우스에서 데이터를 동시에 로드하는 병렬 처리 수준은 복사 작업의 parallelCopies 설정에 의해 제어됩니다.	아니요
partitionSettings	데이터 분할에 대한 설정 그룹을 지정합니다. 파티션 옵션이 None이 아닌 경우 적용됩니다.	아니요
partitionSettings에서:
partitionColumnName	병렬 복사를 위해 범위 분할에서 사용할 원본 열의 이름을 정수, 날짜 또는 날짜/시간 형식(int, smallint, bigint, date, datetime2)으로 지정합니다. 지정하지 않으면 테이블의 인덱스 또는 기본 키가 자동으로 검색되어 파티션 열로 사용됩니다. 파티션 옵션이 DynamicRange인 경우에 적용됩니다. 쿼리를 사용하여 원본 데이터를 검색하는 경우 WHERE 절에서 ?DfDynamicRangePartitionCondition를 후크합니다. 예를 보려면 Microsoft Fabric 웨어하우스의 병렬 복사 섹션을 참조하세요.	아니요
partitionUpperBound	파티션 범위 분할에 대한 파티션 열의 최댓값입니다. 이 값은 테이블의 행을 필터링하는 것이 아니라 파티션 진행 속도를 결정하는 데 사용됩니다. 테이블 또는 쿼리 결과의 모든 행이 분할되고 복사됩니다. 지정하지 않으면 복사 작업에서 값을 자동으로 검색합니다. 파티션 옵션이 DynamicRange인 경우에 적용됩니다. 예를 보려면 Microsoft Fabric 웨어하우스의 병렬 복사 섹션을 참조하세요.	아니요
partitionLowerBound	파티션 범위 분할에 대한 파티션 열의 최솟값입니다. 이 값은 테이블의 행을 필터링하는 것이 아니라 파티션 진행 속도를 결정하는 데 사용됩니다. 테이블 또는 쿼리 결과의 모든 행이 분할되고 복사됩니다. 지정하지 않으면 복사 작업에서 값을 자동으로 검색합니다. 파티션 옵션이 DynamicRange인 경우에 적용됩니다. 예를 보려면 Microsoft Fabric 웨어하우스의 병렬 복사 섹션을 참조하세요.	아니요

참고 항목

원본에서 저장 프로시저를 사용하여 데이터를 검색하는 경우 다른 매개 변수 값이 전달될 때 저장 프로시저에서 다른 스키마를 반환하도록 설계되면 UI에서 스키마를 가져오거나 자동 테이블 만들기를 사용하여 데이터를 Microsoft Fabric 웨어하우스에 복사할 때 예기치 않은 결과가 발생할 수 있습니다.

예: 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 섹션에서 지원되는 속성은 다음과 같습니다.

속성	설명	필수
type	복사 작업 싱크의 type 속성은 WarehouseSink로 설정되어야 합니다.	예
allowCopyCommand	Microsoft Fabric 웨어하우스에 데이터를 로드하기 위해 COPY 문을 사용할지 여부를 나타냅니다. 제약 조건사항과 세부 정보는 COPY 문을 사용하여 Microsoft Fabric 웨어하우스에 데이터 로드 섹션을 참조하세요. 허용되는 값은 True입니다.	예
copyCommandSettings	allowCopyCommand 속성이 TRUE로 설정된 경우 지정될 수 있는 속성의 그룹입니다.	아니요
writeBatchTimeout	이 속성은 삽입, upsert 및 저장 프로시저 작업이 시간 초과되기 전에 완료될 때까지의 대기 시간을 지정합니다. 허용되는 값은 timespan입니다. 예를 들어 30분인 경우 "00:30:00"입니다. 값을 지정하지 않으면 시간 제한은 기본적으로 "00:30:00"으로 설정됩니다.	아니요
preCopyScript	실행할 때마다 Microsoft Fabric 웨어하우스에 데이터를 쓰기 전에 실행할 복사 작업에 대한 SQL 쿼리를 지정합니다. 이 속성을 사용하여 미리 로드된 데이터를 정리합니다.	아니요
tableOption	원본 스키마에 따라 존재하지 않는 경우 싱크 테이블을 자동으로 만들지 여부를 지정합니다. 허용되는 값은 none(기본값) 또는 autoCreate입니다.	아니요
disableMetricsCollection	이 서비스는 복사 성능 최적화 및 권장 사항을 위해 메트릭을 수집하여 추가 마스터 DB 액세스를 도입합니다. 이 동작에 관심이 있는 경우 true를 지정하여 해제합니다.	아니요(기본값: false)

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

시나리오	제안된 설정
데이터 분할을 위한 정수 또는 날짜/시간 열을 사용하면서 대규모 테이블에서 전체 로드를 수행합니다.	파티션 옵션: 동적 범위 파티션입니다. 파티션 열(선택 사항): 데이터를 분할하는 데 사용되는 열을 지정합니다. 지정하지 않으면 인덱스 또는 기본 키 열이 사용됩니다. 파티션 상한 및 파티션 하한(선택 사항): 파티션 진행 속도를 결정할지 여부를 지정합니다. 이는 테이블의 행을 필터링하기 위한 것이 아니며, 테이블의 모든 행을 분할하고 복사합니다. 지정하지 않으면 복사 작업에서 자동으로 값을 검색합니다. 예를 들어, “ID” 파티션 열의 값 범위가 1~100이고, 하한을 20으로 설정하고, 상한을 80으로 설정하고, 병렬 복사를 4로 설정하면 서비스에서 4개의 파티션별로(각각 ID 범위: <=20, [21, 50], [51, 80] 및 >=81) 데이터를 검색합니다.
데이터 분할을 위한 정수, 날짜 또는 날짜/시간 열을 사용하면서 사용자 지정 쿼리를 사용하여 대량의 데이터를 로드합니다.	파티션 옵션: 동적 범위 파티션입니다. 쿼리:SELECT * FROM <TableName> WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause>. 파티션 열: 데이터를 분할하는 데 사용되는 열을 지정합니다. 파티션 상한 및 파티션 하한(선택 사항): 파티션 진행 속도를 결정할지 여부를 지정합니다. 이는 테이블의 행을 필터링하기 위한 것이 아니며, 쿼리 결과의 모든 행을 분할하고 복사합니다. 지정하지 않으면 복사 작업에서 값을 자동으로 검색합니다. 예를 들어 "ID" 파티션 열의 값 범위가 1~100이고 하한을 20으로 설정하고 상한을 80으로 설정하고 병렬 복사를 4로 설정하면 서비스에서 4개의 파티션별로(각각 ID 범위: <=20, [21, 50], [51, 80] 및 >=81) 데이터를 검색합니다. 다양한 시나리오에 대한 추가 샘플 쿼리는 다음과 같습니다. 1. 전체 테이블 쿼리: SELECT * FROM <TableName> WHERE ?DfDynamicRangePartitionCondition 2. 열을 선택하고 where 절 필터를 추가하여 테이블 쿼리: SELECT <column_list> FROM <TableName> WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause> 3. 하위 쿼리를 사용하여 쿼리: SELECT <column_list> FROM (<your_sub_query>) AS T WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause> 4. 하위 쿼리에서 파티션을 사용하여 쿼리: SELECT <column_list> FROM (SELECT <your_sub_query_column_list> FROM <TableName> WHERE ?DfDynamicRangePartitionCondition) AS T

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

• 데이터 기울이기를 방지하려면 고유한 열(예: 기본 키 또는 고유 키)을 분할 열로 선택합니다.
• 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 웨어하우스에 로드합니다.

팁

Azure Integration Runtime과 함께 COPY 문을 사용할 때 효과적인 DIU(데이터 통합 ​​단위)는 항상 2입니다. DIU를 튜닝해도 성능에는 영향이 없습니다.

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 문 설정이 지원됩니다.

속성	설명	필수
defaultValues	Microsoft Fabric 웨어하우스의 각 대상 열에 대한 기본값을 지정합니다. 속성의 기본값은 데이터 웨어하우스의 기본 제약 조건 집합을 덮어쓰고 ID 열에는 기본값을 사용할 수 없습니다.	아니요
additionalOptions	COPY 문의 "With" 절에 있는 Microsoft Fabric 웨어하우스 COPY 문에 직접 전달되는 추가 옵션입니다. 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에 연결된 서비스를 만듭니다.

Important

• 스테이징하는 연결된 서비스에 관리 ID 인증을 사용하는 경우 Azure Blob 및 Azure Data Lake Storage Gen2 각각에 필요한 구성을 알아봅니다.
• 스테이징 Azure Storage가 VNet 서비스 엔드포인트로 구성된 경우 스토리지 계정에 "신뢰할 수 있는 Microsoft 서비스 허용"이 사용하도록 설정된 관리 ID 인증을 사용해야 합니다. Azure Storage에서 VNet 서비스 엔드포인트 사용의 영향을 참조하세요.

Important

스테이징하는 Azure Storage가 관리형 프라이빗 엔드포인트로 구성되고 스토리지 방화벽이 사용하도록 설정된 경우 관리 ID 인증을 사용하고 Synapse SQL Server에 스토리지 Blob 데이터 판독기 권한을 부여하여 COPY 문 로드 중에 스테이징된 파일에 액세스할 수 있도록 해야 합니다.

"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에 특정한 설정은 원본 변환의 원본 옵션 탭에서 사용할 수 있습니다.

속성	설명	필수	허용되는 값	데이터 흐름 스크립트 속성
입력	원본을 테이블에서 가리키거나(Select * from tablename과 동일), 사용자 지정 SQL 쿼리를 입력하거나, 저장 프로시저에서 데이터를 검색할지 선택합니다. 쿼리: 입력 필드에서 쿼리를 선택하는 경우에는 원본에 대한 SQL 쿼리를 입력합니다. 이렇게 설정하면 데이터 세트에서 선택한 모든 테이블이 재정의됩니다. Order By 절은 여기서 지원되지 않지만 전체 SELECT FROM 문을 설정할 수 있습니다. 사용자 정의 테이블 함수를 사용할 수도 있습니다. select * from udfGetData()는 테이블을 반환하는 SQL의 UDF입니다. 이 쿼리는 데이터 흐름에서 사용할 수 있는 원본 테이블을 생성합니다. 쿼리를 사용하는 것은 테스트 또는 조회를 위해 행을 줄이는 좋은 방법이기도 합니다.SQL 예제: Select * from MyTable where customerId > 1000 and customerId < 2000	예	테이블 또는 쿼리 또는 저장 프로시저	형식: 'table'
Batch 크기	일괄 처리 크기를 입력하여 대량 데이터를 읽기로 청크합니다. 데이터 흐름에서 이 설정을 사용하여 Spark 열 형식 캐싱을 설정합니다. 이 필드는 비어 있는 경우 Spark 기본값을 사용하는 옵션 필드입니다.	아니요	숫자 값	batchSize: 1234
격리 수준	매핑 데이터 흐름에서 SQL 원본의 기본값은 커밋되지 않은 읽기입니다. 여기에서 격리 수준을 다음 값 중 하나로 변경할 수 있습니다.• Read Committed • Read Uncommitted • Repeatable Read • Serializable • None (격리 수준 무시)	예	• Read Committed • Read Uncommitted • Repeatable Read • Serializable • None (격리 수준 무시)	isolationLevel

참고 항목

스테이징을 통한 읽기는 지원되지 않습니다. Microsoft Fabric Warehouse 원본에 대한 CDC 지원은 현재 사용할 수 없습니다.

Microsoft Fabric Warehouse를 싱크로

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

속성	설명	필수	허용되는 값	데이터 흐름 스크립트 속성
Update 메서드	데이터베이스 대상에서 허용되는 작업을 결정합니다. 기본값은 삽입만 허용하는 것입니다. 행을 업데이트, upsert 또는 삭제하려면 해당 작업을 위해 행에 태그를 지정하는 데 행 변경 변환이 필요합니다. 업데이트, upsert 및 삭제의 경우 변경할 행을 결정하기 위해 키 열을 설정해야 합니다.	예	true 또는 false	insertable deletable upsertable updateable
테이블 작업	쓰기 전에 대상 테이블에서 모든 행을 다시 만들거나 제거할지 여부를 결정합니다.• None: 테이블에 대한 아무런 작업도 수행되지 않습니다. • Recreate: 테이블이 삭제되고 다시 생성됩니다. 새 테이블을 동적으로 만드는 경우 필수입니다.• Truncate: 대상 테이블의 모든 행이 제거됩니다.	아니요	None 또는 recreate 또는 truncate	recreate: true truncate: true
준비 사용	스테이징 스토리지는 데이터 흐름 실행 작업에서 구성됩니다. 스토리지 연결된 서비스에 관리 ID 인증을 사용하는 경우 Azure Blob 및 Azure Data Lake Storage Gen2 각각에 필요한 구성에 대해 알아봅니다. Azure Storage가 VNet 서비스 엔드포인트로 구성된 경우 스토리지 계정에서 "신뢰할 수 있는 Microsoft 서비스 허용"이 사용하도록 설정된 관리 ID 인증을 사용해야 하며, Azure Storage에서 VNet 서비스 엔드포인트 사용의 영향을 참조하세요.	아니요	true 또는 false	staged: true
Batch 크기	각 버킷에 작성되는 행 수를 제어합니다. 일괄 처리 크기가 클수록 압축 및 메모리 최적화가 향상되지만 데이터를 캐시할 때 메모리 부족 예외가 발생할 위험이 있습니다.	아니요	숫자 값	batchSize: 1234
싱크 스키마 사용	기본적으로 임시 테이블은 싱크 스키마 아래에 스테이징으로 만들어집니다. 또는 싱크 스키마 사용 옵션을 선택 취소하고 대신 사용자 DB 스키마 선택에서 Data Factory가 업스트림 데이터를 로드하는 준비 테이블을 만들고 완료 시 자동으로 정리할 스키마 이름을 지정할 수 있습니다. 데이터베이스에 대한 테이블 만들기 권한과 스키마에 대한 변경 권한이 있는지 확인합니다.	아니요	true 또는 false	stagingSchemaName
사전 및 사후 SQL 스크립트	데이터를 싱크 데이터베이스에 기록하기 전(사전 처리)과 후(사후 처리)에 실행할 여러 줄 SQL 스크립트를 입력합니다.	아니요	SQL 스크립트	preSQLs:['set IDENTITY_INSERT mytable ON'] postSQLs:['set IDENTITY_INSERT mytable OFF'],

오류 행 처리

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

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

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

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

참고 항목

Microsoft Fabric Warehouse 연결된 서비스의 경우 서비스 주체에 대해 지원되는 인증 유형은 '키'입니다. '인증서' 인증은 지원되지 않습니다.

조회 작업 속성

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

GetMetadata 작업 속성

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

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

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

Microsoft Fabric 웨어하우스 데이터 형식	Data Factory 중간 데이터 형식
bigint	Int64
binary	Byte[]
bit	부울
char	String, Char[]
date	DateTime
datetime2	DateTime
소수	Decimal
FILESTREAM 특성(varbinary(max))	Byte[]
Float	Double
int	Int32
numeric	Decimal
real	Single
smallint	Int16
time	TimeSpan
uniqueidentifier	GUID
varbinary	Byte[]
varchar	String, Char[]

다음 단계

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