使用 .NET 在适用于NoSQL 的Azure Cosmos DB中创建项

项目
08/14/2024

适用范围： NoSQL

Azure Cosmos DB 中的项表示存储在容器中的特定实体。在 API for NoSQL 中，项由具有唯一标识符的 JSON 格式数据组成。

为项创建唯一标识符

唯一标识符是标识容器中的项的不同字符串。 id 属性是创建新 JSON 文档时唯一必需的属性。例如，此 JSON 文档是 Azure Cosmos DB 中的有效项：

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

在容器范围内，两个项不能共享同一个唯一标识符。

重要

id 属性区分大小写。名为 ID、Id、iD 和 _id 的属性将被视为任意 JSON 属性。

创建后，项的 URI 采用以下格式：

https://<cosmos-account-name>.documents.azure.cn/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 参数的唯一标识符来确定是否与现有项存在冲突，如果存在，则将相应地替换该项。

后续步骤

现在你已创建各种项，请使用下一个指南读取项。

读取项

通过