مشاركة عبر

بدء استخدام Azure Cosmos DB ل NoSQL باستخدام .NET

  • مقالة

ينطبق على: NoSQL

توضح هذه المقالة كيفية الاتصال ب Azure Cosmos DB ل NoSQL باستخدام .NET SDK. بمجرد الاتصال، يمكنك إجراء عمليات على قواعد البيانات والحاويات والعناصر.

حزمة (NuGet) | العينات | مرجع API | رمز مصدر المكتبة | تقديم الملاحظات

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

إعداد مشروعك

إنشاء تطبيق .NET جديد باستخدام dotnet new الأمر مع قالب وحدة التحكم .

dotnet new console

قم باستيراد حزمة Microsoft.Azure.Cosmos NuGet باستخدام الأمر dotnet add package.

dotnet add package Microsoft.Azure.Cosmos

قم بإنشاء المشروع باستخدام الأمرdotnet build.

dotnet build

الاتصال ب Azure Cosmos DB ل NoSQL

للاتصال بواجهة برمجة التطبيقات ل NoSQL ل Azure Cosmos DB، قم بإنشاء مثيل للفئة CosmosClient . هذه الفئة هي نقطة البداية لتنفيذ جميع العمليات الخاصة بقواعد البيانات.

للاتصال بواجهة برمجة التطبيقات الخاصة بك لحساب NoSQL باستخدام Microsoft Entra، استخدم أساس أمان. سيعتمد النوع الدقيق للحساب الأساسي على المكان الذي تستضيف فيه التعليمات البرمجية للتطبيق الخاص بك. الجدول التالي دليل مرجعي سريع.

مكان تشغيل التطبيق أساس الأمان
جهاز محلي (تطوير واختبار) هوية المستخدم أو كيان الخدمة
Azure الهوية المُدارة
الخوادم أو العملاء خارج Azure كيان الخدمة

قم باستيراد حزمة Azure.Identity

تحتوي حزمة Azure.Identity NuGet على وظائف المصادقة الأساسية التي تتم مشاركتها بين جميع مكتبات Azure SDK.

قم باستيراد حزمة Azure.Identity NuGet باستخدام الأمر dotnet add package.

dotnet add package Azure.Identity

أعد إنشاء المشروع باستخدام الأمر dotnet build.

dotnet build

في محرر التعليمات البرمجية لديك، أضف استخدام التوجيهات في مساحات الأسماء Azure.Core وAzure.Identity.

using Azure.Core;
using Azure.Identity;

قم بإنشاء CosmosClient عن طريق تنفيذ بيانات الاعتماد الافتراضية

إذا كنت تجري الاختبار على جهاز محلي، أو سيتم تشغيل تطبيقك على خدمات Azure بدعم مباشر للهويات المدارة، فاحصل على رمز OAuth المميز عن طريق إنشاء مثيل DefaultAzureCredential.

على سبيل المثال، قمنا بحفظ المثيل في متغير من النوع TokenCredential وهو نوع عام أكثر يمكن إعادة استخدامه عبر عدة تطوير البرامج.

// Credential class for testing on a local machine or Azure services
TokenCredential credential = new DefaultAzureCredential();

قم بإنشاء مثيل جديد من فئة CosmosClient عن طريق متغير البيئة COSMOS_ENDPOINT وكائن TokenCredential باعتبارها معلمات.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    tokenCredential: credential
);

إنشاء التطبيق الخاص بك

في أثناء إنشاء تطبيقك، سوف تتفاعل التعليمة البرمجية الخاصة بك في المقام الأول مع أربعة أنواع من الموارد:

  • واجهة برمجة التطبيقات لحساب NoSQL، وهي مساحة الاسم الفريدة ذات المستوى الأعلى لبيانات Azure Cosmos DB.

  • قواعد البيانات، وهي تنظم الحاويات في حسابك.

  • الحاويات، وهي تحتوي على مجموعة من العناصر الفردية في قاعدة البيانات الخاصة بك.

  • العناصر، وهي تمثل مستند JSON في الحاوية الخاصة بك.

يعرض الرسم التخطيطي التالي العلاقة بين هذه الموارد.

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

يتم تمثيل كل نوع من الموارد بواسطة فئة .NET مقترنة واحدة أو أكثر. فيما يلي قائمة بالفئات الأكثر شيوعاً:

الفصل ‏‏الوصف
CosmosClient توفر هذه الفئة تمثيلاً منطقياً من جانب العميل لخدمة Azure Cosmos DB. يتم استخدام كائن العميل لتكوين الطلبات وتنفيذها على الخدمة.
Database هذه الفئة مرجع لإحدى قواعد البيانات التي قد تكون موجودة في الخدمة أو قد لا تكون موجودة بعد. يتم التحقق من صحة قاعدة البيانات من جانب الخادم عند محاولة الوصول إليها أو إجراء عملية ضدها.
Container هذه الفئة مرجع لإحدى الحاويات التي قد لا تكون موجودة أيضاً في الخدمة بعد. يتم التحقق من صحة الحاوية من جانب الخادم عندما تحاول العمل معها.

توضح لك الأدلة التالية كيفية استخدام كل فئة من هذه الفئات لإنشاء التطبيق الخاص بك.

الدليل: ‏‏الوصف
إنشاء قاعدة بيانات إنشاء قواعد بيانات
إنشاء حاوية إنشاء حاويات
قراءة عنصر نقطة قراءة عنصر معين
عناصر الاستعلام الاستعلام عن عناصر متعددة

(راجع أيضًا )

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

إنشاء قاعدة بيانات في Azure Cosmos DB ل NoSQL باستخدام .NET