data migration desktop tool
2.1.6
도구의 보관된 버전에 액세스하려면 보관 분기 로 이동하세요.
Azure Cosmos DB 데스크톱 데이터 마이그레이션 도구는 Azure Cosmos DB에 대한 가져오기 및 내보내기 기능을 제공하는 명령줄 애플리케이션이 포함된 오픈 소스 프로젝트입니다.
도구를 사용하려면 릴리스에서 플랫폼(win-x64, mac-x64 또는 linux-x64)에 대한 최신 zip 파일을 다운로드하고 모든 파일을 원하는 설치 위치에 추출하십시오. 데이터 전송 작업을 시작하려면 먼저 migrationsettings.json 파일을 데이터 원본 및 싱크에 대한 적절한 설정으로 채운 다음(아래 자세한 지침을 참조하거나 예제 검토) 명령줄(Windows의 경우 dmt.exe 또는 dmt 에서 애플리케이션을 실행하세요. 다른 플랫폼에서는.
이 저장소에는 여러 확장 기능이 제공됩니다. 제공된 링크를 사용하여 각각의 사용법 및 구성에 대한 문서를 찾으십시오.
Azure 코스모스 DB
Azure 테이블 API
JSON
몽고DB
SQL 서버
쪽매 세공
CSV
파일 저장
Azure Blob 저장소
AWS S3
Azure 인지 검색
Azure Cosmos DB 데스크톱 데이터 마이그레이션 도구는 MEF(관리형 확장성 프레임워크)를 활용하는 경량 실행 파일입니다. MEF를 사용하면 핵심 프로젝트와 해당 확장의 분리된 구현이 가능합니다. 핵심 애플리케이션은 런타임 시 애플리케이션의 Extensions 폴더에서 필요한 확장을 자동으로 로드하여 구성하는 명령줄 실행 파일입니다. 확장은 소스로서의 시스템 구현과 데이터 전송을 위한 싱크(선택 사항)를 포함하는 클래스 라이브러리입니다. 핵심 애플리케이션 프로젝트에는 확장 구현에 대한 직접적인 참조가 포함되어 있지 않습니다. 대신 이러한 프로젝트는 공통 인터페이스를 공유합니다.
Cosmos DB 데이터 마이그레이션 도구 핵심 프로젝트는 C# 명령줄 실행 파일입니다. 핵심 애플리케이션은 필수 소스 및 싱크 확장에 대한 구성 컨테이너 역할을 합니다. 따라서 애플리케이션 사용자는 애플리케이션을 실행하기 전에 원하는 Extension 클래스 라이브러리 어셈블리만 Extensions 폴더에 넣어야 합니다. 또한 핵심 프로젝트에는 애플리케이션의 동작을 실행하기 위한 단위 테스트 프로젝트가 있는 반면, 확장 프로젝트에는 외부 시스템에 의존하는 구체적인 통합 테스트가 포함되어 있습니다.
이 프로젝트는 Microsoft 오픈 소스 행동 강령을 채택했습니다. 자세한 내용은 행동 강령 FAQ를 참조하거나 추가 질문이나 의견이 있는 경우 [email protected]으로 문의하세요.
git clone https://github.com/AzureCosmosDB/data-migration-desktop-tool.git Visual Studio 2022를 사용하여 CosmosDbDataMigrationTool.sln 엽니다.
키보드 단축키 Ctrl + Shift + B (Mac에서는 Cmd + Shift + B )를 사용하여 프로젝트를 빌드합니다. 그러면 현재의 모든 확장 프로젝트와 명령줄 Core 애플리케이션이 빌드됩니다. 확장 프로젝트 빌드 어셈블리는 핵심 애플리케이션 빌드의 Extensions 폴더에 기록됩니다. 이렇게 하면 응용 프로그램이 실행될 때 모든 확장 옵션을 사용할 수 있습니다.
이 자습서에서는 Azure Cosmos DB 데스크톱 데이터 마이그레이션 도구를 사용하여 JSON 데이터를 Azure Cosmos DB로 이동하는 방법을 간략하게 설명합니다. 이 자습서에서는 Azure Cosmos DB 에뮬레이터를 사용합니다.
Azure Cosmos DB 에뮬레이터 애플리케이션을 시작하고 브라우저에서 https://localhost:8081/_explorer/index.html을 엽니다.
왼쪽 메뉴에서 Explorer 옵션을 선택합니다. 그런 다음 일반 작업 제목 아래에 있는 새 데이터베이스 링크를 선택합니다.
새 데이터베이스 블레이드에서 데이터베이스 ID 필드에 datamigration 입력한 다음 확인을 선택합니다.
데이터 마이그레이션 데이터베이스가 데이터베이스 목록에 표시되지 않으면 새로 고침 아이콘을 선택합니다.
데이터 마이그레이션 데이터베이스 옆에 있는 줄임표 메뉴를 확장하고 New Container 를 선택합니다.
새 컨테이너 블레이드에서 컨테이너 ID 필드에 btcdata 입력하고 파티션 키 필드에 /id 입력합니다. 확인 버튼을 선택합니다.
참고 : Cosmos DB 데이터 마이그레이션 도구를 사용하는 경우 컨테이너가 이전에 존재할 필요는 없으며 싱크 구성에 지정된 파티션 키를 사용하여 자동으로 생성됩니다.
각 확장에는 데이터 마이그레이션 구성을 개략적으로 설명하는 README 문서가 포함되어 있습니다. 이 경우 JSON(소스) 및 Cosmos DB(싱크)에 대한 구성을 찾습니다.
Visual Studio 솔루션 탐색기에서 Microsoft.Data.Transfer.Core 프로젝트를 확장하고 migrationsettings.json 을 엽니다. 이 파일은 설정 파일 구조의 개요 예를 제공합니다. 위에 링크된 설명서를 사용하여 SourceSettings 및 SinkSettings 섹션을 구성합니다. FilePath 설정이 샘플 데이터가 추출되는 위치인지 확인하십시오. ConnectionString 설정은 Cosmos DB 에뮬레이터 빠른 시작 화면에서 Primary Connection String 으로 찾을 수 있습니다. 파일을 저장합니다.
참고 : 구성 파일 및 명령줄 매개변수에서 싱크 대신 대상 및 대상이라는 대체 용어를 사용할 수 있습니다. 예를 들어
"Target"및"TargetSettings"아래 예에서도 유효합니다.
{
"Source" : " JSON " ,
"Sink" : " Cosmos-nosql " ,
"SourceSettings" : {
"FilePath" : " C: \ btcdata \ simple_json.json "
},
"SinkSettings" : {
"ConnectionString" : " AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDj... " ,
"Database" : " datamigration " ,
"Container" : " btcdata " ,
"PartitionKeyPath" : " /id " ,
"RecreateContainer" : false ,
"IncludeMetadataFields" : false
}
}
Cosmos.DataTransfer.Core 프로젝트가 시작 프로젝트로 설정되어 있는지 확인한 다음 F5 키를 눌러 애플리케이션을 실행합니다.
그런 다음 애플리케이션은 데이터 마이그레이션을 수행합니다. 잠시 후 프로세스에 데이터 전송 완료가 표시됩니다. 또는 데이터 전송이 실패했습니다 .
참고 :
Source및Sink속성은 확장 코드에 설정된 DisplayName 과 일치해야 합니다.
최신 릴리스를 다운로드하거나 프로젝트가 빌드되었는지 확인하세요.
Extensions 폴더에는 마이그레이션에 사용할 수 있는 플러그인이 포함되어 있습니다. 각 확장자는 데이터 소스 이름의 폴더에 있습니다. 예를 들어 Cosmos DB 확장은 Cosmos 폴더에 있습니다. 애플리케이션을 실행하기 전에 Extensions 폴더를 열고 마이그레이션에 필요하지 않은 확장에 대한 폴더를 제거할 수 있습니다.
빌드 폴더의 루트에서 migrationsettings.json 을 찾고 확장 설명서에 설명된 대로 설정을 업데이트합니다. 예제 파일(위 튜토리얼과 유사):
{
"Source" : " JSON " ,
"Sink" : " Cosmos-nosql " ,
"SourceSettings" : {
"FilePath" : " C: \ btcdata \ simple_json.json "
},
"SinkSettings" : {
"ConnectionString" : " AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDj... " ,
"Database" : " datamigration " ,
"Container" : " btcdata " ,
"PartitionKeyPath" : " /id " ,
"RecreateContainer" : false ,
"IncludeMetadataFields" : false
}
}참고 : migrationsettings.json은 단일 실행 명령으로 여러 데이터 전송 작업을 실행하도록 구성할 수도 있습니다. 이렇게 하려면 단일 작업에 대해 위에 표시된 것과 동일한 형식을 사용하여
SourceSettings및SinkSettings속성을 포함하는 개체 배열로 구성된Operations속성을 포함합니다. 자세한 내용과 예시는 이 블로그 게시물에서 확인할 수 있습니다.
다음 명령을 사용하여 프로그램을 실행합니다.
Windows 사용
dmt.exe참고 : 다른 설정 파일을 지정하려면 파일 경로와 함께
--settings옵션을 사용하세요(기본 migrationsettings.json 파일 재정의). 이를 통해 프로그래밍 방식 루프에서 다양한 마이그레이션 작업 실행을 자동화할 수 있습니다.
macOS 사용
./dmt참고 : macOS에서 도구를 실행하기 전에 확인되지 않은 개발자의 Mac 앱을 여는 방법에 대한 Apple의 지침을 따라야 합니다.
만들려는 확장 유형을 결정합니다. 3가지 유형의 확장이 있으며 각 확장은 데이터 읽기, 데이터 쓰기 또는 두 가지 모두를 위해 구현될 수 있습니다.
Extensions 폴더에 확장명 이름으로 새 폴더를 추가합니다.
확장 프로젝트와 관련 테스트 프로젝트를 만듭니다.
Cosmos.DataTransfer.<Name>Extension .바이너리 파일 저장소 확장은 다른 확장과 조합해서만 사용되므로 아래에 필요한 추가 디버깅 구성 없이 .NET 6 클래스 라이브러리 에 배치해야 합니다.
CosmosDbDataMigrationTool 솔루션에 새 프로젝트를 추가합니다.
로컬 디버깅을 용이하게 하려면 종속성과 함께 확장 빌드 출력을 CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions 폴더에 복사해야 합니다. 자동으로 복사되도록 프로젝트를 설정하려면 다음 변경 사항을 추가하세요.
......CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions 인 LocalDebugFolder 폴더에 게시 프로필을 추가합니다.< Target Name = " PublishDebug " AfterTargets = " Build " Condition = " '$(Configuration)' == 'Debug' " >
< Exec Command = " dotnet publish --no-build -p:PublishProfile=LocalDebugFolder " />
</ Target > System.ComponentModel.Composition NuGet 패키지 및 Cosmos.DataTransfer.Interfaces 프로젝트에 대한 참조를 추가합니다.
확장은 IDataSourceExtension 구현하여 데이터를 읽거나 IDataSinkExtension 구현하여 데이터를 쓸 수 있습니다. 이러한 인터페이스를 구현하는 클래스에는 구현된 인터페이스 유형을 매개 변수로 사용하는 클래스 수준 System.ComponentModel.Composition.ExportAttribute 포함되어야 합니다. 이렇게 하면 기본 애플리케이션에서 플러그인을 선택할 수 있습니다.
IComposableDataSource 또는 IComposableDataSink 인터페이스를 구현합니다. 다른 파일 형식과 함께 사용하려면 포맷터가 포함된 프로젝트가 확장의 프로젝트를 참조하고 스토리지 및 포맷터 확장을 참조하는 새로운 CompositeSourceExtension 또는 CompositeSinkExtension 추가해야 합니다.IFormattedDataReader 또는 IFormattedDataWriter 인터페이스를 구현합니다. 사용 가능하려면 각 형식에 대해 사용 가능한 저장 위치를 정의하기 위해 하나 이상의 CompositeSourceExtension 또는 CompositeSinkExtension 선언해야 합니다. 이를 위해서는 스토리지 확장 프로젝트에 대한 참조를 추가하고 각 파일 형식/스토리지 조합에 대한 선언을 추가해야 합니다. 예: [ Export ( typeof ( IDataSinkExtension ) ) ]
public class JsonAzureBlobSink : CompositeSinkExtension < AzureBlobDataSink , JsonFormatWriter >
{
public override string DisplayName => " JSON-AzureBlob " ;
}ReadAsync 및 WriteAsync 메서드에 전달된 IConfiguration 인스턴스를 사용하여 기본 애플리케이션의 표준 .NET 구성 소스에서 검색할 수 있습니다. SourceSettings / SinkSettings 아래의 설정은 물론 SourceSettingsPath / SinkSettingsPath 에 지정된 JSON 파일에 포함된 모든 설정도 포함됩니다. 개체 속성을 목록 키-값 쌍으로 노출하는 일반 IDataItem 인터페이스를 사용하여 읽기 및/또는 쓰기를 위한 확장을 구현합니다. 구현되는 데이터 저장소 유형의 특정 구조에 따라 중첩된 개체 및 배열을 지원하거나 단순 최상위 속성만 지원하도록 선택할 수 있습니다.
바이너리 파일 저장소 확장은 일반 저장소에만 관련되므로 개별
IDataItem이 아닌 전체 파일을 나타내는Stream인스턴스에서만 작동합니다.
