بدء استخدام 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

إنشاء تطبيق .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 باستخدام فئة CosmosClient :

• الاتصال بواجهة برمجة تطبيقات لنقطة نهاية NoSQL ومفتاح القراءة/الكتابة
• الاتصال بواجهة برمجة تطبيقات ل NoSQL سلسلة الاتصال
• الاتصال بمعرف Microsoft Entra

الاتصال بإحدى نقاط النهاية وأحد المفاتيح

تحتوي الدالة الإنشائية الأكثر شيوعاً لدى CosmosClient على معلمتين:

المعلمة‬	قيمة المثال	‏‏الوصف
accountEndpoint	متغير البيئة COSMOS_ENDPOINT	واجهة برمجة التطبيقات لنقطة نهاية NoSQL لاستخدامها لجميع الطلبات
authKeyOrResourceToken	متغير البيئة COSMOS_KEY	مفتاح الحساب أو الرمز المميز للمورد لاستخدامه عند المصادقة

استرداد نقطة نهاية حسابك ومفتاحه

Azure CLI

1. إنشاء متغير shell لدى resourceGroupName.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos-dotnet-howto-rg"
   

2. استخدم الأمر az cosmosdb list لاسترداد اسم حساب Azure Cosmos DB الأول في مجموعة الموارد وتخزينه في متغير accountName shell.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

3. احصل على واجهة برمجة التطبيقات لنقطة نهاية NoSQL URI للحساب باستخدام az cosmosdb show الأمر .

   az cosmosdb show \
       --resource-group $resourceGroupName \
       --name $accountName \
       --query "documentEndpoint"
   

4. ابحث عن PRIMARY KEY من قائمة مفاتيح الحساب باستخدام الأمر az-cosmosdb-keys-list.

   az cosmosdb keys list \
       --resource-group $resourceGroupName \
       --name $accountName \
       --type "keys" \
       --query "primaryMasterKey"
   

5. سجل قيم URI وPRIMARY KEY. سوف تستخدم بيانات الاعتماد هذه لاحقًا.

بوويرشيل

1. إنشاء متغير shell لدى RESOURCE_GROUP_NAME.

   # Variable for resource group name
   $RESOURCE_GROUP_NAME = "msdocs-cosmos-dotnet-howto-rg"
   

2. استخدم الأمر Get-AzCosmosDBAccount cmdlet لاسترداد اسم حساب Azure Cosmos DB الأول في مجموعة الموارد وتخزينه في متغير ACCOUNT_NAME shell.

   # Retrieve most recently created account name
   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
   }
   $ACCOUNT_NAME = (
       Get-AzCosmosDBAccount @parameters |
           Select-Object -Property Name -First 1
   ).Name
   

3. احصل على واجهة برمجة التطبيقات لنقطة نهاية NoSQL URI للحساب باستخدام Get-AzCosmosDBAccount cmdlet.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
   }
   Get-AzCosmosDBAccount @parameters |
       Select-Object -Property "DocumentEndpoint"
   

4. ابحث عن PRIMARY KEY من قائمة مفاتيح الحساب باستخدام الأمر Get-AzCosmosDBAccountKey cmdlet.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "Keys"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "PrimaryMasterKey"    
   

5. سجل قيم URI وPRIMARY KEY. سوف تستخدم بيانات الاعتماد هذه لاحقًا.

بوابة

تلميح

نوصي باستخدام اسم مجموعة الموارد msdocs-cosmos-dotnet-howto-rgفي هذا الدليل.

1. قم بتسجيل الدخول إلى بوابة Azure.

2. انتقل إلى صفحة حساب Azure Cosmos DB for NoSQL الموجودة.

3. من صفحة حساب Azure Cosmos DB for NoSQL، حدد خيار قائمة التنقل Keys .

   

4. سجل القيم من حقلي URI وPRIMARY KEY. سوف تستخدم هذه القيم في خطوة لاحقة.

   

لاستخدام قيم URI و PRIMARY KEY داخل التعليمات البرمجية لتطبيق .NET، استمر في استخدام متغيرات البيئة الجديدة على الجهاز المحلي الذي يقوم بتشغيل التطبيق.

Windows

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Linux / macOS

export COSMOS_ENDPOINT="<cosmos-account-URI>"
export COSMOS_KEY="<cosmos-account-PRIMARY-KEY>"

إنشاء CosmosClient باستخدام نقطة نهاية الحساب ومفتاحه

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

// New instance of CosmosClient class using an endpoint and key string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    authKeyOrResourceToken: Environment.GetEnvironmentVariable("COSMOS_KEY")!
);

الاتصال بسلسلة الاتصال

تحتوي دالة إنشائية أخرى في CosmosClient على معلمة واحدة فقط:

