Membuat item di Azure Cosmos DB untuk NoSQL menggunakan .NET

Artikel
08/15/2024

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.

Membuat pengidentifikasi unik untuk item

Pengidentifikasi unik adalah string berbeda yang mengidentifikasi item dalam kontainer. Properti id adalah satu-satunya properti yang diperlukan saat membuat dokumen JSON baru. Misalnya, dokumen JSON ini adalah item yang valid di Azure Cosmos DB:

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

Dalam cakupan kontainer, dua item tidak dapat berbagi pengidentifikasi unik yang sama.

Penting

Properti id ini peka huruf besar/kecil. Properti bernama ID, Id, iD, dan _id akan diperlakukan sebagai properti JSON arbitrer.

Setelah dibuat, URI untuk item berada dalam format ini:

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

Saat mereferensikan item menggunakan URI, gunakan pengidentifikasi sumber daya yang dihasilkan sistem alih-alih bidang id. Untuk informasi selengkapnya tentang properti item yang dihasilkan sistem di Azure Cosmos DB untuk NoSQL, lihat properti item

Membuat item

Catatan

Contoh dalam artikel ini mengasumsikan bahwa Anda telah menentukan jenis C# untuk mewakili data Anda bernama Produk:

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

Contohnya juga mengasumsikan bahwa Anda telah membuat objek baru jenis Produk bernama newItem:

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

Untuk membuat item, panggil salah satu metode berikut:

CreateItemAsync<>
ReplaceItemAsync<>
UpsertItemAsync<>

Membuat item secara asinkron

Contoh berikut membuat item baru secara asinkron:

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

Metode Container.CreateItemAsync<> ini akan memberikan pengecualian jika ada konflik dengan pengidentifikasi unik item yang ada. Untuk mempelajari selengkapnya tentang potensi pengecualian, lihat CreateItemAsync<> pengecualian.

Mengganti item secara asinkron

Contoh berikut menggantikan item yang ada secara asinkron:

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

Metode Container.ReplaceItemAsync<> ini memerlukan string yang disediakan untuk parameter id agar sesuai dengan pengidentifikasi unik parameter item.

Membuat atau mengganti item secara asinkron

Contoh berikut akan membuat item baru atau mengganti item yang sudah ada jika item sudah ada dengan pengidentifikasi unik yang sama:

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

Metode Container.UpsertItemAsync<> ini akan menggunakan pengidentifikasi unik parameter item untuk menentukan apakah ada konflik dengan item yang ada dan untuk mengganti item dengan tepat.

Langkah berikutnya

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

Membaca item

Bagikan melalui