الصفحة الرئيسية>المتعلقة بالبرمجة>شفرة المصدر الأخرى
تنزيل

أداة ترحيل بيانات سطح المكتب Azure Cosmos DB

للوصول إلى النسخة المؤرشفة من الأداة، انتقل إلى فرع الأرشيف .

  • أداة ترحيل بيانات سطح المكتب Azure Cosmos DB
    • ملخص
    • وثائق التمديد
    • بنيان
    • هيكل المشروع
    • ابدء
      • استنساخ مستودع التعليمات البرمجية المصدر
      • بناء الحل
    • البرنامج التعليمي: ترحيل JSON إلى Cosmos DB
      • متطلبات البرامج التعليمية
      • المهمة 1: توفير نموذج قاعدة بيانات وحاوية باستخدام Azure Cosmos DB Emulator كوجهة (مخزن)
      • المهمة 2: إعداد مستندات مصدر JSON
      • المهمة 3: إعداد تكوين ترحيل البيانات
    • باستخدام سطر الأوامر
    • إنشاء ملحقات

ملخص

أداة ترحيل بيانات سطح المكتب Azure Cosmos DB عبارة عن مشروع مفتوح المصدر يحتوي على تطبيق سطر أوامر يوفر وظائف الاستيراد والتصدير لـ Azure Cosmos DB.

التثبيت السريع

لاستخدام الأداة، قم بتنزيل أحدث ملف مضغوط لنظامك الأساسي (win-x64 أو mac-x64 أو linux-x64) من الإصدارات واستخرج جميع الملفات إلى موقع التثبيت المطلوب. لبدء عملية نقل البيانات، قم أولاً بملء ملف migrationsettings.json بالإعدادات المناسبة لمصدر البيانات ومخزنها (راجع الإرشادات التفصيلية أدناه أو راجع الأمثلة)، ثم قم بتشغيل التطبيق من سطر الأوامر: dmt.exe على Windows أو dmt على منصات أخرى.

وثائق التمديد

يتم توفير ملحقات متعددة في هذا المستودع. ابحث عن الوثائق الخاصة باستخدام وتكوين كل منها باستخدام الروابط المتوفرة:

  1. أزور كوزموس دي بي

  2. واجهة برمجة تطبيقات الجدول Azure

  3. JSON

  4. MongoDB

  5. خادم SQL

  6. باركيه

  7. CSV

  8. تخزين الملفات

  9. تخزين Azure Blob

  10. أوس S3

  11. البحث المعرفي أزور

بنيان

تعد أداة ترحيل بيانات سطح المكتب Azure Cosmos DB أداة قابلة للتنفيذ خفيفة الوزن تعمل على تعزيز إطار عمل القابلية للتوسعة المُدار (MEF). يتيح MEF التنفيذ المنفصل للمشروع الأساسي وملحقاته. التطبيق الأساسي عبارة عن سطر أوامر قابل للتنفيذ مسؤول عن إنشاء الامتدادات المطلوبة في وقت التشغيل عن طريق تحميلها تلقائيًا من مجلد الامتدادات الخاص بالتطبيق. الامتداد عبارة عن مكتبة فئة تتضمن تنفيذ النظام كمصدر و(اختياريًا) مصدر لنقل البيانات. لا يحتوي مشروع التطبيق الأساسي على إشارات مباشرة إلى أي تطبيق ملحق. وبدلاً من ذلك، تشترك هذه المشاريع في واجهة مشتركة.

An extensions folder holds multiple extensions implementations.The application loads extensions from the extensions folder and executes functionality based on an interface implementation.

هيكل المشروع

المشروع الأساسي لأداة Cosmos DB Data Migration Tool هو سطر أوامر C# قابل للتنفيذ. يعمل التطبيق الأساسي كحاوية تكوين لامتدادات المصدر والحوض المطلوبة. لذلك، يحتاج مستخدم التطبيق إلى وضع مجموعة مكتبة فئة الامتداد المطلوبة فقط في مجلد الامتدادات قبل تشغيل التطبيق. بالإضافة إلى ذلك، يحتوي المشروع الأساسي على مشروع اختبار الوحدة لممارسة سلوك التطبيق، بينما تحتوي المشاريع الإرشادية على اختبارات تكامل ملموسة تعتمد على أنظمة خارجية.

