مشاركة عبر

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

  • مقالة

ينطبق على: NoSQL

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

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

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

{
  "id": "unique-string-2309509"
}

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

هام

الخاصية id حساسة لحالة الأحرف. سيتم التعامل مع الخصائص المسماة ID، وId وiD، و_id كخاصية JSON عشوائية.

بمجرد الإنشاء، يكون عنوان موقع الويب للعنصر بهذا التنسيق:

https://<cosmos-account-name>.documents.azure.com/dbs/<database-name>/docs/<item-resource-identifier>

عند الرجوع إلى العنصر باستخدام عنوان موقع ويب، بإستخدم معرف المورد الذي أنشأه النظام بدلا من الحقلid. لمزيد من المعلومات حول خصائص العنصر الذي أنشأه النظام في Azure Cosmos DB ل NoSQL، راجع خصائص عنصر

إنشاء عنصر

إشعار

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

// C# record type for items in the container
public record Product(
    string id,
    string category,
    string name,
    int quantity,
    bool sale
);

تفترض الأمثلة أيضا أنك قمت بالفعل بإنشاء عنصر جديد من نوع Product يسمى newItem:

// Create new item and add to container
Product item = new(
    id: "68719518388",
    category: "gear-surf-surfboards",
    name: "Sunnox Surfboard",
    quantity: 8,
    sale: true
);

لإنشاء عنصر، قم باستدعاء إحدى الأساليب التالية:

إنشاء عنصر بشكل غير متزامن

ينشئ المثال التالي عنصر جديد بشكل غير متزامن:

Product createdItem = await container.CreateItemAsync<Product>(
    item: item,
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

سيطرح الأسلوبContainer.CreateItemAsync<> استثناء إذا كان هناك تعارض مع المعرف الفريد لعنصر موجود. لمعرفة المزيد حول الاستثناءات المحتملة، راجع CreateItemAsync<> الاستثناءات.

استبدال عنصر بشكل غير متزامن

يحل المثال التالي محل عنصر موجود بشكل غير متزامن:

Product replacedItem = await container.ReplaceItemAsync<Product>(
    item: item,
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

يتطلب الأسلوب Container.ReplaceItemAsync<> السلسلة المتوفرة للمعلمة id لمطابقة المعرف الفريد للمعلمة item.

إنشاء عنصر أو استبداله بشكل غير متزامن

سيقوم المثال التالي بإنشاء عنصر جديد أو استبدال عنصر موجود إذا كان هناك عنصر موجود بالفعل بنفس المعرف الفريد:

Product upsertedItem = await container.UpsertItemAsync<Product>(
    item: item,
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

سيستخدم الأسلوب Container.UpsertItemAsync<> المعرف الفريد للمعلمة item لتحديد ما إذا كان هناك تعارض مع عنصر موجود واستبدال العنصر بشكل مناسب.

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

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

قراءة عنصر