التشغيل السريع: Azure Cosmos DB for Table for .NET

مقالة
03/10/2024

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

يوضح هذا التشغيل السريع كيفية البدء باستخدام Azure Cosmos DB للجدول من تطبيق .NET. Azure Cosmos DB للجدول هو مخزن بيانات بلا مخطط يسمح للتطبيقات بتخزين بيانات الجدول المنظمة في السحابة. ستتعلم كيفية إنشاء جداول وصفوف وتنفيذ المهام الأساسية داخل مورد Azure Cosmos DB باستخدام حزمة Azure.Data.Tables (NuGet).

إشعار

تتوفر القصاصات البرمجية المثال على GitHub كمشروع .NET.

API للوثائق | المرجعية للجداول حزمة Azure.Data.Tables (NuGet)

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

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

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

الإعداد

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

هام

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

افتح محطة طرفية في الدليل الجذر للمشروع.
المصادقة على Azure Developer CLI باستخدام azd auth login. اتبع الخطوات المحددة بواسطة الأداة للمصادقة على CLI باستخدام بيانات اعتماد Azure المفضلة لديك.
```
azd auth login
```
استخدم azd init لتهيئة المشروع.
```
azd init
```
أثناء التهيئة، قم بتكوين اسم بيئة فريد.

تلميح

سيتم أيضا استخدام اسم البيئة كاسم مجموعة الموارد الهدف. لهذا التشغيل السريع، ضع في اعتبارك استخدام 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
```
إذا لم يكن مثبتا بالفعل، فقم بتثبيت الحزمة Azure.Data.Tables باستخدام dotnet add package.
```
dotnet add package Azure.Data.Tables
```
أيضا، قم بتثبيت الحزمة Azure.Identity إذا لم تكن مثبتة بالفعل.
```
dotnet add package Azure.Identity
```
افتح الملف src/web/Cosmos.Samples.Table.Quickstart.Web.csproj وراجعه للتحقق من وجود Microsoft.Azure.Cosmos الإدخالين وAzure.Identity.

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

ستستخدم واجهة برمجة التطبيقات التالية لفئات الجدول للتفاعل مع هذه الموارد:

TableServiceClient - توفر هذه الفئة أساليب لتنفيذ عمليات مستوى الخدمة باستخدام Azure Cosmos DB للجدول.
TableClient - تسمح لك هذه الفئة بالتفاعل مع الجداول المستضافة في واجهة برمجة تطبيقات جدول Azure Cosmos DB.
TableEntity - هذه الفئة هي مرجع إلى صف في جدول يسمح لك بإدارة الخصائص وبيانات العمود.

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

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

using Azure.Data.Tables;

حدد مثيلًا جديدًا للفئة TableServiceClient باستخدام الدالة الإنشائية وEnvironment.GetEnvironmentVariable لقراءة سلسلة الاتصال التي عيّنتها مسبقًا.

// New instance of the TableClient class
TableServiceClient tableServiceClient = new TableServiceClient(Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING"));

إنشاء جدول

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

// New instance of TableClient class referencing the server-side table
TableClient tableClient = tableServiceClient.GetTableClient(
    tableName: "adventureworks"
);

await tableClient.CreateIfNotExistsAsync();

إنشاء عنصر

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

// C# record type for items in the table
public record Product : ITableEntity
{
    public string RowKey { get; set; } = default!;

    public string PartitionKey { get; set; } = default!;

    public string Name { get; init; } = default!;

    public int Quantity { get; init; }

    public bool Sale { get; init; }

    public ETag ETag { get; set; } = default!;

    public DateTimeOffset? Timestamp { get; set; } = default!;
}

إنشاء عنصر في المجموعة باستخدام الفئة Product عن طريق استدعاء TableClient.AddEntityAsync<T>.

// Create new item using composite key constructor
var prod1 = new Product()
{
    RowKey = "68719518388",
    PartitionKey = "gear-surf-surfboards",
    Name = "Ocean Surfboard",
    Quantity = 8,
    Sale = true
};

// Add new item to server-side table
await tableClient.AddEntityAsync<Product>(prod1);

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

يمكنك استرداد عنصر معين من جدول باستخدام الأسلوب TableEntity.GetEntityAsync<T>. قم بتوفير partitionKey وrowKey كمعلمات لتحديد الصف الصحيح لتنفيذ قراءة نقطة سريعة لهذا العنصر.

// Read a single item from container
var product = await tableClient.GetEntityAsync<Product>(
    rowKey: "68719518388",
    partitionKey: "gear-surf-surfboards"
);
Console.WriteLine("Single product:");
Console.WriteLine(product.Value.Name);

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

بعد إدراج عنصر، يمكنك أيضًا تشغيل استعلام للحصول على جميع العناصر التي تطابق عامل تصفية معين باستخدام الأسلوب TableClient.Query<T>. يقوم هذا المثال بتصفية المنتجات حسب الفئة باستخدام بناء جملة Linq، وهي ميزة لاستخدام نماذج ITableEntity مكتوبة مثل الفئة Product.

إشعار

يمكنك أيضًا الاستعلام عن العناصر باستخدام بناء جملة OData. يمكنك مشاهدة مثال على هذا الأسلوب في البرنامج التعليمي بيانات الاستعلام.

// Read multiple items from container
var prod2 = new Product()
{
    RowKey = "68719518390",
    PartitionKey = "gear-surf-surfboards",
    Name = "Sand Surfboard",
    Quantity = 5,
    Sale = false
};

await tableClient.AddEntityAsync<Product>(prod2);

var products = tableClient.Query<Product>(x => x.PartitionKey == "gear-surf-surfboards");

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

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

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

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

dotnet run

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

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

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

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

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

az group delete --name $resourceGroupName

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

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

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

في هذا التشغيل السريع، تعلمت كيفية إنشاء حساب Azure Cosmos DB للجدول، وإنشاء جدول، وإدارة الإدخالات باستخدام .NET SDK. يمكنك الآن التعمق أكثر في SDK لمعرفة كيفية تنفيذ استعلامات البيانات ومهام الإدارة الأكثر تقدما في Azure Cosmos DB لموارد الجدول.

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

Share via