التشغيل السريع: Azure Cosmos DB for Table for .NET
ينطبق على: جدول
يوضح هذا التشغيل السريع كيفية البدء باستخدام 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);
الحصول على عنصر
يمكنك استرداد عنصر معين من جدول باستخدام الأسلوب TableClient.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
الخطوات التالية
في هذا التشغيل السريع، تعلمت كيفية إنشاء حساب Azure Cosmos DB للجدول، وإنشاء جدول، وإدارة الإدخالات باستخدام .NET SDK. يمكنك الآن التعمق أكثر في SDK لمعرفة كيفية تنفيذ استعلامات البيانات ومهام الإدارة الأكثر تقدما في Azure Cosmos DB لموارد الجدول.