使用 .NET 在适用于NoSQL 的Azure Cosmos DB中创建项
适用范围: 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
);
要创建项,请调用以下方法之一:
异步创建项
以下示例异步创建一个新项:
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
参数的唯一标识符来确定是否与现有项存在冲突,如果存在,则将相应地替换该项。
后续步骤
现在你已创建各种项,请使用下一个指南读取项。