data migration desktop tool

Alat Migrasi Data Desktop Azure Cosmos DB

Untuk mengakses versi alat yang diarsipkan, navigasikan ke cabang Arsip .

---

• Alat Migrasi Data Desktop Azure Cosmos DB
  • Ringkasan
  • Dokumentasi ekstensi
  • Arsitektur
  • Struktur Proyek
  • Memulai
    • Kloning repositori kode sumber
    • Bangun solusinya
  • Tutorial: Migrasi JSON ke Cosmos DB
    • Prasyarat Perangkat Lunak Tutorial
    • Tugas 1: Menyediakan database sampel dan kontainer menggunakan Emulator Azure Cosmos DB sebagai tujuan (sink)
    • Tugas 2: Menyiapkan dokumen sumber JSON
    • Tugas 3: Menyiapkan konfigurasi migrasi data
  • Menggunakan baris perintah
  • Membuat Ekstensi

Ringkasan

Alat Migrasi Data Desktop Azure Cosmos DB adalah proyek sumber terbuka yang berisi aplikasi baris perintah yang menyediakan fungsionalitas impor dan ekspor untuk Azure Cosmos DB.

Instalasi Cepat

Untuk menggunakan alat ini, unduh file zip terbaru untuk platform Anda (win-x64, mac-x64, atau linux-x64) dari Rilis dan ekstrak semua file ke lokasi instalasi yang Anda inginkan. Untuk memulai operasi transfer data, pertama-tama isi file migrationsettings.json dengan pengaturan yang sesuai untuk sumber data dan sink Anda (lihat petunjuk detail di bawah atau tinjau contoh), lalu jalankan aplikasi dari baris perintah: dmt.exe di Windows atau dmt di platform lain.

Dokumentasi ekstensi

Beberapa ekstensi disediakan di repositori ini. Temukan dokumentasi penggunaan dan konfigurasi masing-masing menggunakan tautan yang disediakan:

1. Azure Cosmos DB

2. API Tabel Azure

3. JSON

4. MongoDB

5. SQLServer

6. Parket

7. CSV

8. Penyimpanan Berkas

9. Penyimpanan Blob Azure

10. AWS S3

11. Pencarian Kognitif Azure

Arsitektur

Alat Migrasi Data Desktop Azure Cosmos DB adalah executable ringan yang memanfaatkan Managed Extensibility Framework (MEF). MEF memungkinkan implementasi proyek inti dan perluasannya secara terpisah. Aplikasi inti adalah baris perintah yang dapat dieksekusi yang bertanggung jawab untuk menyusun ekstensi yang diperlukan saat runtime dengan memuatnya secara otomatis dari folder Ekstensi aplikasi. Ekstensi adalah perpustakaan kelas yang mencakup implementasi Sistem sebagai Sumber dan (opsional) Sink untuk transfer data. Proyek aplikasi inti tidak berisi referensi langsung ke implementasi ekstensi apa pun. Sebaliknya, proyek-proyek ini berbagi antarmuka yang sama.

Struktur Proyek

Proyek inti Alat Migrasi Data Cosmos DB adalah baris perintah C# yang dapat dieksekusi. Aplikasi inti berfungsi sebagai wadah komposisi untuk ekstensi Sumber dan Sink yang diperlukan. Oleh karena itu, pengguna aplikasi hanya perlu memasukkan rakitan perpustakaan kelas Extension yang diinginkan ke dalam folder Extensions sebelum menjalankan aplikasi. Selain itu, proyek inti memiliki proyek pengujian unit untuk melatih perilaku aplikasi, sedangkan proyek perluasan berisi pengujian integrasi konkrit yang bergantung pada sistem eksternal.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi lebih lanjut lihat FAQ Pedoman Perilaku atau hubungi [email protected] jika ada pertanyaan atau komentar tambahan.

Memulai

Kloning repositori kode sumber

1. Dari prompt perintah, jalankan perintah berikut di folder kerja kosong yang akan menampung kode sumber.

