หากต้องการเข้าถึงเวอร์ชันที่เก็บถาวรของเครื่องมือ ให้ไปที่ สาขา Archive
เครื่องมือการย้ายข้อมูลบนเดสก์ท็อป Azure Cosmos DB เป็นโครงการโอเพ่นซอร์สที่มีแอปพลิเคชันบรรทัดคำสั่งที่ให้ฟังก์ชันการนำเข้าและส่งออกสำหรับ Azure Cosmos DB
หากต้องการใช้เครื่องมือนี้ ให้ดาวน์โหลดไฟล์ zip ล่าสุดสำหรับแพลตฟอร์มของคุณ (win-x64, mac-x64 หรือ linux-x64) จาก Releases และแยกไฟล์ทั้งหมดไปยังตำแหน่งการติดตั้งที่คุณต้องการ หากต้องการเริ่มดำเนินการถ่ายโอนข้อมูล ขั้นแรกเติมไฟล์ migrationsettings.json
ด้วยการตั้งค่าที่เหมาะสมสำหรับแหล่งข้อมูลและซิงก์ของคุณ (ดูคำแนะนำโดยละเอียดด้านล่างหรือดูตัวอย่าง) จากนั้นเรียกใช้แอปพลิเคชันจากบรรทัดคำสั่ง: dmt.exe
บน Windows หรือ dmt
บนแพลตฟอร์มอื่น
มีส่วนขยายหลายรายการไว้ในที่เก็บนี้ ค้นหาเอกสารสำหรับการใช้งานและการกำหนดค่าของแต่ละรายการโดยใช้ลิงก์ที่ให้ไว้:
ฐานข้อมูล Azure Cosmos
Azure Table API
เจสัน
MongoDB
เซิร์ฟเวอร์ SQL
ปาร์เก้
ซีเอสวี
พื้นที่จัดเก็บไฟล์
ที่เก็บข้อมูล Azure Blob
AWS S3
การค้นหาองค์ความรู้ Azure
เครื่องมือการย้ายข้อมูลบนเดสก์ท็อป Azure Cosmos DB เป็นไฟล์ปฏิบัติการขนาดเล็กที่ใช้ประโยชน์จาก Managed Extensibility Framework (MEF) MEF ช่วยให้การดำเนินงานโครงการหลักและส่วนขยายแยกจากกัน แอปพลิเคชันหลักเป็นไฟล์ปฏิบัติการบรรทัดคำสั่งที่รับผิดชอบในการเขียนส่วนขยายที่จำเป็นในขณะรันไทม์โดยการโหลดส่วนขยายเหล่านั้นจากโฟลเดอร์ส่วนขยายของแอปพลิเคชันโดยอัตโนมัติ ส่วนขยายคือไลบรารีคลาสที่รวมการใช้งานระบบเป็นแหล่งที่มาและ (ทางเลือก) Sink สำหรับการถ่ายโอนข้อมูล โครงการแอปพลิเคชันหลักไม่มีการอ้างอิงโดยตรงไปยังการใช้งานส่วนขยายใดๆ แต่โปรเจ็กต์เหล่านี้ใช้อินเทอร์เฟซร่วมกันแทน
โปรเจ็กต์หลักของ Cosmos DB Data Migration Tool เป็นไฟล์ปฏิบัติการบรรทัดคำสั่ง C# แอปพลิเคชันหลักทำหน้าที่เป็นคอนเทนเนอร์การเรียบเรียงสำหรับส่วนขยาย Source และ Sink ที่จำเป็น ดังนั้นผู้ใช้แอปพลิเคชันจำเป็นต้องใส่เฉพาะแอสเซมบลีไลบรารีคลาส Extension ที่ต้องการลงในโฟลเดอร์ Extensions ก่อนที่จะรันแอปพลิเคชัน นอกจากนี้ โปรเจ็กต์หลักยังมีโปรเจ็กต์การทดสอบหน่วยเพื่อใช้พฤติกรรมของแอปพลิเคชัน ในขณะที่โปรเจ็กต์ส่วนขยายประกอบด้วยการทดสอบการรวมที่เป็นรูปธรรมซึ่งอาศัยระบบภายนอก
โครงการนี้ได้นำหลักจรรยาบรรณของ Microsoft Open Source มาใช้ สำหรับข้อมูลเพิ่มเติม โปรดดูคำถามที่พบบ่อยเกี่ยวกับจรรยาบรรณหรือติดต่อ [email protected] หากมีคำถามหรือความคิดเห็นเพิ่มเติม
git clone https://github.com/AzureCosmosDB/data-migration-desktop-tool.git
ใช้ Visual Studio 2022 เปิด CosmosDbDataMigrationTool.sln
สร้างโปรเจ็กต์โดยใช้แป้นพิมพ์ลัด Ctrl + Shift + B ( Cmd + Shift + B บน Mac) สิ่งนี้จะสร้างโปรเจ็กต์ส่วนขยายปัจจุบันทั้งหมดรวมถึงแอปพลิเคชัน Core แบบบรรทัดคำสั่ง แอสเซมบลีการสร้างโปรเจ็กต์ส่วนขยายจะถูกเขียนไปยังโฟลเดอร์ ส่วน ขยายของบิลด์แอปพลิเคชัน หลัก วิธีนี้จะทำให้ตัวเลือกส่วนขยายทั้งหมดพร้อมใช้งานเมื่อแอปพลิเคชันทำงาน
บทช่วยสอนนี้สรุปวิธีการใช้เครื่องมือการย้ายข้อมูลเดสก์ท็อป Azure Cosmos DB เพื่อย้ายข้อมูล JSON ไปยัง Azure Cosmos DB บทช่วยสอนนี้ใช้ Azure Cosmos DB Emulator
เปิดแอปพลิเคชันจำลอง Azure Cosmos DB และเปิด https://localhost:8081/_explorer/index.html ในเบราว์เซอร์
เลือกตัวเลือก Explorer จากเมนูด้านซ้าย จากนั้นเลือกลิงก์ ฐานข้อมูลใหม่ ใต้หัวข้อ งานทั่วไป
บนเบ ลดฐานข้อมูลใหม่ ให้ป้อน datamigration
ในฟิลด์ ID ฐานข้อมูล จากนั้นเลือก ตกลง
หากฐาน ข้อมูลการย้ายข้อมูล ไม่ปรากฏในรายการฐานข้อมูล ให้เลือกไอคอน รีเฟรช
ขยายเมนูจุดไข่ปลาถัดจากฐานข้อมูล การย้ายข้อมูล และเลือก คอนเทนเนอร์ใหม่
บนเบลด คอนเทนเนอร์ใหม่ ให้ป้อน btcdata
ในช่อง รหัสคอนเทนเนอร์ และ /id
ในช่อง คีย์พาร์ติชัน เลือกปุ่ม ตกลง
หมายเหตุ : เมื่อใช้เครื่องมือการย้ายข้อมูล Cosmos DB คอนเทนเนอร์ไม่จำเป็นต้องมีอยู่แล้ว แต่จะถูกสร้างขึ้นโดยอัตโนมัติโดยใช้คีย์พาร์ติชันที่ระบุในการกำหนดค่าซิงก์
แต่ละส่วนขยายประกอบด้วยเอกสาร README ที่แสดงโครงร่างการกำหนดค่าสำหรับการย้ายข้อมูล ในกรณีนี้ ให้ค้นหาการกำหนดค่าสำหรับ JSON (แหล่งที่มา) และ Cosmos DB (Sink)
ใน Visual Studio Solution Explorer ให้ขยายโปรเจ็กต์ Microsoft.Data.Transfer.Core และเปิด Migrationsettings.json ไฟล์นี้จะแสดงตัวอย่างโครงร่างของโครงสร้างไฟล์การตั้งค่า ใช้เอกสารประกอบที่ลิงก์ด้านบน กำหนดค่าส่วน SourceSettings และ SinkSettings ตรวจสอบให้แน่ใจว่าการตั้งค่า FilePath เป็นตำแหน่งที่ดึงข้อมูลตัวอย่าง การตั้งค่า ConnectionString สามารถพบได้บนหน้าจอ Cosmos DB Emulator Quickstart เป็น สตริงการเชื่อมต่อหลัก บันทึกไฟล์.
หมายเหตุ : คำอื่น Target และ Destination สามารถใช้แทน Sink ในไฟล์คอนฟิกูเรชันและพารามิเตอร์บรรทัดคำสั่งได้ ตัวอย่างเช่น
"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 ที่ตั้งไว้ในโค้ดสำหรับส่วนขยาย
ดาวน์โหลดรุ่นล่าสุด หรือตรวจสอบให้แน่ใจว่ามีการสร้างโปรเจ็กต์แล้ว
โฟลเดอร์ ส่วนขยาย ประกอบด้วยปลั๊กอินที่พร้อมใช้งานในการย้ายข้อมูล แต่ละส่วนขยายจะอยู่ในโฟลเดอร์ที่มีชื่อแหล่งข้อมูล ตัวอย่างเช่น ส่วนขยาย 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 ยังสามารถกำหนดค่าให้ดำเนินการโอนข้อมูลหลายรายการโดยใช้คำสั่งเรียกใช้คำสั่งเดียวได้ เมื่อต้องการทำเช่นนี้ ให้รวมคุณสมบัติ
Operations
ที่ประกอบด้วยอาร์เรย์ของออบเจ็กต์ที่มีคุณสมบัติSourceSettings
และSinkSettings
โดยใช้รูปแบบเดียวกันกับที่แสดงด้านบนสำหรับการดำเนินการเดี่ยว รายละเอียดและตัวอย่างเพิ่มเติมสามารถพบได้ในโพสต์บล็อกนี้
รันโปรแกรมโดยใช้คำสั่งต่อไปนี้:
การใช้วินโดวส์
dmt.exe
หมายเหตุ : ใช้ตัวเลือก
--settings
กับพาธของไฟล์เพื่อระบุไฟล์การตั้งค่าอื่น (แทนที่ไฟล์ Migrationsettings.json เริ่มต้น) สิ่งนี้อำนวยความสะดวกในการรันงานการย้ายข้อมูลต่างๆ โดยอัตโนมัติในลูปแบบเป็นโปรแกรม
การใช้ macOS
./dmt
หมายเหตุ : ก่อนที่คุณจะเรียกใช้เครื่องมือบน macOS คุณจะต้องปฏิบัติตามคำแนะนำของ Apple เกี่ยวกับวิธีเปิดแอพ Mac จากนักพัฒนาที่ไม่ปรากฏชื่อ
ตัดสินใจว่าคุณต้องการสร้างส่วนขยายประเภทใด ส่วนขยายมี 3 ประเภทที่แตกต่างกัน และแต่ละประเภทสามารถนำมาใช้เพื่ออ่านข้อมูล เขียนข้อมูล หรือทั้งสองอย่างได้
เพิ่มโฟลเดอร์ใหม่ในโฟลเดอร์ส่วนขยายด้วยชื่อส่วนขยายของคุณ
สร้างโปรเจ็กต์ส่วนขยายและโปรเจ็กต์ทดสอบที่แนบมาด้วย
Cosmos.DataTransfer.<Name>Extension
ส่วนขยาย Binary File Storage ใช้ร่วมกับส่วนขยายอื่นๆ เท่านั้น ดังนั้นควรวางไว้ใน ไลบรารีคลาส .NET 6 โดยไม่ต้องกำหนดค่าการดีบักเพิ่มเติมด้านล่าง
เพิ่มโปรเจ็กต์ใหม่ให้กับโซลูชัน CosmosDbDataMigrationTool
เพื่ออำนวยความสะดวกในการดีบักในเครื่อง เอาต์พุตของบิลด์ส่วนขยายพร้อมกับการขึ้นต่อกันใดๆ จะต้องคัดลอกลงในโฟลเดอร์ CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions
หากต้องการตั้งค่าโปรเจ็กต์ให้คัดลอกโดยอัตโนมัติให้เพิ่มการเปลี่ยนแปลงต่อไปนี้
LocalDebugFolder
โดยมีตำแหน่งเป้าหมายเป็น ......CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions
< 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 " ;
}
IConfiguration
ที่ส่งผ่านไปยังวิธี ReadAsync
และ WriteAsync
การตั้งค่าภายใต้ SourceSettings
/ SinkSettings
จะถูกรวมไว้ เช่นเดียวกับการตั้งค่าใดๆ ที่รวมอยู่ในไฟล์ JSON ที่ระบุโดย SourceSettingsPath
/ SinkSettingsPath
ใช้ส่วนขยายของคุณเพื่ออ่านและ/หรือเขียนโดยใช้อินเทอร์เฟซ IDataItem
ทั่วไปซึ่งจะแสดงคุณสมบัติของออบเจ็กต์เป็นคู่คีย์-ค่าของรายการ ขึ้นอยู่กับโครงสร้างเฉพาะของประเภทการจัดเก็บข้อมูลที่กำลังใช้งาน คุณสามารถเลือกที่จะสนับสนุนอ็อบเจ็กต์และอาร์เรย์ที่ซ้อนกันหรือเฉพาะคุณสมบัติระดับบนสุดแบบเรียบได้
ส่วนขยายพื้นที่จัดเก็บไฟล์ไบนารีเกี่ยวข้องกับพื้นที่จัดเก็บข้อมูลทั่วไปเท่านั้น ดังนั้นจึงใช้งานได้เฉพาะกับอินสแตนซ์
Stream
ที่แสดงไฟล์ทั้งหมด แทนที่จะเป็นIDataItem
แต่ละรายการ