The project consists of a core application executable project as well as a shared interface project. Each extension will consist of an extension project plus integration test project. A core unit test project exercises the core application functionality.

اعتمد هذا المشروع قواعد السلوك الخاصة بشركة Microsoft مفتوحة المصدر. لمزيد من المعلومات، راجع الأسئلة الشائعة حول قواعد السلوك أو اتصل بـ [email protected] لطرح أي أسئلة أو تعليقات إضافية.

ابدء

استنساخ مستودع التعليمات البرمجية المصدر

  1. من موجه الأوامر، قم بتنفيذ الأمر التالي في مجلد عمل فارغ سيحتوي على التعليمات البرمجية المصدر. 
git clone https://github.com/AzureCosmosDB/data-migration-desktop-tool.git

بناء الحل

  1. باستخدام Visual Studio 2022، افتح CosmosDbDataMigrationTool.sln .

  2. أنشئ المشروع باستخدام اختصار لوحة المفاتيح Ctrl + Shift + B ( Cmd + Shift + B على جهاز Mac). سيؤدي هذا إلى إنشاء جميع مشاريع الامتداد الحالية بالإضافة إلى تطبيق سطر الأوامر الأساسي . تتم كتابة تجميعات إنشاء مشاريع الامتداد في مجلد الملحقات الخاص ببناء التطبيق الأساسي . بهذه الطريقة تكون جميع خيارات الامتداد متاحة عند تشغيل التطبيق.

البرنامج التعليمي: ترحيل JSON إلى Cosmos DB

يوضح هذا البرنامج التعليمي كيفية استخدام أداة ترحيل بيانات سطح المكتب Azure Cosmos DB لنقل بيانات JSON إلى Azure Cosmos DB. يستخدم هذا البرنامج التعليمي Azure Cosmos DB Emulator.

متطلبات البرامج التعليمية

  1. فيجوال ستوديو 2022
  2. صافي 6.0 SDK
  3. محاكي Azure Cosmos DB أو مورد Azure Cosmos DB.

المهمة 1: توفير نموذج قاعدة بيانات وحاوية باستخدام Azure Cosmos DB Emulator كوجهة (مخزن)

  1. قم بتشغيل تطبيق محاكي Azure Cosmos DB وافتح https://localhost:8081/_explorer/index.html في المتصفح.

  2. حدد خيار Explorer من القائمة اليسرى. ثم اختر رابط قاعدة البيانات الجديدة الموجود أسفل عنوان المهام المشتركة .

    The Azure Cosmos DB emulator screen displays with Explorer selected from the left menu and the New Database link highlighted beneath the Common Tasks heading.

  3. في النصل "قاعدة البيانات الجديدة "، أدخل datamigration في الحقل "معرف قاعدة البيانات" ، ثم حدد "موافق" .

    The New Database blade displays with datamigration entered in the Database id field and the OK button is highlighted.

  4. إذا لم تظهر قاعدة بيانات ترحيل البيانات في قائمة قواعد البيانات، فحدد أيقونة التحديث .

    The datamigration database displays with the refresh button highlighted.

  5. قم بتوسيع قائمة القطع الموجودة بجوار قاعدة بيانات ترحيل البيانات وحدد حاوية جديدة .

    The ellipsis menu of the datamigration database is expanded with the New Container item highlighted.

  6. في النصل "الحاوية الجديدة" ، أدخل btcdata في حقل معرف الحاوية ، و /id في حقل مفتاح القسم . حدد الزر موافق .

    The New Container blade displays with btcdata entered in the Container id field and /id entered in the Partition key field. The OK button is highlighted.

    ملاحظة : عند استخدام أداة Cosmos DB Data Migration، لا يلزم أن تكون الحاوية موجودة مسبقًا، وسيتم إنشاؤها تلقائيًا باستخدام مفتاح القسم المحدد في تكوين الحوض.

المهمة 2: إعداد مستندات مصدر JSON

  1. حدد موقع الملف docs/resources/sample-data.zip . استخراج الملفات إلى أي المجلد المطلوب. تعمل هذه الملفات كبيانات JSON التي سيتم ترحيلها إلى Cosmos DB.