git clone https://github.com/AzureCosmosDB/data-migration-desktop-tool.git

Bangun solusinya

1. Menggunakan Visual Studio 2022, buka CosmosDbDataMigrationTool.sln .

2. Bangun proyek menggunakan pintasan keyboard Ctrl + Shift + B ( Cmd + Shift + B di Mac). Ini akan membangun semua proyek ekstensi saat ini serta aplikasi Inti baris perintah. Rakitan pembangunan proyek ekstensi ditulis ke folder Ekstensi dari pembangunan aplikasi Inti . Dengan cara ini semua opsi ekstensi tersedia saat aplikasi dijalankan.

Tutorial: Migrasi JSON ke Cosmos DB

Tutorial ini menguraikan cara menggunakan Alat Migrasi Data Desktop Azure Cosmos DB untuk memindahkan data JSON ke Azure Cosmos DB. Tutorial ini menggunakan Emulator Azure Cosmos DB.

Prasyarat Perangkat Lunak Tutorial

1. Visual Studio 2022
2. .NET 6.0 SDK
3. Emulator Azure Cosmos DB atau sumber daya Azure Cosmos DB.

Tugas 1: Menyediakan database sampel dan kontainer menggunakan Emulator Azure Cosmos DB sebagai tujuan (sink)

1. Luncurkan aplikasi emulator Azure Cosmos DB dan buka https://localhost:8081/_explorer/index.html di browser.

2. Pilih opsi Explorer dari menu sebelah kiri. Kemudian pilih tautan Database Baru yang ada di bawah judul Tugas Umum .

   

3. Pada bilah Database Baru , masukkan datamigration di bidang Id database , lalu pilih OK .

   

4. Jika database migrasi data tidak muncul dalam daftar database, pilih ikon Refresh .

   

5. Perluas menu elipsis di samping database migrasi data dan pilih Kontainer Baru .

   

6. Pada bilah Kontainer Baru , masukkan btcdata di bidang Id Kontainer , dan /id di bidang Kunci partisi . Pilih tombol OK .

   

   Catatan : Saat menggunakan alat Migrasi Data Cosmos DB, kontainer tidak harus ada sebelumnya, kontainer akan dibuat secara otomatis menggunakan kunci partisi yang ditentukan dalam konfigurasi sink.

Tugas 2: Menyiapkan dokumen sumber JSON

1. Temukan file docs/resources/sample-data.zip . Ekstrak file ke folder mana pun yang diinginkan. File-file ini berfungsi sebagai data JSON yang akan dimigrasikan ke Cosmos DB.

Tugas 3: Menyiapkan konfigurasi migrasi data

1. Setiap ekstensi berisi dokumen README yang menguraikan konfigurasi untuk migrasi data. Dalam hal ini, temukan konfigurasi untuk JSON (Sumber) dan Cosmos DB (Sink).

2. Di Visual Studio Solution Explorer, perluas proyek Microsoft.Data.Transfer.Core , dan buka migrasisettings.json . File ini memberikan contoh garis besar struktur file pengaturan. Dengan menggunakan dokumentasi yang ditautkan di atas, konfigurasikan bagian SourceSettings dan SinkSettings . Pastikan pengaturan FilePath adalah lokasi di mana data sampel diekstraksi. Pengaturan ConnectionString dapat ditemukan di layar Mulai Cepat Cosmos DB Emulator sebagai Primary Connection String . Simpan berkasnya.

   Catatan : Istilah alternatif Target dan Tujuan dapat digunakan sebagai pengganti Sink dalam file konfigurasi dan parameter baris perintah. Misalnya "Target" dan "TargetSettings" juga akan valid dalam contoh di bawah ini.

   {
       "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
       }
   }

   

3. Pastikan proyek Cosmos.DataTransfer.Core ditetapkan sebagai proyek startup lalu tekan F5 untuk menjalankan aplikasi.

