التشغيل السريع: Azure Cosmos DB ل MongoDB ل .NET مع برنامج تشغيل MongoDB

مقالة
08/15/2024

ينطبق على: MongoDB

ابدأ باستخدام MongoDB لإنشاء قواعد البيانات والمجموعات والمستندات داخل مورد Azure Cosmos DB. اتبع هذه الخطوات لنشر الحد الأدنى من الحل إلى البيئة الخاصة بك باستخدام Azure Developer CLI.

API للوثائق | المرجعية MongoDB حزم حزمة MongoDB (NuGet) / Microsoft.Azure.Cosmos) | Azure Developer CLI

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

حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
حساب GitHub

حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
Azure Developer CLI
Docker Desktop

الإعداد

نشر حاوية تطوير هذا المشروع إلى البيئة الخاصة بك. ثم استخدم Azure Developer CLI (azd) لإنشاء Azure Cosmos DB لحساب MongoDB ونشر نموذج تطبيق حاوية. يستخدم نموذج التطبيق مكتبة العميل لإدارة البيانات النموذجية وإنشاءها وقراءتها والاستعلام عن البيانات.

هام

تتضمن حسابات GitHub استحقاق التخزين والساعات الأساسية دون أي تكلفة. لمزيد من المعلومات، راجع التخزين المضمن والساعات الأساسية لحسابات GitHub.

افتح محطة طرفية في الدليل الجذر للمشروع.
المصادقة على Azure Developer CLI باستخدام azd auth login. اتبع الخطوات المحددة بواسطة الأداة للمصادقة على CLI باستخدام بيانات اعتماد Azure المفضلة لديك.
```
azd auth login
```
استخدم azd init لتهيئة المشروع.
```
azd init --template cosmos-db-mongodb-dotnet-quickstart
```
إشعار

يستخدم هذا التشغيل السريع مستودع GitHub لقالب azure-samples/cosmos-db-mongodb-dotnet-quickstart . سيقوم Azure Developer CLI تلقائيا باستنساخ هذا المشروع إلى جهازك إذا لم يكن موجودا بالفعل.
أثناء التهيئة، قم بتكوين اسم بيئة فريد.

تلميح

سيتم أيضا استخدام اسم البيئة كاسم مجموعة الموارد الهدف. لهذا التشغيل السريع، ضع في اعتبارك استخدام msdocs-cosmos-db.
انشر حساب Azure Cosmos DB باستخدام azd up. تنشر قوالب Bicep أيضا نموذج تطبيق ويب.
```
azd up
```
أثناء عملية التوفير، حدد اشتراكك والموقع المطلوب. انتظر حتى اكتمال عملية التوفير. قد تستغرق العملية حوالي خمس دقائق.

بمجرد توفير موارد Azure الخاصة بك، يتم تضمين عنوان URL لتطبيق الويب قيد التشغيل في الإخراج.

Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

استخدم عنوان URL في وحدة التحكم للانتقال إلى تطبيق الويب الخاص بك في المستعرض. لاحظ إخراج التطبيق قيد التشغيل.

تثبيت مكتبة العميل

تتوفر مكتبة العميل من خلال NuGet، كحزمة Microsoft.Azure.Cosmos .

افتح terminal وانتقل إلى /src/web المجلد.
```
cd ./src/web
```
إذا لم يكن مثبتا بالفعل، فقم بتثبيت الحزمة MongoDb.Driver باستخدام dotnet add package.
```
dotnet add package MongoDb.Driver
```
أيضا، قم بتثبيت الحزمة Azure.Identity إذا لم تكن مثبتة بالفعل.
```
dotnet add package Azure.Identity
```

نموذج الكائن

قبل البدء في إنشاء التطبيق، لنلقِ نظرة على التدرج الهرمي للموارد في قاعدة بيانات Azure Cosmos DB. تحتوي قاعدة بيانات Azure Cosmos DB على نموذج كائن محدد يُستخدم لإنشاء الموارد والوصول إليها. تنشئ قاعدة بيانات Azure Cosmos DB موارد في تدرج هرمي يتكون من الحسابات وقواعد البيانات والحاويات والمستندات.

رسم تخطيطي لتدرج Azure Cosmos DB الهرمي بما في ذلك الحسابات وقواعد البيانات والمجموعات والمستندات.

يمكنك استخدام فئات MongoDB التالية للتفاعل مع هذه الموارد:

MongoClient - توفر هذه الفئة تمثيلا منطقيا من جانب العميل لواجهة برمجة التطبيقات لطبقة MongoDB على Azure Cosmos DB. يتم استخدام كائن العميل لتكوين الطلبات وتنفيذها على الخدمة.
MongoDatabase - هذه الفئة هي مرجع إلى قاعدة بيانات قد تكون موجودة في الخدمة أو قد لا تكون موجودة بعد. يتم التحقق من صحة قاعدة البيانات من جانب الخادم عند محاولة الوصول إليها أو إجراء عملية ضدها.
Collection - هذه الفئة هي مرجع إلى مجموعة قد لا تكون موجودة أيضا في الخدمة حتى الآن. يتم التحقق من صحة المجموعة من جانب الخادم عندما تحاول استخدامها.

