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

ينطبق على: الجدول

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

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

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

• حساب Azure باشتراك نشط. إنشاء حساب مجاناً.
• Azure Cosmos DB لحساب الجدول. إنشاء واجهة برمجة تطبيقات لحساب الجدول.
• .إصدار NET 6.0 أو إصدار أحدث
• واجهة سطر الأوامر من Azure (CLI) أو Azure PowerShell

إعداد مشروعك

إنشاء تطبيق وحدة تحكم .NET

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

dotnet new console

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

dotnet add package Azure.Data.Tables

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

dotnet build

الاتصال ب Azure Cosmos DB للجدول

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

• الاتصال بواجهة برمجة تطبيقات لسلسلة اتصال الجدول

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

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

المعلمة	قيمة المثال	الوصف
connectionString	متغير البيئة COSMOS_CONNECTION_STRING	سلسلة الاتصال بواجهة برمجة التطبيقات لحساب الجدول

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

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 Table Connection String\`] | [0].connectionString"
   

PowerShell

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 Table Connection String" -First 1    
   

لاستخدام قيمة 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>"

إنشاء TableServiceClient مع سلسلة الاتصال

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

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

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

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

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

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

• العناصر التي تمثل عنصرًا فرديًا في جدولك.

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

رسم تخطيطي هرمي يظهر حساب قاعدة بيانات Azure Cosmos في الأعلى. يحتوي الحساب على عقدتين فرعيتين في الجدول. تتضمن إحدى عقد الجدول عنصرين تابعين.

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

الفصل	الوصف
TableServiceClient	توفر فئة العميل هذه تمثيلًا منطقيًا من جانب العميل لخدمة Azure Cosmos DB. يتم استخدام كائن العميل لتكوين الطلبات وتنفيذها على الخدمة.
TableClient	فئة العميل هذه هي إشارة إلى جدول قد يكون موجودًا أو غير موجود في الخدمة حتى الآن. تم التحقق من صحة الجدول من جانب الخادم عند محاولة الوصول إليه أو إجراء عملية عليه.
ITableEntity	هذه الواجهة هي الواجهة الأساسية لأي عناصر تم إنشاؤها في الجدول أو تم الاستعلام عنها من الجدول. تتضمن هذه الواجهة جميع الخصائص المطلوبة للعناصر في واجهة برمجة التطبيقات للجدول.
TableEntity	هذه الفئة هي تطبيق عام للواجهة ITableEntity كقاموس لأزواج قيم المفاتيح.

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

الدليل:	الوصف
إنشاء جدول	إنشاء جداول
إنشاء عنصر	إنشاء عناصر
قراءة عنصر	قراءة العناصر

راجع أيضًا

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

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

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

إنشاء جدول في Azure Cosmos DB للجدول باستخدام .NET