4. Aplikasi kemudian melakukan migrasi data. Setelah beberapa saat proses akan menunjukkan transfer data selesai. atau Transfer data gagal .

Catatan : Properti Source dan Sink harus cocok dengan Nama Tampilan yang ditetapkan dalam kode untuk ekstensi.

Menggunakan baris perintah

1. Unduh rilis terbaru, atau pastikan proyek telah dibuat.

2. Folder Extensions berisi plug-in yang tersedia untuk digunakan dalam migrasi. Setiap ekstensi terletak di folder dengan nama sumber data. Misalnya, ekstensi Cosmos DB terletak di folder Cosmos . Sebelum menjalankan aplikasi, Anda dapat membuka folder Ekstensi dan menghapus folder apa pun untuk ekstensi yang tidak diperlukan untuk migrasi.

3. Di root folder build, temukan migrasisettings.json dan perbarui pengaturan seperti yang didokumentasikan dalam dokumentasi Ekstensi. Contoh file (mirip dengan tutorial di atas):

   {
       "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
       }
   }

Catatan : migrasisettings.json juga dapat dikonfigurasi untuk menjalankan beberapa operasi transfer data dengan satu perintah jalankan. Untuk melakukan hal ini, sertakan properti Operations yang terdiri dari array objek yang mencakup properti SourceSettings dan SinkSettings menggunakan format yang sama seperti yang ditunjukkan di atas untuk operasi tunggal. Detail dan contoh tambahan dapat ditemukan di postingan blog ini.

4. Jalankan program menggunakan perintah berikut:

   Menggunakan Windows

   dmt.exe

   Catatan : Gunakan opsi --settings dengan jalur file untuk menentukan file pengaturan yang berbeda (mengganti file migrasisettings.json default). Hal ini memfasilitasi otomatisasi jalannya tugas migrasi yang berbeda dalam satu putaran terprogram.

   Menggunakan macOS

   ./dmt

   Catatan : Sebelum menjalankan alat ini di macOS, Anda harus mengikuti instruksi Apple tentang cara Membuka aplikasi Mac dari pengembang yang tidak dikenal.

Membuat Ekstensi

1. Putuskan jenis ekstensi apa yang ingin Anda buat. Ada 3 jenis ekstensi berbeda dan masing-masing dapat diterapkan untuk membaca data, menulis data, atau keduanya.

   1. Ekstensi DataSource/DataSink: Sesuai untuk sumber data yang mencakup format dan penyimpanan data asli. Sebagian besar database termasuk dalam kategori ini dan umumnya ekstensi Anda akan ditulis menggunakan SDK khusus untuk jenis database tersebut. Misalnya, SQL Server menggunakan data terstruktur sebagai tabel dan diakses melalui driver yang menangani komunikasi mendasar dengan database.
   2. Ekstensi Penyimpanan File Biner: Hanya berkaitan dengan penyimpanan file biner dan tidak bergantung pada format file tertentu. Contohnya termasuk file di disk lokal atau penyedia penyimpanan cloud blob. Jenis ekstensi ini dapat digunakan oleh ekstensi Format File apa pun.
   3. Ekstensi Format File: Menangani penerjemahan data untuk format file biner tertentu tetapi tidak bergantung pada penyimpanan. Contohnya termasuk JSON atau Parket. Jenis ekstensi ini dapat digabungkan dengan ekstensi Penyimpanan File Biner apa pun untuk membuat beberapa ekstensi DataSource/DataSink.

2. Tambahkan folder baru di folder Extensions dengan nama ekstensi Anda.

3. Buat proyek ekstensi dan proyek pengujian yang menyertainya.

   • Konvensi penamaan untuk proyek ekstensi adalah Cosmos.DataTransfer.<Name>Extension .
   • Proyek ekstensi harus menggunakan kerangka .NET 6 dan jenis Aplikasi Konsol . File Program.cs harus disertakan untuk membangun proyek konsol. Proyek Aplikasi Konsol diperlukan agar build menyertakan paket referensi NuGet.

   Ekstensi Penyimpanan File Biner hanya digunakan dalam kombinasi dengan ekstensi lain sehingga harus ditempatkan di Perpustakaan Kelas .NET 6 tanpa memerlukan konfigurasi debugging tambahan di bawah.

