مشاركة عبر

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

  • مقالة

ينطبق على: NoSQL

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

قراءة العناصر ذات المعرفات الفريدة

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

قراءة عنصر

إشعار

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

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

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

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

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

// Read existing item from container
Product readItem = await container.ReadItemAsync<Product>(
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

يقرأ الأسلوب Database.ReadItemAsync<> والعنصر ويعيد عنصر من النوع ItemResponse<>. يرث نوع ItemResponse<> من النوع Response<> الذي يحتوي على عامل تحويل ضمني لتحويل العنصر إلى النوع العام. لمعرفة المزيد حول عوامل التشغيل الضمنية، راجع عوامل تشغيل التحويل المعرفة من قبل المستخدم.

بدلا من ذلك، يمكنك إرجاع النوع العام ItemResponse<> والحصول على المورد بشكل صريح. يحتوي نوع ItemResponse<> الأكثر عمومية أيضا على بيانات تعريف مفيدة حول عملية واجهة برمجة التطبيقات الأساسية. في هذا المثال، يتم جمع بيانات التعريف حول رسوم وحدة الطلب لهذه العملية باستخدام الخاصية RequestCharge.

// Read existing item from container
ItemResponse<Product> readResponse = await container.ReadItemAsync<Product>(
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

// Get response metadata
double requestUnits = readResponse.RequestCharge;
HttpStatusCode statusCode = readResponse.StatusCode;

// Explicitly get item
Product readItemExplicit = readResponse.Resource;

قراءة عنصر كتدفق بشكل غير متزامن

يقرأ هذا المثال عنصرا كتدفق بيانات مباشرة:

// Read existing item from container
using ResponseMessage readItemStreamResponse = await container.ReadItemStreamAsync(
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

// Get stream from response
using StreamReader readItemStreamReader = new(readItemStreamResponse.Content);

// (optional) Get stream content
string content = await readItemStreamReader.ReadToEndAsync();

يقوم الأسلوب Container.ReadItemStreamAsync بإرجاع العنصر ك Stream دون إلغاء تسلسل المحتويات.

إذا كنت لا تخطط لإلغاء تسلسل العناصر مباشرة، يمكن أن يؤدي استخدام دفق البيانات APIs إلى تحسين الأداء عن طريق تسليم العنصر كتدفق مباشرة إلى المكون التالي من التطبيق الخاص بك. لمزيد من التلميحات حول كيفية تحسين SDK للسيناريوهات عالية الأداء، راجع نصائح أداء SDK.

قراءة عناصر متعددة بشكل غير متزامن

في هذا المثال، يتم استخدام قائمة بالمجموعات التي تحتوي على معرف فريد وأزواج مفاتيح القسم للبحث عن عناصر متعددة واستردادها:

// Create partition key object
PartitionKey partitionKey = new("gear-surf-surfboards");

// Create list of tuples for each item
List<(string, PartitionKey)> itemsToFind = new()
{
    ("68719518388", partitionKey),
    ("68719518381", partitionKey)
};

// Read multiple items
FeedResponse<Product> feedResponse = await container.ReadManyItemsAsync<Product>(
    items: itemsToFind
);

foreach (Product item in feedResponse)
{
    Console.WriteLine($"Found item:\t{item.name}");
}

Container.ReadManyItemsAsync<> يرجع قائمة بالعناصر استنادا إلى المعرفات الفريدة ومفاتيح الأقسام التي توفرها. تهدف هذه العملية إلى أداء زمن انتقال أفضل من الاستعلام مع IN عبارات لجلب عدد كبير من العناصر المستقلة.

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

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

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