Membaca item di Azure Cosmos DB untuk NoSQL menggunakan .NET

BERLAKU UNTUK: NoSQL

Item di Azure Cosmos DB mewakili entitas tertentu yang disimpan dalam kontainer. Dalam API untuk NoSQL, item terdiri dari data berformat JSON dengan pengidentifikasi unik.

Setiap item di Azure Cosmos DB for NoSQL memiliki pengidentifikasi unik yang ditentukan oleh id properti . Dalam cakupan kontainer, dua item tidak dapat berbagi pengidentifikasi unik yang sama. Namun, Azure Cosmos DB memerlukan pengidentifikasi unik dan nilai kunci partisi item untuk melakukan pembacaan titik cepat item tersebut. Jika hanya pengidentifikasi unik yang tersedia, Anda harus melakukan kueri yang kurang efisien untuk mencari item di beberapa partisi logis. Untuk mempelajari selengkapnya tentang pembacaan titik dan kueri, lihat mengoptimalkan biaya permintaan untuk membaca data.

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

Untuk melakukan pembacaan titik item, panggil salah satu metode berikut:

• ReadItemAsync<>
• ReadItemStreamAsync<>
• ReadManyItemsAsync<>

Contoh titik berikut membaca satu item secara asinkron dan mengembalikan item yang dideserialisasi menggunakan jenis generik yang disediakan:

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

Metode Database.ReadItemAsync<> membaca item dan mengembalikan objek jenis ItemResponse<>. Jenis ItemResponse<> mewarisi dari Response<> jenis, yang berisi operator konversi implisit untuk mengonversi objek menjadi jenis generik. Untuk mempelajari selengkapnya tentang operator implisit, lihat operator konversi yang ditentukan pengguna.

Atau, Anda dapat mengembalikan jenis generik ItemResponse<> dan secara eksplisit mendapatkan sumber daya. Jenis ItemResponse<> yang lebih umum juga berisi metadata yang berguna tentang operasi API yang mendasar. Dalam contoh ini, metadata tentang biaya unit permintaan untuk operasi ini dikumpulkan menggunakan properti 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;

Contoh ini membaca item sebagai aliran data secara langsung:

// 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();

Metode Container.ReadItemStreamAsync mengembalikan item sebagai Stream tanpa deserialisasi konten.

Jika Anda tidak berencana untuk mendeserialisasi item secara langsung, menggunakan API stream dapat meningkatkan performa dengan menyerahkan item sebagai aliran langsung ke komponen aplikasi Anda berikutnya. Untuk tips selengkapnya tentang cara mengoptimalkan SDK untuk skenario performa tinggi, lihat tips performa SDK.

Dalam contoh ini, daftar tupel yang berisi pengidentifikasi unik dan pasangan kunci partisi digunakan untuk mencari dan mengambil beberapa item:

// 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<> mengembalikan daftar item berdasarkan pengidentifikasi unik dan kunci partisi yang Anda berikan. Operasi ini dimaksudkan untuk melakukan latensi yang lebih baik daripada kueri dengan IN pernyataan untuk mengambil sejumlah besar item independen.

Sekarang setelah Anda membaca berbagai item, gunakan panduan berikutnya untuk mengkueri item.