مشاركة عبر

استيراد البيانات المجمعة إلى Azure Cosmos DB لحساب NoSQL باستخدام .NET SDK

  • مقالة

ينطبق على: NoSQL

يوضح هذا البرنامج التعليمي كيفية إنشاء تطبيق وحدة تحكم .NET الذي يحسن معدل النقل المتوفر (RU/s) المطلوب لاستيراد البيانات إلى Azure Cosmos DB.

في هذه المقالة، ستقرأ البيانات من مصدر بيانات نموذجي وتستوردها إلى حاوية Azure Cosmos DB. يستخدم هذا البرنامج التعليمي الإصدار 3.0+ من SDK DB.NET Cosmos Azure، والذي يمكن توجيهه إلى .NET Framework أو .NET Core.

يغطي هذا البرنامج التعليمي:

  • إنشاء حساب Azure Cosmos DB
  • تكوين مشروعك
  • الاتصال بحساب Azure Cosmos DB مع تمكين الدعم المجمع
  • تنفيذ استيراد بيانات من خلال عمليات الإنشاء المتزامنة

المتطلبات الأساسية

قبل اتباع الإرشادات الواردة في هذه المقالة، تأكد من أن لديك الموارد التالية:

الخطوة 1: إنشاء حساب Azure Cosmos DB

إنشاء حساب Azure Cosmos DB ل NoSQL من مدخل Microsoft Azure أو يمكنك إنشاء الحساب باستخدام Azure Cosmos DB Emulator.

الخطوة 2: إعداد مشروع .NET الخاص بك

افتح موجه الأوامر Windows أو نافذة المحطة الطرفية من الكمبيوتر المحلي. سيجري تشغيل جميع الأوامر في الأقسام التالية من موجه الأوامر أو المحطة الطرفية. تشغيل الأمر الجديد dotnet التالي لإنشاء تطبيق جديد مع اسم bulk-import-demo.

dotnet new console -n bulk-import-demo

غيّر دليلك إلى مجلد التطبيق المنشأ حديثاً. يمكنك إنشاء التطبيق باستخدام:

cd bulk-import-demo
dotnet build

يجب أن يبدو الناتج المتوقع من الإصدار شيئاً مثل هذا:

Restore completed in 100.37 ms for C:\Users\user1\Downloads\CosmosDB_Samples\bulk-import-demo\bulk-import-demo.csproj.
  bulk -> C:\Users\user1\Downloads\CosmosDB_Samples\bulk-import-demo \bin\Debug\netcoreapp2.2\bulk-import-demo.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:34.17

الخطوة 3: إضافة حزمة AZURE Cosmos DB

أثناء وجودك في دليل التطبيق، ثبت مكتبة عميل Azure Cosmos DB لـ .NET Core باستخدام الأمر dotnet add package.

dotnet add package Microsoft.Azure.Cosmos

الخطوة 4: الحصول على بيانات اعتماد حساب Azure Cosmos DB

يحتاج نموذج التطبيق إلى المصادقة على حساب Azure Cosmos DB الخاص بك. للمصادقة، يجب تمرير بيانات اعتماد حساب Azure Cosmos DB إلى التطبيق. احصل على بيانات اعتماد حساب Azure Cosmos DB باتباع الخطوات التالية:

  1. قم بتسجيل الدخول إلى بوابة Azure.
  2. انتقل إلى حسابك على Azure Cosmos DB.
  3. افتح جزء "Keys" وانسخ "URI" و"PRIMARY KEY" لحسابك.

إذا كنت تستخدم Azure Cosmos DB Emulator، فاحصل على بيانات اعتماد المحاكي من هذه المقالة.

الخطوة 5: تهيئة الكائن CosmosClient مع دعم تنفيذ مجمع

افتح الملف المنشأ Program.cs في محرر تعليمات برمجية. ستنشئ مثيلاً جديداً من CosmosClient مع تمكين التنفيذ المجمّع واستخدامه لإجراء عمليات ضد Azure Cosmos DB.

لنبدأ بالكتابة فوق الأسلوب Main الافتراضي وتعريف المتغيرات العمومية. ستتضمن هذه المتغيرات العامة نقطة النهاية، ومفاتيح التخويل، واسم قاعدة البيانات، والحاوية التي ستنشئها، وعدد العناصر التي ستدرجها بشكل مجمّع. تأكد من استبدال endpointURL وقيم مفتاح التخويل وفقاً لبيئتك.

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.IO;
using System.Text.Json;
using System.Threading.Tasks;
using Microsoft.Azure.Cosmos;

public class Program
{
     private const string EndpointUrl = "https://<your-account>.documents.azure.com:443/";
     private const string AuthorizationKey = "<your-account-key>";
     private const string DatabaseName = "bulk-tutorial";
     private const string ContainerName = "items";
     private const int AmountToInsert = 300000;

     static async Task Main(string[] args)
     {

     }
}

داخل Main الأسلوب، أضف التعليمات البرمجية التالية لتهيئة الكائن CosmosClient:

CosmosClient cosmosClient = new CosmosClient(EndpointUrl, AuthorizationKey, new CosmosClientOptions() { AllowBulkExecution = true });

إشعار

بمجرد تحديد التنفيذ المجمّع في CosmosClientOptions، فإنها تصبح غير قابلة للتغيير بشكل فعّال مدة بقاء CosmosClient. لن يكون لتغيير القيم أي تأثير.

