使用 .NET 在 Azure Cosmos DB for NoSQL 中建立項目

發行項
08/15/2024

適用於：NoSQL

Azure Cosmos DB 中的項目代表儲存在容器內的特定實體。在 NoSQL API 中，項目是由具有唯一識別碼的 JSON 格式資料所組成。

建立項目的唯一識別碼

唯一識別碼是識別容器內專案的相異字串。屬性 id 是建立新 JSON 文件時唯一的必要屬性。例如，此 JSON 文件是 Azure Cosmos DB 中的有效項目：

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

在容器的範圍內，兩個項目無法共用相同的唯一識別碼。

重要

id 屬性必須區分大小寫。名為 ID、Id、iD 和 _id 的屬性會被視為任意 JSON 屬性。

建立之後，項目的 URI 格式如下：

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

使用 URI 參考項目時，請使用系統產生的資源識別碼，而不是 id 欄位。如需 Azure Cosmos DB for NoSQL 中系統所產生項目屬性的詳細資訊，請參閱項目的屬性

建立項目

注意

本文中的範例假設您已經定義 C# 類型來代表名為 Product 的資料：

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

這些範例也假設您已經建立名為 newItem 的 Product 類型新物件：

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

若要建立項目，請呼叫下列其中一種方法：

CreateItemAsync<>
ReplaceItemAsync<>
UpsertItemAsync<>

以非同步方式建立項目

下列範例會以非同步方式建立新項目：

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 參數的唯一識別碼來判斷是否有與現有項目發生衝突，並適當地取代項目。

下一步

既然您已建立各種項目，請使用下一個指南來讀取項目。

讀取項目

共用方式為