Azure Data Factory를 사용하여 Azure Cosmos DB for NoSQL에서 데이터 복사 및 변환

  • 아티클

적용 대상: Azure Data Factory Azure Synapse Analytics

팁

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

이 문서에서는 Azure Data Factory에서 복사 작업을 사용하여 Azure Cosmos DB for NoSQL 간에 데이터를 복사하고 Data Flow를 사용하여 Azure Cosmos DB for NoSQL에서 데이터를 변환하는 방법을 설명합니다. 자세한 내용은 Azure Data Factory 및 Azure Synapse Analytics의 소개 문서를 참조하세요.

참고 항목

이 커넥터는 Azure Cosmos DB for NoSQL만 지원합니다. Azure Cosmos DB for MongoDB의 경우 Azure Cosmos DB for MongoDB용 커넥터를 참조하세요. 다른 API 형식은 이제 지원되지 않습니다.

지원되는 기능

이 Azure Cosmos DB for NoSQL 커넥터는 다음 기능에 대해 지원됩니다.

지원되는 기능 IR 관리형 프라이빗 엔드포인트
복사 작업(원본/싱크) (1) (2) ✓
매핑 데이터 흐름(원본/싱크) (1) ✓
조회 작업 (1) (2) ✓

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

복사 작업의 경우 이 Azure Cosmos DB for NoSQL 커넥터는 다음을 지원합니다.

  • Azure 리소스 인증을 위해 키, 서비스 주체 또는 관리 ID를 사용하여 Azure Cosmos DB for NoSQL 간에 데이터를 복사합니다.
  • insert 또는 upsert로 Azure Cosmos DB에 씁니다.
  • JSON 문서를 있는 그대로 가져오고 내보내거나 데이터를 테이블 형식 데이터 세트 간에 복사합니다. 예로는 SQL 데이터베이스 및 CSV 파일이 있습니다. JSON 파일 간 또는 다른 Azure Cosmos DB 컬렉션 간에 문서를 있는 그대로 복사하려면 JSON 문서 가져오기 또는 내보내기를 참조하세요.

Data Factory 및 Synapse 파이프라인은 Azure Cosmos DB에 쓸 때 최상의 성능을 제공하기 위해 Azure Cosmos DB 대량 실행기 라이브러리와 통합됩니다.

팁

데이터 마이그레이션 동영상에서는 Azure Blob Storage에서 Azure Cosmos DB로 데이터를 복사하는 단계를 안내합니다. 이 동영상에서는 또한 일반적으로 Azure Cosmos DB에 데이터를 수집하기 위한 성능 조정 고려 사항도 설명합니다.

시작하기

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

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

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

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

  2. Azure Cosmos DB for NoSQL를 검색하고 Azure Cosmos DB for NoSQL 커넥터를 선택합니다.

    Azure Cosmos DB for NoSQL 커넥터를 선택합니다.

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

    Azure Cosmos DB에 대한 연결된 서비스 구성의 스크린샷

커넥터 구성 세부 정보

다음 섹션에서는 Azure Cosmos DB for NoSQL과 관련된 엔터티를 정의하는 데 사용할 수 있는 속성에 대한 세부 정보를 제공합니다.

연결된 서비스 속성

Azure Cosmos DB for NoSQL 커넥터는 다음 인증 형식을 지원합니다. 자세한 내용은 해당 섹션을 참조하세요.

키 인증

속성 설명 필수
type type 속성은 CosmosDb로 설정해야 합니다. 예
connectionString Azure Cosmos DB 데이터베이스에 연결하는 데 필요한 정보를 지정합니다.
참고: 다음 예제에 표시된 대로 연결 문자열에 데이터베이스 정보를 지정해야 합니다.
Azure Key Vault에 계정 키를 넣고, 연결 문자열에서 accountKey 구성을 끌어올 수도 있습니다. 자세한 내용은 다음 샘플 및 Azure Key Vault에 자격 증명 저장 문서를 참조하세요.		 예
connectVia 데이터 저장소에 연결하는 데 사용할 통합 런타임입니다. Azure Integration Runtime 또는 데이터 저장소가 프라이빗 네트워크에 있는 경우, 자체 호스팅 통합 런타임을 사용할 수 있습니다. 이 속성을 지정하지 않으면 기본 Azure Integration Runtime이 사용됩니다. 아니요

