استيراد البيانات المجمعة إلى 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 مع تمكين الدعم المجمع
- تنفيذ استيراد بيانات من خلال عمليات الإنشاء المتزامنة
المتطلبات الأساسية
قبل اتباع الإرشادات الواردة في هذه المقالة، تأكد من أن لديك الموارد التالية:
حساب Azureنشط. في حال لم يكن لديك اشتراك Azure، فأنشئ حساباً مجانيّاً قبل البدء.
بدلاً من ذلك، يمكنك تجربة قاعدة بيانات Azure Cosmos مجاناً دون اشتراك Azure، مجاناً دون التزامات. بدلاً من ذلك، يمكنك إنشاء حساب Azure Cosmos DB مجاني ، مع أول 1000 RU/s و 25GB من التخزين مجاناً. يمكنك أيضًا استخدام محاكي Azure Cosmos DB مع عنوان URL المستخدم
https://localhost:8081
. لاستخدام المفتاح مع المحاكي، راجع مصادقة الطلبات.NET Core 3 SDK. يمكنك التحقق من الإصدار المتوفر في بيئتك عن طريق تشغيل
dotnet --version
.
الخطوة 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 باتباع الخطوات التالية:
- قم بتسجيل الدخول إلى بوابة Azure.
- انتقل إلى حسابك على Azure Cosmos DB.
- افتح جزء "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؟ يمكنك استخدام معلومات حول نظام مجموعة قاعدة البيانات الموجودة لديك لـ تخطيط السعة.
- إذا لم تكن تعرف سوى عدد vCores والخوادم في نظام مجموعة قاعدة البيانات الحالية فقط، فاقرأ عن تقدير وحدات الطلب باستخدام vCores أو vCPUs
- إذا كان كل ما تعرفه هو عدد vcores والخوادم الموجودة في مجموعة قاعدة البيانات، اقرأ عن تقدير وحدات الطلب باستخدام vCores أو vCPUs