بعد تمكين التنفيذ المجمع، يقوم CosmosClient داخلياً بتجميع العمليات المتزامنة في مكالمات خدمة واحدة. وبهذه الطريقة فإنه يُحسّن استخدام معدل النقل عن طريق توزيع مكالمات الخدمة عبر الأقسام، وأخيراً تعيين نتائج فردية للمتصلين الأصليين.

يمكنك بعد ذلك إنشاء حاوية لتخزين جميع العناصر. عرّف /pk كمفتاح القسم و50000 RU/s على أنه معدل النقل المتوفر و نهج فهرسة مخصصة والذي سيستبعد جميع الحقول لتحسين سرعة الكتابة. أضف التعليمات البرمجية التالية بعد عبارة التهيئة CosmosClient:

Database database = await cosmosClient.CreateDatabaseIfNotExistsAsync(Program.DatabaseName);

await database.DefineContainer(Program.ContainerName, "/pk")
        .WithIndexingPolicy()
            .WithIndexingMode(IndexingMode.Consistent)
            .WithIncludedPaths()
                .Attach()
            .WithExcludedPaths()
                .Path("/*")
                .Attach()
        .Attach()
    .CreateAsync(50000);

الخطوة 6: تعبئة قائمة المهام المتزامنة

للاستفادة من دعم التنفيذ المجمع، أنشئ قائمة بالمهام غير المتزامنة استناداً إلى مصدر البيانات والعمليات التي تريد تنفيذها، واستخدم Task.WhenAll لتنفيذها بشكل متزامن. لنبدأ باستخدام بيانات "وهمية" لإنشاء قائمة بالعناصر من نموذج البيانات الخاص بنا. في تطبيق العالم الحقيقي، ستأتي العناصر من مصدر البيانات المطلوب.

أولاً، أضف حزمة Bogus إلى الحل باستخدام الأمر "dotnet add package".

dotnet add package Bogus

تعريف العناصر التي تريد حفظها. تحتاج إلى تعريف الفئة Item داخل Program.cs الملف:

public class Item
{
    public string id {get;set;}
    public string pk {get;set;}

    public string username{get;set;}
}

بعد ذلك، أنشئ دالة مساعدة داخل Program الفئة. ستحصل دالة المساعدة هذه على عدد العناصر التي عرفتها لإدراج وإنشاء بيانات عشوائية:

private static IReadOnlyCollection<Item> GetItemsToInsert()
{
    return new Bogus.Faker<Item>()
    .StrictMode(true)
    //Generate item
    .RuleFor(o => o.id, f => Guid.NewGuid().ToString()) //id
    .RuleFor(o => o.username, f => f.Internet.UserName())
    .RuleFor(o => o.pk, (f, o) => o.id) //partitionkey
    .Generate(AmountToInsert);
}

استخدم الدالة المساعدة لتهيئة قائمة المستندات للعمل مع:

IReadOnlyCollection<Item> itemsToInsert = Program.GetItemsToInsert();

ثم استخدم قائمة المستندات لإنشاء مهام متزامنة وتعبئة قائمة المهام لإدراج العناصر في الحاوية. لتنفيذ هذه العملية، أضف التعليمات البرمجية التالية إلى Program الفئة:

Container container = database.GetContainer(ContainerName);
List<Task> tasks = new List<Task>(AmountToInsert);
foreach (Item item in itemsToInsert)
{
    tasks.Add(container.CreateItemAsync(item, new PartitionKey(item.pk))
        .ContinueWith(itemResponse =>
        {
            if (!itemResponse.IsCompletedSuccessfully)
            {
                AggregateException innerExceptions = itemResponse.Exception.Flatten();
                if (innerExceptions.InnerExceptions.FirstOrDefault(innerEx => innerEx is CosmosException) is CosmosException cosmosException)
                {
                    Console.WriteLine($"Received {cosmosException.StatusCode} ({cosmosException.Message}).");
                }
                else
                {
                    Console.WriteLine($"Exception {innerExceptions.InnerExceptions.FirstOrDefault()}.");
                }
            }
        }));
}

// Wait until all are done
await Task.WhenAll(tasks);

ستُنفذ كافة عمليات النقاط المتزامنة هذه معًا (المجمعة) كما هو موضح في مقطع المقدمة.

الخطوة 7: تشغيل العينة

لتشغيل العينة، يمكنك فعل ذلك ببساطة عن طريق dotnet الأمر:

dotnet run

الحصول على عينة مكتملة

إذا لم يكن لديك الوقت لإكمال الخطوات في هذا البرنامج التعليمي، أو تريد فقط تحميل عينات تعليمات برمجية، يمكنك الحصول عليها من GitHub.

بعد نسخ المشروع، تأكد من تحديث بيانات الاعتماد المطلوبة داخل Program.cs.

يمكن تشغيل العينة عن طريق التغيير إلى دليل المستودع واستخدام dotnet :

cd cosmos-dotnet-bulk-import-throughput-optimizer
dotnet run

الخطوات التالية

في هذا البرنامج التعليمي، كنت قد نفذت الخطوات التالية:

  • إنشاء حساب Azure Cosmos DB
  • تكوين مشروعك
  • الاتصال بحساب Azure Cosmos DB مع تمكين الدعم المجمع
  • تنفيذ استيراد بيانات من خلال عمليات الإنشاء المتزامنة

يمكنك الآن المتابعة إلى البرنامج التعليمي التالي:

الاستعلام عن Azure Cosmos DB باستخدام واجهة برمجة التطبيقات ل NoSQL

هل تحاول القيام بتخطيط السعة للترحيل إلى Azure Cosmos DB؟ يمكنك استخدام معلومات حول نظام مجموعة قاعدة البيانات الموجودة لديك لـ تخطيط السعة.