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 Cosmos DB
AzureテーブルAPI
JSON
モンゴDB
SQLサーバー
寄木細工
CSV
ファイルストレージ
Azure Blob ストレージ
AWS S3
Azure コグニティブ検索
Azure Cosmos DB デスクトップ データ移行ツールは、マネージド拡張性フレームワーク (MEF) を利用する軽量の実行可能ファイルです。 MEF を使用すると、コア プロジェクトとその拡張機能を分離して実装できます。コア アプリケーションは、アプリケーションの Extensions フォルダーから自動的にロードされることにより、実行時に必要な拡張機能を作成するコマンド ライン実行可能ファイルです。拡張機能は、データ転送用のソースおよび (オプションで) シンクとしてのシステムの実装を含むクラス ライブラリです。コア アプリケーション プロジェクトには、拡張実装への直接参照は含まれません。代わりに、これらのプロジェクトは共通のインターフェイスを共有します。
Cosmos DB Data Migration Tool コア プロジェクトは、C# コマンド ライン実行可能ファイルです。コア アプリケーションは、必要なソース拡張機能とシンク拡張機能の構成コンテナーとして機能します。したがって、アプリケーション ユーザーは、アプリケーションを実行する前に、必要な Extension クラス ライブラリ アセンブリのみを Extensions フォルダーに配置する必要があります。さらに、コア プロジェクトにはアプリケーションの動作を実行するための単体テスト プロジェクトがあり、拡張プロジェクトには外部システムに依存する具体的な統合テストが含まれています。
このプロジェクトはマイクロソフトのオープンソース行動規範を採用しています。詳細については、行動規範に関する FAQ を参照するか、追加の質問やコメントがあれば [email protected] までお問い合わせください。
git clone https://github.com/AzureCosmosDB/data-migration-desktop-tool.gitVisual Studio 2022 を使用して、 CosmosDbDataMigrationTool.slnを開きます。
キーボード ショートカットCtrl + Shift + B (Mac の場合はCmd + Shift + B ) を使用してプロジェクトをビルドします。これにより、現在のすべての拡張プロジェクトとコマンドラインコアアプリケーションがビルドされます。拡張機能プロジェクトのビルド アセンブリは、コアアプリケーション ビルドのExtensionsフォルダーに書き込まれます。これにより、アプリケーションの実行時にすべての拡張オプションが利用可能になります。
このチュートリアルでは、Azure Cosmos DB デスクトップ データ移行ツールを使用して JSON データを Azure Cosmos DB に移動する方法について概要を説明します。このチュートリアルでは、Azure Cosmos DB エミュレーターを使用します。
Azure Cosmos DB エミュレーター アプリケーションを起動し、ブラウザーで https://localhost:8081/_explorer/index.html を開きます。
左側のメニューから「エクスプローラー」オプションを選択します。次に、 [共通タスク]見出しの下にある [新しいデータベース]リンクを選択します。
[新しいデータベース]ブレードで、 [データベース ID]フィールドにdatamigrationと入力し、 [OK]を選択します。
データ移行データベースがデータベースのリストに表示されない場合は、 [更新]アイコンを選択します。
データ移行データベースの横にある省略記号メニューを展開し、 [新しいコンテナ]を選択します。
[新しいコンテナー]ブレードで、 [コンテナー ID]フィールドにbtcdata入力し、 [パーティション キー]フィールドに/id入力します。 [OK]ボタンを選択します。
注: Cosmos DB Data Migration ツールを使用する場合、コンテナーは事前に存在している必要はなく、シンク構成で指定されたパーティション キーを使用して自動的に作成されます。
各拡張機能には、データ移行の構成の概要を説明した README ドキュメントが含まれています。この場合、JSON (ソース) と Cosmos DB (シンク) の構成を見つけます。
Visual Studio ソリューション エクスプローラーで、 Microsoft.Data.Transfer.Coreプロジェクトを展開し、 migrationsettings.jsonを開きます。このファイルは、設定ファイル構造の概要の例を提供します。上記のリンク先のドキュメントを使用して、 SourceSettings セクションとSinkSettingsセクションを構成します。 FilePath設定がサンプル データが抽出される場所であることを確認します。 ConnectionString 設定は、Cosmos DB エミュレーターのクイックスタート画面にプライマリ接続文字列として表示されます。ファイルを保存します。
注: 構成ファイルおよびコマンド ライン パラメータでは、シンクの代わりにターゲットと宛先という代替用語を使用できます。たとえば、以下の例では
"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フォルダーにあります。アプリケーションを実行する前に、拡張機能フォルダーを開いて、移行に必要のない拡張機能のフォルダーを削除できます。
ビルド フォルダーのルートで、 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 は、 1 つの実行コマンドで複数のデータ転送操作を実行するように構成することもできます。これを行うには、上記の単一操作の場合と同じ形式を使用して、
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インターフェイスを実装します。使用できるようにするには、それぞれが 1 つ以上の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インスタンスでのみ機能します。
