بدء استخدام Azure Cosmos DB ل NoSQL باستخدام .NET
ينطبق على: NoSQL
توضح هذه المقالة كيفية الاتصال ب Azure Cosmos DB ل NoSQL باستخدام .NET SDK. بمجرد الاتصال، يمكنك إجراء عمليات على قواعد البيانات والحاويات والعناصر.
حزمة (NuGet) | العينات | مرجع API | رمز مصدر المكتبة | تقديم الملاحظات
المتطلبات الأساسية
- حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
- Azure Cosmos DB لحساب NoSQL. إنشاء واجهة برمجة تطبيقات لحساب NoSQL.
- .إصدار NET 6.0 أو إصدار أحدث
- واجهة سطر الأوامر من Azure (واجهة مستوى الاستدعاء) أو Azure PowerShell
إعداد مشروعك
إنشاء تطبيق .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 في الأعلى. يحتوي الحساب على عقدتين تابعتين لقاعدة البيانات. تتضمن إحدى عُقد قاعدة البيانات عقدتين تابعتين للحاوية. تتضمن عقدة قاعدة البيانات الأخرى عقدة حاوية تابعة واحدة. تحتوي عقدة الحاوية المفردة على ثلاث عُقد عناصر تابعة.
يتم تمثيل كل نوع من الموارد بواسطة فئة .NET مقترنة واحدة أو أكثر. فيما يلي قائمة بالفئات الأكثر شيوعاً:
الفصل | الوصف |
---|---|
CosmosClient |
توفر هذه الفئة تمثيلاً منطقياً من جانب العميل لخدمة Azure Cosmos DB. يتم استخدام كائن العميل لتكوين الطلبات وتنفيذها على الخدمة. |
Database |
هذه الفئة مرجع لإحدى قواعد البيانات التي قد تكون موجودة في الخدمة أو قد لا تكون موجودة بعد. يتم التحقق من صحة قاعدة البيانات من جانب الخادم عند محاولة الوصول إليها أو إجراء عملية ضدها. |
Container |
هذه الفئة مرجع لإحدى الحاويات التي قد لا تكون موجودة أيضاً في الخدمة بعد. يتم التحقق من صحة الحاوية من جانب الخادم عندما تحاول العمل معها. |
توضح لك الأدلة التالية كيفية استخدام كل فئة من هذه الفئات لإنشاء التطبيق الخاص بك.
الدليل: | الوصف |
---|---|
إنشاء قاعدة بيانات | إنشاء قواعد بيانات |
إنشاء حاوية | إنشاء حاويات |
قراءة عنصر | نقطة قراءة عنصر معين |
عناصر الاستعلام | الاستعلام عن عناصر متعددة |