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

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

تمثل العناصر في Azure Cosmos DB كيانًا معينًا مخزنًا في جدول. في واجهة برمجة التطبيقات للجدول، يتكون العنصر من مجموعة من أزواج قيم المفاتيح التي تم تعريفها بشكل فريد بواسطة مركب مفاتيح الصف والأقسام.

إنشاء معرف فريد لعنصر

المعرف الفريد، المعروف برمجيا باسم **** هو سلسلة مميزة تحدد عنصرًا داخل جدول. يتضمن كل عنصر أيضًا قيمة مفتاح القسم المستخدمة لتحديد القسم المنطقي للعنصر. كلا المفتاحين مطلوبان عند إنشاء عنصر جديد داخل جدول.

ضمن نطاق الجدول، لا يمكن لاثنين من العناصر مشاركة مفتاح الصف ومفتاح القسم نفسه.

إنشاء عنصر

الفئة TableEntity هي تطبيق عام لقاموس مصمم بشكل فريد لتسهيل إنشاء عنصر جديد من قاموس عشوائي لأزواج قيم المفاتيح.

استخدم إحدى الاستراتيجيات التالية لنمذجة العناصر التي ترغب في إنشائها في جدول:

• إنشاء مثيل للفئة TableEntity
• تنفيذ واجهة ITableEntity

استخدام فئة مضمنة

(string rowKey, string partitionKey) الدالة الإنشائية لفئة TableEntity طريقة سريعة لإنشاء عنصر بالخصائص المطلوبة فقط. يمكنك بعد ذلك استخدام الأسلوب Add لإضافة أزواج قيمة مفتاح إضافية إلى العنصر.

على سبيل المثال، يمكنك إنشاء مثيل جديد من فئة TableEntity عن طريق تحديد مفاتيح الصف والقسم أولاً في الدالة الإنشائية ثم إضافة أزواج قيم مفاتيح جديدة إلى القاموس:

// Create new item using composite key constructor
TableEntity item1 = new(
    rowKey: "68719518388",
    partitionKey: "gear-surf-surfboards"
);

// Add properties to item
item1.Add("Name", "Sunnox Surfboard");
item1.Add("Quantity", 8);
item1.Add("Sale", true);

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

تحول (IDictionary<string, object>)الدالة الإنشائية لفئة TableEntity قاموسًا موجودًا إلى عنصر جاهز لإضافته إلى جدول.

على سبيل المثال، يمكنك تمرير قاموس إلى مثيل جديد من فئة TableEntity:

// Create dictionary
Dictionary<string, object> properties = new()
{
    { "RowKey", "68719518388" },
    { "PartitionKey", "gear-surf-surfboards" },
    { "Name", "Sunnox Surfboard" },
    { "Quantity", 8 },
    { "Sale", true }
};

// Create new item using dictionary constructor
TableEntity item2 = new(
    values: properties
);

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

يأخذ الأسلوب TableClient.AddEntityAsync<> معلمة من نوع TableEntity ثم يقوم بإنشاء عنصر من جانب الخادم في الجدول.

تنفيذ واجهة

إشعار

تفترض الأمثلة في هذا القسم أنك قد حددت بالفعل نوع C # لتمثيل بياناتك المسماة Product:

// 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!;
}

يأخذ الأسلوب TableClient.AddEntityAsync<> معلمة من أي نوع ينفذ الواجهةITableEntity. تتضمن الواجهة بالفعل RowKey المطلوب وخصائص PartitionKey.

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

// Create new item
Product item = new()
{
    RowKey = "68719518388",
    PartitionKey = "gear-surf-surfboards",
    Name = "Sunnox Surfboard",
    Quantity = 8,
    Sale = true
};

يمكنك بعد ذلك تمرير هذا العنصر إلى أسلوب AddEntityAsync<> لإنشاء عنصر من جانب الخادم:

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

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

الآن بعد أن قمت بإنشاء عناصر مختلفة، استخدم الدليل التالي لقراءة عنصر.

قراءة عنصر