المهمة 3: إعداد تكوين ترحيل البيانات

  1. يحتوي كل ملحق على مستند README الذي يوضح التكوين الخاص بترحيل البيانات. في هذه الحالة، حدد موقع تكوين JSON (المصدر) وCosmos DB (Sink).

  2. في Visual Studio Solution Explorer، قم بتوسيع مشروع Microsoft.Data.Transfer.Core ، وافتح المهاجرينsettings.json . يوفر هذا الملف مخططًا تفصيليًا لبنية ملف الإعدادات. باستخدام الوثائق المرتبطة أعلاه، قم بتكوين قسمي SourceSettings و SinkSettings . تأكد من أن إعداد FilePath هو الموقع الذي يتم فيه استخراج بيانات العينة. يمكن العثور على إعداد ConnectionString على شاشة Cosmos DB Emulator Quickstart باعتبارها سلسلة الاتصال الأساسية . احفظ الملف.

    ملاحظة : يمكن استخدام المصطلحين البديلين "الهدف" و "الوجهة" بدلاً من "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
    }
}

    The Cosmos DB Emulator Quickstart screen displays with the Primary Connection String value highlighted.

  3. تأكد من تعيين مشروع Cosmos.DataTransfer.Core كمشروع بدء التشغيل ثم اضغط على F5 لتشغيل التطبيق.

  4. ثم يقوم التطبيق بترحيل البيانات. بعد لحظات قليلة، ستشير العملية إلى اكتمال نقل البيانات. أو فشل نقل البيانات .

ملاحظة : يجب أن تتطابق خصائص Source Sink مع DisplayName المعين في كود الامتدادات.

باستخدام سطر الأوامر

  1. قم بتنزيل أحدث إصدار، أو تأكد من إنشاء المشروع.

  2. يحتوي مجلد الملحقات على المكونات الإضافية المتوفرة للاستخدام في عملية الترحيل. يوجد كل ملحق في مجلد باسم مصدر البيانات. على سبيل المثال، يوجد ملحق Cosmos DB في المجلد Cosmos . قبل تشغيل التطبيق، يمكنك فتح مجلد الملحقات وإزالة أي مجلدات للملحقات غير المطلوبة للترحيل.

  3. في جذر مجلد البناء، حدد موقع المهاجرينsettings.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
    }
}

ملاحظة : يمكن أيضًا تكوين المهاجرينsettings.json لتنفيذ عمليات نقل بيانات متعددة باستخدام أمر تشغيل واحد. للقيام بذلك، قم بتضمين خاصية Operations التي تتكون من مجموعة من الكائنات التي تتضمن خصائص SourceSettings و SinkSettings باستخدام نفس التنسيق الموضح أعلاه للعمليات الفردية. يمكن العثور على تفاصيل وأمثلة إضافية في منشور المدونة هذا.

  1. قم بتنفيذ البرنامج باستخدام الأمر التالي:

    باستخدام ويندوز 

    dmt.exe

    ملاحظة : استخدم خيار --settings مع مسار الملف لتحديد ملف إعدادات مختلف (تجاوز ملف الهجرة الافتراضي.json). وهذا يسهل التشغيل الآلي لمهام الترحيل المختلفة في حلقة برمجية.

    باستخدام ماك 

    ./dmt

    ملاحظة : قبل تشغيل الأداة على نظام التشغيل macOS، ستحتاج إلى اتباع تعليمات Apple حول كيفية فتح تطبيق Mac من مطور غير معروف.