4. Tambahkan proyek baru ke solusi CosmosDbDataMigrationTool .

5. Untuk memfasilitasi proses debug lokal, keluaran pembuatan ekstensi beserta dependensi apa pun perlu disalin ke folder CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions . Untuk menyiapkan proyek agar disalin secara otomatis, tambahkan perubahan berikut.

   • Tambahkan Profil Publikasikan ke Folder bernama LocalDebugFolder dengan Lokasi Target ......CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions
   • Untuk memublikasikan setiap kali proyek dibuat, edit file .csproj untuk menambahkan langkah pasca-pembangunan baru:

   < Target Name = " PublishDebug " AfterTargets = " Build " Condition = " '$(Configuration)' == 'Debug' " >
      < Exec Command = " dotnet publish --no-build -p:PublishProfile=LocalDebugFolder " />
   </ Target >

6. Tambahkan referensi ke paket NuGet System.ComponentModel.Composition dan proyek Cosmos.DataTransfer.Interfaces .

7. Ekstensi dapat mengimplementasikan IDataSourceExtension untuk membaca data atau IDataSinkExtension untuk menulis data. Kelas yang mengimplementasikan antarmuka ini harus menyertakan System.ComponentModel.Composition.ExportAttribute tingkat kelas dengan tipe antarmuka yang diimplementasikan sebagai parameter. Ini akan memungkinkan plugin diambil oleh aplikasi utama.

   • Ekstensi Penyimpanan File Biner mengimplementasikan antarmuka IComposableDataSource atau IComposableDataSink . Untuk digunakan dengan format file yang berbeda, proyek yang berisi pemformat harus mereferensikan proyek ekstensi dan menambahkan CompositeSourceExtension atau CompositeSinkExtension baru yang merujuk pada penyimpanan dan ekstensi pemformat.
   • Ekstensi Format File mengimplementasikan antarmuka IFormattedDataReader atau IFormattedDataWriter . Agar dapat digunakan, masing-masing juga harus mendeklarasikan satu atau lebih CompositeSourceExtension atau CompositeSinkExtension untuk menentukan lokasi penyimpanan yang tersedia untuk format tersebut. Ini memerlukan penambahan referensi ke proyek ekstensi Penyimpanan dan penambahan deklarasi untuk setiap kombinasi format/penyimpanan file. Contoh:

      [ Export ( typeof ( IDataSinkExtension ) ) ]
     public class JsonAzureBlobSink : CompositeSinkExtension < AzureBlobDataSink , JsonFormatWriter >
     {
         public override string DisplayName => " JSON-AzureBlob " ;
     }

   7. Pengaturan yang diperlukan oleh ekstensi dapat diambil dari sumber konfigurasi .NET standar apa pun di aplikasi utama dengan menggunakan instans IConfiguration yang diteruskan ke metode ReadAsync dan WriteAsync . Pengaturan di bawah SourceSettings / SinkSettings akan disertakan serta pengaturan apa pun yang disertakan dalam file JSON yang ditentukan oleh SourceSettingsPath / SinkSettingsPath .

8. Terapkan ekstensi Anda untuk membaca dan/atau menulis menggunakan antarmuka IDataItem generik yang memperlihatkan properti objek sebagai daftar pasangan nilai kunci. Bergantung pada struktur spesifik tipe penyimpanan data yang diterapkan, Anda dapat memilih untuk mendukung objek dan array bertumpuk atau hanya properti tingkat atas datar.

   Ekstensi Penyimpanan File Biner hanya berkaitan dengan penyimpanan umum sehingga hanya berfungsi dengan instance Stream yang mewakili seluruh file, bukan IDataItem individual.