예제

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "connectionString": "AccountEndpoint=<EndpointUrl>;AccountKey=<AccessKey>;Database=<Database>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

예제: Azure Key Vault에 계정 키 저장

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "connectionString": "AccountEndpoint=<EndpointUrl>;Database=<Database>",
            "accountKey": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<Azure Key Vault linked service name>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<secretName>" 
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

서비스 주체 인증

참고 항목

현재 서비스 주체 인증은 데이터 흐름에서 지원되지 않습니다.

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

  1. Microsoft ID 플랫폼에 애플리케이션 등록 자세한 방법은 빠른 시작: Microsoft ID 플랫폼에 애플리케이션 등록을 참조하세요. 연결된 서비스를 정의하는 데 사용되므로 다음 값을 적어둡니다.

    • 애플리케이션 ID
    • 애플리케이션 키
    • 테넌트 ID

  2. 서비스 주체에게 적절한 사용 권한을 부여합니다. 파일 및 디렉터리에 대한 액세스 제어 목록에서 Azure Cosmos DB 권한이 작동하는 방식에 대한 예시를 참조하세요. 보다 구체적으로 역할 정의를 만들고 서비스 주체 개체 ID를 통해 서비스 주체에 역할을 할당합니다.

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

속성 설명 필수
type type 속성은 CosmosDb로 설정해야 합니다. 예
accountEndpoint Azure Cosmos DB 인스턴스에 대한 계정 엔드포인트 URL을 지정합니다. 예
database 데이터베이스의 이름을 지정합니다. 예
servicePrincipalId 애플리케이션의 클라이언트 ID를 지정합니다. 예
servicePrincipalCredentialType 서비스 주체 인증에 사용할 자격 증명 유형입니다. 허용되는 값은 ServicePrincipalKey 및 ServicePrincipalCert입니다. 예
servicePrincipalCredential 서비스 주체 자격 증명입니다.
ServicePrincipalKey를 자격 증명 유형으로 사용하는 경우 애플리케이션의 키를 지정합니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나 Azure Key Vault에 저장된 비밀을 참조합니다.
ServicePrincipalCert를 자격 증명으로 사용하는 경우 Azure Key Vault에서 인증서를 참조하고 인증서 콘텐츠 형식이 PKCS #12인지 확인합니다.		 예
테넌트 애플리케이션이 있는 테넌트 정보(도메인 이름 또는 테넌트 ID)를 지정합니다. Azure 포털의 오른쪽 위 모서리를 마우스로 가리켜 검색합니다. 예
azureCloudType 서비스 주체 인증의 경우 Microsoft Entra 애플리케이션이 등록된 Azure 클라우드 환경의 형식을 지정합니다.
허용되는 값은 AzurePublic, AzureChina, AzureUsGovernment, AzureGermany입니다. 기본적으로 이 서비스의 클라우드 환경이 사용됩니다.		 아니요
connectVia 데이터 저장소에 연결하는 데 사용할 통합 런타임입니다. Azure 통합 런타임 또는 데이터 저장소가 프라이빗 네트워크에 있는 경우 자체 호스팅 통합 런타임을 사용할 수 있습니다. 지정하지 않으면 기본 Azure 통합 런타임이 사용됩니다. 아니요

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

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

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalKey",
            "servicePrincipalCredential": {
                "type": "SecureString",
                "value": "<service principal key>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>" 
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>", 
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalCredential": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<AKV reference>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<certificate name in AKV>" 
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>" 
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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

참고 항목

현재 시스템 할당 관리 ID 인증은 데이터 흐름에서 지원되지 않습니다.

Data Factory 또는 Synapse 파이프라인은 이 특정 서비스 인스턴스를 나타내는 Azure 리소스에 대한 시스템 할당 관리 ID와 연결할 수 있습니다. 사용자 고유의 서비스 주체를 사용하는 것과 비슷하게 Azure Cosmos DB 인증에 이 관리 ID를 직접 사용할 수 있습니다. 이를 통해 이 지정된 리소스는 Azure Cosmos DB 인스턴스에서 데이터에 액세스하고 데이터를 복사할 수 있습니다.

Azure 리소스 인증에 시스템 할당 관리 ID를 사용하려면 다음 단계를 따릅니다.

  1. 서비스와 함께 생성된 관리 ID 개체 ID 값을 복사하여 시스템 할당 관리 ID 정보를 검색합니다.

  2. 적절한 사용 권한을 시스템 할당 관리 ID에 부여합니다. 파일 및 디렉터리에 대한 액세스 제어 목록에서 Azure Cosmos DB 권한이 작동하는 방식에 대한 예시를 참조하세요. 보다 구체적으로는 역할 정의를 만들고 시스템 할당 관리 ID에 역할을 할당합니다.

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

속성 설명 필수
type type 속성은 CosmosDb로 설정해야 합니다. 예
accountEndpoint Azure Cosmos DB 인스턴스에 대한 계정 엔드포인트 URL을 지정합니다. 예
database 데이터베이스의 이름을 지정합니다. 예
connectVia 데이터 저장소에 연결하는 데 사용할 통합 런타임입니다. Azure 통합 런타임 또는 데이터 저장소가 프라이빗 네트워크에 있는 경우 자체 호스팅 통합 런타임을 사용할 수 있습니다. 지정하지 않으면 기본 Azure 통합 런타임이 사용됩니다. 아니요

예제:

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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

참고 항목

현재 사용자 할당 관리 ID 인증은 데이터 흐름에서 지원되지 않습니다.

데이터 팩터리 또는 Synapse 파이프라인은 이 특정 서비스 인스턴스를 나타내는 사용자 할당 관리 ID와 연결될 수 있습니다. 사용자 고유의 서비스 주체를 사용하는 것과 비슷하게 Azure Cosmos DB 인증에 이 관리 ID를 직접 사용할 수 있습니다. 이를 통해 이 지정된 리소스는 Azure Cosmos DB 인스턴스에서 데이터에 액세스하고 데이터를 복사할 수 있습니다.

Azure 리소스 인증에 사용자 할당 관리 ID를 사용하려면 다음 단계를 따릅니다.

  1. 하나 이상의 사용자 할당 관리 ID를 만들고 사용자 할당 관리 ID에 적절한 권한을 부여합니다. 파일 및 디렉터리에 대한 액세스 제어 목록에서 Azure Cosmos DB 권한이 작동하는 방식에 대한 예시를 참조하세요. 보다 구체적으로, 역할 정의를 만들고 사용자가 할당한 관리 ID에 역할을 할당합니다.

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

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

속성 설명 필수
type type 속성은 CosmosDb로 설정해야 합니다. 예
accountEndpoint Azure Cosmos DB 인스턴스에 대한 계정 엔드포인트 URL을 지정합니다. 예
database 데이터베이스의 이름을 지정합니다. 예
credentials 사용자가 할당한 관리 ID를 자격 증명 개체로 지정합니다. 예
connectVia 데이터 저장소에 연결하는 데 사용할 통합 런타임입니다. Azure 통합 런타임 또는 데이터 저장소가 프라이빗 네트워크에 있는 경우 자체 호스팅 통합 런타임을 사용할 수 있습니다. 지정하지 않으면 기본 Azure 통합 런타임이 사용됩니다. 아니요

예제:

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

데이터 세트 속성

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

Azure Cosmos DB for NoSQL 데이터 세트에는 다음 속성이 지원됩니다.

속성 설명 필수
type 데이터 세트의 type 속성을 CosmosDbSqlApiCollection으로 설정해야 합니다. 예
collectionName Azure Cosmos DB 문서 컬렉션의 이름입니다. 예

“DocumentDbCollection” 형식 데이터 세트를 사용하는 경우 버전과의 호환성을 위해 복사 및 조회 작업에 그대로 계속 지원되지만 Data Flow에는 지원되지 않습니다. 앞으로는 새 모델을 사용하는 것이 좋습니다.

예제

{
    "name": "CosmosDbSQLAPIDataset",
    "properties": {
        "type": "CosmosDbSqlApiCollection",
        "linkedServiceName":{
            "referenceName": "<Azure Cosmos DB linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [],
        "typeProperties": {
            "collectionName": "<collection name>"
        }
    }
}

복사 활동 속성

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

원본으로서의 Azure Cosmos DB for NoSQL

Azure Cosmos DB for NoSQL에서 데이터를 복사하려면 복사 작업의 원본 형식을 DocumentDbCollectionSource로 설정합니다.

복사 작업 source 섹션에서 지원되는 속성은 다음과 같습니다.

속성 설명 필수
type 복사 작업 원본의 type 속성을 CosmosDbSqlApiSource로 설정해야 합니다. 예
query 데이터를 읽는 Azure Cosmos DB 쿼리를 지정합니다.

예시:
SELECT c.BusinessEntityID, c.Name.First AS FirstName, c.Name.Middle AS MiddleName, c.Name.Last AS LastName, c.Suffix, c.EmailPromotion FROM c WHERE c.ModifiedDate > \"2009-01-01T00:00:00\"		 아님

지정하지 않는 경우 실행되는 SQL 문: select <columns defined in structure> from mycollection
preferredRegions Azure Cosmos DB에서 데이터를 검색할 때 연결할 기본 지역 목록입니다. 아니요
pageSize 쿼리 결과의 페이지당 문서 수입니다. 기본값은 서비스 쪽 동적 페이지 크기를 1000까지 사용함을 의미하는 “-1”입니다. 아니요
detectDatetime 문서의 문자열 값에서 날짜/시간을 검색할지를 지정합니다. 허용되는 값은 true(기본값), false입니다. 아니요

“DocumentDbCollectionSource” 형식 원본을 사용하는 경우 이전 버전과의 호환성을 위해 그대로 계속 지원됩니다. 앞으로 Azure Cosmos DB에서 데이터를 복사하는 다양한 기능을 제공하는 새 모델을 사용하는 것이 좋습니다.

예제

"activities":[
    {
        "name": "CopyFromCosmosDBSQLAPI",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Cosmos DB for NoSQL input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "CosmosDbSqlApiSource",
                "query": "SELECT c.BusinessEntityID, c.Name.First AS FirstName, c.Name.Middle AS MiddleName, c.Name.Last AS LastName, c.Suffix, c.EmailPromotion FROM c WHERE c.ModifiedDate > \"2009-01-01T00:00:00\"",
                "preferredRegions": [
                    "East US"
                ]
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Azure Cosmos DB에서 데이터를 복사할 때에는 JSON 문서를 있는 그대로 내보내려는 경우가 아닌 한, 복사 작업에서 매핑을 지정하는 것이 가장 좋습니다. 이 서비스는 작업에 대해 지정된 매핑을 사용합니다. 행에 열에 대한 값이 포함되어 있지 않으면 열 값에 대해 null 값이 제공됩니다. 매핑을 지정하지 않으면 서비스는 데이터의 첫 번째 행을 사용하여 스키마를 유추합니다. 첫 번째 행에 전체 스키마가 포함되어 있지 않으면 일부 열이 복사 작업의 결과에서 누락됩니다.

Azure Cosmos DB for NoSQL를 싱크로 사용

Azure Cosmos DB for NoSQL에 데이터를 복사하려면 복사 작업의 싱크 형식을 DocumentDbCollectionSink로 설정합니다.

복사 작업 sink 섹션에서 지원되는 속성은 다음과 같습니다.

속성 설명 필수
type 복사 작업 싱크의 type 속성은 CosmosDbSqlApiSink로 설정해야 합니다. 예
writeBehavior Azure Cosmos DB에 데이터를 쓰는 방법을 설명합니다. 허용되는 값은 insert 및 upsert입니다.

upsert의 동작은 동일한 ID의 문서가 이미 존재하는 경우 문서를 바꾸는 것이며, 존재하지 않는 경우 문서를 삽입하는 것입니다.

참고: ID가 원래 문서 또는 열 매핑에 지정되지 않은 경우 이 서비스는 문서에 대한 ID를 자동으로 생성합니다. 즉, upsert가 예상대로 작동하려면 문서에 ID가 있는지 확인해야 합니다.		 아니요
(기본값: insert)
writeBatchSize 이 서비스는 Azure Cosmos DB 대량 실행기 라이브러리를 사용하여 Azure Cosmos DB에 데이터를 씁니다. writeBatchSize 속성은 서비스가 라이브러리에 제공하는 문서의 크기를 제어합니다. 성능을 개선하기 위해 writeBatchSize에 대한 값을 늘리고 문서 크기가 커지는 경우 값을 줄이도록 시도할 수 있습니다. 아래 팁을 참조하세요. 아니요
(기본값: 10,000)
disableMetricsCollection 이 서비스는 복사 성능 최적화 및 권장 사항에 대한 Azure Cosmos DB RU와 같은 메트릭을 수집합니다. 이 동작에 관심이 있는 경우 true를 지정하여 해제합니다. 아니요(기본값: false)
 maxConcurrentConnections 작업 실행 중 데이터 저장소에 설정된 동시 연결의 상한입니다. 동시 연결을 제한하려는 경우에만 값을 지정합니다.   아님

팁

JSON 문서를 그대로 가져오려면 JSON 문서 가져오기 또는 내보내기 섹션을 참조하세요. 표 형식 데이터를 복사하려면 관계형 데이터베이스에서 Azure Cosmos DB로 마이그레이션을 참조하세요.

팁

Azure Cosmos DB는 단일 요청의 크기를 2MB로 제한합니다. 수식은 요청 크기 = 단일 문서 크기 * 쓰기 일괄 처리 크기입니다. "요청 크기가 너무 큽니다."라는 오류가 발생하는 경우 복사 싱크 구성에서 writeBatchSize 값을 줄입니다.

“DocumentDbCollectionSink” 형식 원본을 사용하는 경우 이전 버전과의 호환성을 위해 그대로 계속 지원됩니다. 앞으로 Azure Cosmos DB에서 데이터를 복사하는 다양한 기능을 제공하는 새 모델을 사용하는 것이 좋습니다.

예제

"activities":[
    {
        "name": "CopyToCosmosDBSQLAPI",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Document DB output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "CosmosDbSqlApiSink",
                "writeBehavior": "upsert"
            }
        }
    }
]

스키마 매핑

Azure Cosmos DB에서 표 형식 싱크로 또는 싱크에서 API로 데이터를 복사하려면 스키마 매핑을 참조하세요.

매핑 데이터 흐름 속성

매핑 데이터 흐름에서 데이터를 변환하는 경우 Azure Cosmos DB에서 컬렉션에 대한 읽기 및 쓰기를 수행할 수 있습니다. 자세한 내용은 매핑 데이터 흐름에서 원본 변환 및 싱크 변환을 참조하세요.

참고 항목

Azure Cosmos DB 서버리스는 매핑 데이터 흐름에서 지원되지 않습니다.

원본 변환

Azure Cosmos DB에만 해당하는 설정은 원본 변환의 원본 옵션 탭에서 사용할 수 있습니다.

시스템 열 포함: true인 경우 id, _ts 및 기타 시스템 열이 Azure Cosmos DB의 데이터 흐름 메타데이터에 포함됩니다. 컬렉션을 업데이트할 때에는 기존 행 ID를 가져올 수 있도록 이 옵션을 포함하는 것이 중요합니다.

페이지 크기: 쿼리 결과의 페이지당 문서 수입니다. 기본값은 서비스 동적 페이지를 1000까지 사용하는 “-1”입니다.

처리량: 읽기 작업을 수행하는 동안 이 데이터 흐름이 실행될 때마다 Azure Cosmos DB 컬렉션에 적용할 RU 수에 대해 선택적 값을 설정합니다. 최솟값은 400입니다.

기본 설정 지역: 이 프로세스에 대한 기본 읽기 지역을 선택합니다.

변경 피드: true인 경우 마지막 실행부터 자동으로 발생한 순서대로 컨테이너 변경 내용을 지속적으로 기록하는 Azure Cosmos DB 변경 피드에서 데이터를 가져옵니다. true로 설정할 때 드리프트된 열 형식 유추과 스키마 드리프트 허용을 동시에 true로 설정하지 마세요. 자세한 내용은 Azure Cosmos DB 변경 피드)를 참조하세요.

처음부터 시작: true인 경우 첫 번째 실행에서 전체 스냅샷 데이터의 초기 로드를 가져온 후 다음 실행에서 변경된 데이터를 캡처합니다. false인 경우 첫 번째 실행에서 초기 로드를 건너뛰고 다음 실행에서 변경된 데이터를 캡처합니다. 설정은 Azure Cosmos DB 참조에서 동일한 설정 이름과 정렬되어 있습니다. 자세한 내용은 Azure Cosmos DB 변경 피드를 참조하세요.

싱크 변환

Azure Cosmos DB에 특정한 설정은 싱크 변환의 설정 탭에서 사용할 수 있습니다.

업데이트 메서드: 데이터베이스 대상에서 허용되는 작업을 결정합니다. 기본값은 삽입만 허용하는 것입니다. 행을 업데이트, upsert 또는 삭제하려면 해당 작업을 위해 행에 태그를 지정하는 데 행 변경 변환이 필요합니다. 업데이트, upsert 및 삭제의 경우 변경할 행을 결정하기 위해 키 열을 설정해야 합니다.

컬렉션 작업: 쓰기 전에 대상 컬렉션을 다시 만들지를 결정합니다.

  • 없음: 테이블에 대해 아무 작업도 수행되지 않습니다.
  • 다시 만들기: 컬렉션이 삭제되고 다시 만들어집니다.

일괄 처리 크기: 각 일괄 처리에서 Azure Cosmos DB 컬렉션에 얼마나 많은 개체가 기록되는지 나타내는 정수입니다. 일반적으로 기본 일괄 처리 크기로 시작하는 것으로 충분합니다. 이 값을 추가로 조정하려면 다음을 참고하세요.

  • Azure Cosmos DB는 단일 요청의 크기를 2MB로 제한합니다. 수식은 “요청 크기 = 단일 문서 크기 * 일괄 처리 크기”입니다. “요청 크기가 너무 큼”이라는 오류가 발생하는 경우 일괄 처리 크기 값을 줄입니다.
  • 일괄 처리 크기가 클수록 서비스의 처리량은 높아지지만 워크로드를 지원하기에 충분한 RU를 할당해야 합니다.

파티션 키: 컬렉션에 대한 파티션 키를 나타내는 문자열을 입력합니다. 예: /movies/title

처리량: 이 데이터 흐름의 각 실행에 대해 Azure Cosmos DB 컬렉션에 적용하려는 RU 수에 대한 선택적 값을 설정합니다. 최솟값은 400입니다.

쓰기 처리량 예산: 컬렉션에 할당된 총 처리량 중 이 데이터 흐름 쓰기 작업에 할당하려는 RU를 나타내는 정수입니다.

참고 항목

RU 사용을 제한하려면 Cosmos DB 처리량(자동 크기 조정)을 수동으로 설정하세요.

조회 작업 속성

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

JSON 문서 가져오기 및 내보내기

이 Azure Cosmos DB for NoSQL 커넥터를 사용하여 쉽게 다음을 수행할 수 있습니다.

  • 두 Azure Cosmos DB 컬렉션 간에 문서를 있는 그대로 복사
  • Azure Blob Storage, Azure Data Lake Store 및 서비스에서 지원하는 기타 파일 기반 저장소 등 다양한 원본에서 Azure Cosmos DB로 JSON 문서 가져오기
  • Azure Cosmos DB 컬렉션에서 다양한 파일 기반 저장소로 JSON 문서 내보내기

스키마 중립적 복사를 수행하려면 다음을 수행합니다.

  • 데이터 복사 도구를 사용하는 경우 JSON 파일 또는 Azure Cosmos DB 컬렉션으로 있는 그대로 내보내기 옵션을 선택합니다.
  • 작업 작성을 사용하는 경우 원본 또는 싱크에 해당하는 파일 저장소를 가진 JSON 형식을 선택합니다.

관계형 데이터베이스에서 Azure Cosmos DB로 마이그레이션

관계형 데이터베이스(예: SQL Server)에서 Azure Cosmos DB로 마이그레이션하는 경우 복사 작업은 Azure Cosmos DB에서 JSON 문서를 평면화하기 위해 원본에서 표 형식 데이터를 쉽게 매핑할 수 있습니다. 경우에 따라 데이터 모델을 다시 디자인하여 Azure Cosmos DB의 데이터 모델링에 따른 NoSQL 사용 사례에 맞게 최적화하는 것이 좋습니다. 예를 들어 하나의 JSON 문서 내에 모든 관련 하위 항목을 포함함으로써 데이터를 비정규화할 수 있습니다. 이 경우 복사 작업을 사용하여 이를 달성하는 방법을 안내하는 이 문서를 참조하세요.

Azure Cosmos DB 변경 피드

Azure Data Factory는 매핑 데이터 흐름 원본 변환에서 사용하도록 설정하여 Azure Cosmos DB 변경 피드에서 데이터를 가져올 수 있습니다. 이 커넥터 옵션을 사용하면 변환된 데이터를 선택한 대상 데이터 세트에 로드하기 전에 변경 피드를 읽고 변환을 적용할 수 있습니다. 변경 피드를 읽은 다음 사용자 지정 변환을 작성하는 데 Azure 기능을 사용할 필요가 없습니다. 이 옵션을 사용하여 한 컨테이너에서 다른 컨테이너로 데이터를 이동하고, 목적에 맞게 변경 피드 기반 자료 보기를 준비하거나, 변경 피드를 기반으로 컨테이너 백업 또는 복구를 자동화하고, Azure Data Factory의 시각적 끌어서 놓기 기능을 사용하여 더 많은 사용 사례를 사용하도록 설정할 수 있습니다.

마지막 실행에서 변경된 데이터를 자동으로 가져올 수 있도록 ADF에서 검사점을 기록할 수 있으려면 파이프라인과 작업 이름을 변경하지 않은 상태로 유지해야 합니다. 파이프라인 이름이나 작업 이름을 변경하면 검사점이 다시 설정되어 다음 실행에서 처음부터 시작하거나 지금부터 변경 내용을 가져올 수 있습니다.

파이프라인을 디버그할 때 이 기능은 동일하게 작동합니다. 디버그 실행 중에 브라우저를 새로 고치면 검사점이 다시 설정됩니다. 디버그 실행의 파이프라인 결과에 만족하면 파이프라인을 게시하고 트리거할 수 있습니다. 게시된 파이프라인을 처음 트리거하는 순간 처음부터 자동으로 다시 시작하거나 지금부터 변경 내용을 가져옵니다.

모니터링 섹션에서는 항상 파이프라인을 다시 실행할 수 있습니다. 이렇게 하면 변경된 데이터가 선택한 파이프라인 실행의 이전 검사점에서 항상 캡처됩니다.

또한 Azure Cosmos DB 분석 저장소는 이제 Azure Cosmos DB API for NoSQL 및 Azure Cosmos DB API for Mongo DB(공개 미리 보기)에 대한 CDC(변경 데이터 캡처)를 지원합니다. Azure Cosmos DB 분석 저장소를 사용하면 분석 저장소에서 변경(삽입, 업데이트 및 삭제) 데이터의 연속적이고 증분적인 피드를 효율적으로 사용할 수 있습니다.

관련 콘텐츠

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