إنشاء ملحقات

  1. حدد نوع الامتداد الذي تريد إنشاءه. هناك 3 أنواع مختلفة من الامتدادات ويمكن تنفيذ كل منها لقراءة البيانات أو كتابتها أو كليهما.

    1. ملحق DataSource/DataSink: مناسب لمصادر البيانات التي تشتمل على تنسيق بيانات أصلي وتخزين. تندرج معظم قواعد البيانات ضمن هذه الفئة، وبشكل عام ستتم كتابة الامتداد الخاص بك باستخدام SDK خاص بهذا النوع من قواعد البيانات. على سبيل المثال، يستخدم SQL Server البيانات المنظمة كجداول ويتم الوصول إليها من خلال برامج التشغيل التي تتعامل مع الاتصال الأساسي مع قاعدة البيانات.
    2. ملحق تخزين الملفات الثنائية: يهتم فقط بتخزين الملفات الثنائية ولا يلتزم بتنسيق الملف المحدد. تتضمن الأمثلة الملفات الموجودة على القرص المحلي أو موفري خدمة تخزين البيانات الثنائية الكبيرة السحابية. يمكن استخدام هذا النوع من الامتدادات بواسطة أي امتداد File Format.
    3. ملحق تنسيق الملف: يتعامل مع ترجمة البيانات لتنسيق ملف ثنائي محدد ولكنه غير ملائم للتخزين. تشمل الأمثلة JSON أو Parquet. يمكن دمج هذا النوع من الامتدادات مع أي ملحق Binary File Storage لإنشاء امتدادات DataSource/DataSink متعددة.

  2. أضف مجلدًا جديدًا في مجلد الامتدادات باسم الامتداد الخاص بك.

  3. قم بإنشاء مشروع التمديد ومشروع الاختبار المصاحب.

    • اصطلاح التسمية لمشاريع الامتداد هو Cosmos.DataTransfer.<Name>Extension .
    • يجب أن تستخدم مشاريع الامتداد إطار عمل .NET 6 ونوع تطبيق وحدة التحكم . يجب تضمين ملف Program.cs لإنشاء مشروع وحدة التحكم. مطلوب مشروع تطبيق وحدة التحكم حتى يتضمن البناء حزم NuGet المرجعية.

    تُستخدم ملحقات تخزين الملفات الثنائية فقط مع ملحقات أخرى، لذا يجب وضعها في .NET 6 Class Library دون تكوين تصحيح الأخطاء الإضافي المطلوب أدناه.

  4. أضف المشاريع الجديدة إلى حل CosmosDbDataMigrationTool .

  5. لتسهيل تصحيح الأخطاء محليًا، يجب نسخ مخرجات بناء الامتداد مع أي تبعيات إلى المجلد CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions . لإعداد المشروع للنسخ تلقائيًا، قم بإضافة التغييرات التالية.

    • قم بإضافة ملف تعريف النشر إلى المجلد المسمى LocalDebugFolder مع الموقع المستهدف لـ ......CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions
    • للنشر في كل مرة يتم فيها إنشاء المشروع، قم بتحرير ملف .csproj لإضافة خطوة جديدة بعد الإنشاء: 
    < Target Name = " PublishDebug " AfterTargets = " Build " Condition = " '$(Configuration)' == 'Debug' " >
   < Exec Command = " dotnet publish --no-build -p:PublishProfile=LocalDebugFolder " />
</ Target >

  6. أضف مراجع إلى حزمة System.ComponentModel.Composition NuGet ومشروع Cosmos.DataTransfer.Interfaces .

  7. يمكن للملحقات تنفيذ إما 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 " ;
}
    1. يمكن استرداد الإعدادات التي يحتاجها الامتداد من أي مصدر تكوين .NET قياسي في التطبيق الرئيسي باستخدام مثيل IConfiguration الذي تم تمريره إلى طريقتي ReadAsync و WriteAsync . سيتم تضمين الإعدادات ضمن SourceSettings / SinkSettings بالإضافة إلى أي إعدادات مضمنة في ملفات JSON المحددة بواسطة SourceSettingsPath / SinkSettingsPath .

  8. قم بتنفيذ الامتداد الخاص بك للقراءة و/أو الكتابة باستخدام واجهة IDataItem العامة التي تعرض خصائص الكائن كأزواج قيمة مفتاح القائمة. اعتمادًا على البنية المحددة لنوع تخزين البيانات الذي يتم تنفيذه، يمكنك اختيار دعم الكائنات والمصفوفات المتداخلة أو خصائص المستوى الأعلى المسطحة فقط.

    تهتم ملحقات تخزين الملفات الثنائية فقط بالتخزين العام، لذا تعمل فقط مع مثيلات Stream التي تمثل الملفات بأكملها بدلاً من IDataItem الفردية.

يوسع
معلومات إضافية
تطبيقات ذات صلة
نوصي لك
أخبار ذات صلة الكل