المعلمة‬	قيمة المثال	‏‏الوصف
accountEndpoint	متغير البيئة COSMOS_ENDPOINT	واجهة برمجة التطبيقات لنقطة نهاية NoSQL لاستخدامها لجميع الطلبات
connectionString	متغير البيئة COSMOS_CONNECTION_STRING	سلسلة الاتصال بواجهة برمجة التطبيقات لحساب NoSQL

استرداد سلسلة الاتصال حسابك

Azure CLI

1. استخدم الأمر az cosmosdb list لاسترداد اسم حساب Azure Cosmos DB الأول في مجموعة الموارد وتخزينه في متغير accountName shell.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

2. ابحث عن سلسلة الاتصال PRIMARY CONNECTION STRING من قائمة سلاسل الاتصال للحساب باستخدام الأمر az-cosmosdb-keys-list.

   az cosmosdb keys list \
       --resource-group $resourceGroupName \
       --name $accountName \
       --type "connection-strings" \
       --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"
   

بوويرشيل

1. استخدم الأمر Get-AzCosmosDBAccount cmdlet لاسترداد اسم حساب Azure Cosmos DB الأول في مجموعة الموارد وتخزينه في متغير ACCOUNT_NAME shell.

   # Retrieve most recently created account name
   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
   }
   $ACCOUNT_NAME = (
       Get-AzCosmosDBAccount @parameters |
           Select-Object -Property Name -First 1
   ).Name
   

2. ابحث عن سلسلة الاتصال PRIMARY CONNECTION STRING من قائمة سلاسل الاتصال للحساب باستخدام Get-AzCosmosDBAccountKey cmdlet.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary SQL Connection String" -First 1    
   

بوابة

تلميح

نوصي باستخدام اسم مجموعة الموارد msdocs-cosmos-dotnet-howto-rgفي هذا الدليل.

1. قم بتسجيل الدخول إلى بوابة Azure.

2. انتقل إلى صفحة حساب Azure Cosmos DB for NoSQL الموجودة.

3. من صفحة حساب Azure Cosmos DB for NoSQL، حدد خيار قائمة التنقل Keys .

4. سجل القيمة من حقل PRIMARY CONNECTION STRING.

لاستخدام قيمة PRIMARY CONNECTION STRING ضمن التعليمات البرمجية في .NET لديك، استمر في ذلك إلى متغير بيئة جديد على الجهاز المحلي الذي يقوم بتشغيل التطبيق.

Windows

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Linux / macOS

export COSMOS_CONNECTION_STRING="<cosmos-account-PRIMARY-CONNECTION-STRING>"

إنشاء CosmosClient باستخدام سلسلة الاتصال

إنشاء مثيل جديد من فئة CosmosClient باستخدام متغير البيئة COSMOS_CONNECTION_STRING باعتباره المعلمة الوحيدة.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    connectionString: Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING")!
);

الاتصال باستخدام النظام الأساسي للهويات في Microsoft

للاتصال بواجهة برمجة التطبيقات الخاصة بك لحساب NoSQL باستخدام النظام الأساسي للهويات في Microsoft ومعرف 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
);

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

إذا كنت تخطط لنشر التطبيق خارج Azure، فيمكنك الحصول على رمز OAuth مميز باستخدام فئات أخرى في مكتبة عميل Azure Identity لـ.NET. هذه الفئات الأخرى مشتقة من الفئة TokenCredential أيضاً.

على سبيل المثال، نقوم بإنشاء مثيل ClientSecretCredential باستخدام معرفات العميل والمستأجر، بالإضافة إلى سر العميل.

// Custom credential class for servers and clients outside of Azure
TokenCredential credential = new ClientSecretCredential(
    tenantId: Environment.GetEnvironmentVariable("AAD_TENANT_ID")!,
    clientId: Environment.GetEnvironmentVariable("AAD_CLIENT_ID")!,
    clientSecret: Environment.GetEnvironmentVariable("AAD_CLIENT_SECRET")!,
    options: new TokenCredentialOptions()
);

يمكنك الحصول على معرف العميل ومعرف المستأجر وسر العميل عند تسجيل تطبيق في معرف Microsoft Entra. لمزيد من المعلومات حول تسجيل تطبيقات Microsoft Entra، راجع تسجيل تطبيق مع النظام الأساسي للهويات في Microsoft.

قم بإنشاء مثيل جديد من فئة 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	هذه الفئة مرجع لإحدى الحاويات التي قد لا تكون موجودة أيضاً في الخدمة بعد. يتم التحقق من صحة الحاوية من جانب الخادم عندما تحاول العمل معها.

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

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

(راجع أيضًا )

• حزمة (NuGet)
• العينات
• مرجع واجهة برمجة التطبيقات
• التعليمات البرمجية لمصدر للمكتبة
• تقديم ملاحظات

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

الآن بعد أن قمت بالاتصال بواجهة برمجة تطبيقات لحساب NoSQL، استخدم الدليل التالي لإنشاء قواعد البيانات وإدارتها.

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