ينشئ نموذج التعليمات البرمجية الموضح في هذه المقالة قاعدة بيانات مسماة adventureworks بحاوية مُسماة products. تم تصميم المجموعة products لتحتوي على تفاصيل المنتج مثل الاسم والفئة والكمية ومؤشر البيع. يحتوي كل منتج أيضًا على معرّف فريد.

مصادقة العميل

من دليل المشروع، افتح ملف Program.cs. في المحرر الخاص بك، أضف توجيه استخدام لـ MongoDB.Driver.

using MongoDB.Driver;

حدد مثيلا جديدا للفئة MongoClient باستخدام الدالة الإنشائية، ولقراءة Environment.GetEnvironmentVariable سلسلة الاتصال التي تم تعيينها بواسطة Azure Developer CLI سابقا.

// New instance of CosmosClient class
var client = new MongoClient(Environment.GetEnvironmentVariable("MONGO_CONNECTION"));

إنشاء قاعدة بيانات

استخدم الأسلوب MongoClient.GetDatabase لإنشاء قاعدة بيانات جديدة إذا لم تكن موجودة بالفعل. يقوم هذا الأسلوب بإرجاع مرجع إلى قاعدة البيانات الموجودة أو التي تم إنشاؤها حديثا.

// Database reference with creation if it does not already exist
var db = client.GetDatabase("adventure");

إنشاء مجموعة

MongoDatabase.GetCollection ينشئ مجموعة جديدة إذا لم تكن موجودة بالفعل وإرجاع مرجع إلى المجموعة.

// Container reference with creation if it does not alredy exist
var _products = db.GetCollection<Product>("products");

إنشاء عنصر

أسهل طريقة لإنشاء عنصر جديد في مجموعة هي إنشاء فئة C# أو نوع سجل مع جميع الأعضاء الذين تريد تسلسلهم في JSON. في هذا المثال، يحتوي سجل C# على معرف فريد وحقل فئة لمفتاح القسم وحقول الاسموالكميةوالبيع الإضافية.

public record Product(
    string Id,
    string Category,
    string Name,
    int Quantity,
    bool Sale
);

أنشئ عنصر في المجموعة باستخدام السجل Product عن طريق استدعاء IMongoCollection<TDocument>.InsertOne.

// Create new object and upsert (create or replace) to container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Yamba Surfboard", 
    12, 
    false
));

الحصول على عنصر

في قاعدة بيانات Azure Cosmos، يمكنك استرداد العناصر عن طريق إنشاء استعلامات باستخدام Linq. في SDK، استدعِ IMongoCollection.FindAsync<> ومرر تعبير C# لتصفية النتائج.

// Read a single item from container
var product = (await _products.FindAsync(p => p.Name.Contains("Yamba"))).FirstOrDefault();
Console.WriteLine("Single product:");
Console.WriteLine(product.Name);

عناصر الاستعلام

بعد إدراج عنصر، يمكنك تشغيل استعلام للحصول على جميع العناصر التي تطابق عامل تصفية معين بمعالجة المجموعة على أنها IQueryable. يستخدم هذا المثال تعبيرًا لتصفية المنتجات حسب الفئة. بمجرد إجراء الاستدعاء AsQueryable، استدعِ MongoQueryable.Where لاسترداد مجموعة من العناصر التي جرى تصفيتها.

// Read multiple items from container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Sand Surfboard",
    4,
    false
));

var products = _products.AsQueryable().Where(p => p.Category == "gear-surf-surfboards");

Console.WriteLine("Multiple products:");
foreach (var prod in products)
{
    Console.WriteLine(prod.Name);
}

تشغيل التعليمات البرمجية

ينشئ هذا التطبيق قاعدة بيانات ومجموعة Azure Cosmos DB MongoDb API. يقوم المثال بعد ذلك بإنشاء عنصر ثم يقرأ نفس العنصر بالضبط مرة أخرى. أخيرًا، يُنشئ المثال عنصرًا ثانيًا ثم يُجرى استعلام يجب أن يرجع عناصر متعددة. مع كل خطوة، يقوم المثال بإخراج بيانات التعريف إلى وحدة التحكم حول الخطوات المنفذة.

لتشغيل التطبيق، استخدم terminal للانتقال إلى دليل التطبيق وتشغيل التطبيق.

dotnet run

يجب أن يكون إخراج التطبيق مشابهًا لهذا المثال:

Single product name: 
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard

تنظيف الموارد

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

استخدم الأمر az group delete لحذف مجموعة الموارد.

az group delete --name $resourceGroupName

استخدم الأمر Remove-AzResourceGroup cmdlet لحذف مجموعة الموارد.

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

مشاركة عبر