使用 Azure Cosmos DB for NoSQL SDK 创建和更新文档

Microsoft.Azure.Cosmos.Container 类包括一组成员方法，用于在 Azure Cosmos DB for NoSQL 容器中创建、检索、更新和删除项。这些方法共同在 NoSQL API 容器中对各种项执行一些最常见的“CRUD”操作。

在本实验室中，你将在 Azure Cosmos DB for NoSQL 容器中使用 SDK 对项执行日常 CRUD 操作。

准备开发环境

如果你还没有将 DP-420 的实验室代码存储库克隆到使用此实验室的环境，请按照以下步骤操作。否则，请在 Visual Studio Code 中打开以前克隆的文件夹。

启动 Visual Studio Code。

📝 如果你还不熟悉 Visual Studio Code 界面，请参阅入门文档
打开命令面板并运行 Git: Clone，将 https://github.com/microsoftlearning/dp-420-cosmos-db-dev GitHub 存储库克隆到你选择的本地文件夹中。

💡 你可以使用 Ctrl+Shift+P 键盘快捷方式打开命令面板。
克隆存储库后，打开在 Visual Studio Code 中选择的本地文件夹。

创建 Azure Cosmos DB for NoSQL 帐户

Azure Cosmos DB 是一项基于云的 NoSQL 数据库服务，它支持多个 API。在首次预配 Azure Cosmos DB 帐户时，可以选择希望该帐户支持的 API（例如 Mongo API 或 NoSQL API）。完成 Azure Cosmos DB for NoSQL 帐户预配后，可以检索终结点和密钥，并使用它们通过 Azure SDK for .NET 或所选择的任何其他 SDK 连接到 Azure Cosmos DB for NoSQL 帐户。

在新的 Web 浏览器窗口或选项卡中，导航到 Azure 门户 (portal.azure.com)。
使用与你的订阅关联的 Microsoft 凭证登录到门户。

选择“+ 创建资源”，搜索“Cosmos DB”，然后使用以下设置创建新的“Azure Cosmos DB for NoSQL”帐户资源，并将所有其余设置保留为默认值：

设置	值
订阅	你的现有 Azure 订阅
资源组	选择现有资源组，或创建新资源组
帐户名	输入全局唯一名称
位置	选择任何可用区域
容量模式	预配的吞吐量
应用免费分级折扣	不应用

📝 你的实验室环境可能存在阻止你创建新资源组的限制。如果是这种情况，请使用现有的预先创建的资源组。

等待部署任务完成，然后继续执行此任务。
转到新创建的 Azure Cosmos DB 帐户资源，并导航到“键”窗格。
此窗格包含从 SDK 连接到帐户所需的连接详细信息和凭据。具体而言：
1. 请注意“URI”** 字段。稍后在本练习中将用到此终结点值。
2. 请注意“主键”** 字段。稍后在本练习中将用到此键值。
切回到 Visual Studio Code**。

从 SDK 连接到 Azure Cosmos DB for NoSQL 帐户

使用新创建帐户中的凭据，你将连接到 SDK 类，并创建新的数据库和容器实例。然后，你将使用数据资源管理器验证这些实例是否存在于 Azure 门户中。

在 Visual Studio Code 的“资源管理器”窗格中，浏览到“06-sdk-crud”文件夹。
打开“06-sdk-crud”文件夹的上下文菜单，然后选择“在集成终端中打开”以打开新的终端实例。

📝 此命令将打开起始目录已设置为“06-sdk-crud”文件夹的终端。

使用以下命令从 NuGet 添加 Microsoft.Azure.Cosmos 包：

 dotnet add package Microsoft.Azure.Cosmos --version 3.22.1

使用 dotnet build 命令生成项目：
```
 dotnet build
```
关闭集成终端。
在 06-sdk-crud 文件夹内打开 script.cs 代码文件。

📝 已从 NuGet 中预先导入 Microsoft.Azure.Cosmos 库。
找到名为 endpoint 的 string 变量。将它的值设置为之前创建的 Azure Cosmos DB 帐户的终结点。
```
 string endpoint = "<cosmos-endpoint>";
```
📝 例如，如果终结点为：https://dp420.documents.azure.com:443/，则 C# 语句将为：string endpoint = “https://dp420.documents.azure.com:443/”;。
找到名为 key 的 string 变量。将它的值设置为之前创建的 Azure Cosmos DB 帐户的键。
```
 string key = "<cosmos-key>";
```
📝 例如，如果键为：fDR2ci9QgkdkvERTQ==，则 C# 语句应为：string key = “fDR2ci9QgkdkvERTQ==”;。
异步调用 client 变量的 CreateDatabaseIfNotExistsAsync 方法，传入要创建的新数据库的名称 (cosmicworks)，并将结果存储在 Database 类型的变量中：
```
 Database database = await client.CreateDatabaseIfNotExistsAsync("cosmicworks");
```
异步调用 database 变量的 CreateContainerIfNotExistsAsync 方法，传入新容器的名称 (products)、分区键路径 (/categoryId)，以及要在 cosmicworks 中创建的吞吐量 (400)，并将结果存储在 Container 类型的变量中：
```
 Container container = await database.CreateContainerIfNotExistsAsync("products", "/categoryId", 400);    
```

完成后，代码文件现在应包含：

 using System;
 using Microsoft.Azure.Cosmos;

 string endpoint = "<cosmos-endpoint>";
 string key = "<cosmos-key>";

 CosmosClient client = new CosmosClient(endpoint, key);
    
 Database database = await client.CreateDatabaseIfNotExistsAsync("cosmicworks");
    
 Container container = await database.CreateContainerIfNotExistsAsync("products", "/categoryId", 400);

保存 script.cs 代码文件。
在 Visual Studio Code 中，打开 06-sdk-crud 文件夹的上下文菜单，然后选择“在集成终端中打开”以打开一个新的终端实例。
使用 dotnet run 命令生成并运行项目：
```
 dotnet run
```
关闭集成终端。
切回到 Web 浏览器窗口。
在 Azure Cosmos DB 帐户资源中，导航到“数据资源管理器”窗格。
在“数据资源管理器”** 中，展开“cosmicworks”** 数据库节点，然后在“NoSQL API”** 导航树中观察新“products”** 容器节点。

使用 SDK 对项执行创建和读取点操作

现在，你将在 Microsoft.Azure.Cosmos.Container 类中使用一组异步方法，对 NoSQL API 容器中的项执行常见操作。这些操作都是使用 C# 中的任务异步编程模型完成的。

返回到 Visual Studio Code。在 06-sdk-crud 文件夹内打开 product.cs 代码文件。

📝 不要关闭 script.cs 文件编辑器。
查看此代码文件中的 Product 类。此类表示将在此容器中进行存储和操作的产品项。
返回到 script.cs 代码文件的“编辑器”选项卡。

使用以下属性创建一个 Product 类型的名为 saddle 的新对象：

属性	值
id	706cd7c6-db8b-41f9-aea2-0e0c7e8eb009
categoryId	9603ca6c-9e28-4a02-9194-51cdb7fea816
name	Road Saddle
price	45.99d
tags	{ tan, new, crisp }

 Product saddle = new()
 {
     id = "706cd7c6-db8b-41f9-aea2-0e0c7e8eb009",
     categoryId = "9603ca6c-9e28-4a02-9194-51cdb7fea816",
     name = "Road Saddle",
     price = 45.99d,
     tags = new string[]
     {
         "tan",
         "new",
         "crisp"
     }
 };

异步调用 container 变量的泛型 CreateItemAsync<> 方法，将 saddle 变量作为方法参数传入，并使用 Product 作为泛型类型：
```
 await container.CreateItemAsync<Product>(saddle);
```

完成后，代码文件现在应包含：

 using System;
 using Microsoft.Azure.Cosmos;

 string endpoint = "<cosmos-endpoint>";
 string key = "<cosmos-key>";

 CosmosClient client = new CosmosClient(endpoint, key);
    
 Database database = await client.CreateDatabaseIfNotExistsAsync("cosmicworks");
    
 Container container = await database.CreateContainerIfNotExistsAsync("products", "/categoryId", 400);

 Product saddle = new()
 {
     id = "706cd7c6-db8b-41f9-aea2-0e0c7e8eb009",
     categoryId = "9603ca6c-9e28-4a02-9194-51cdb7fea816",
     name = "Road Saddle",
     price = 45.99d,
     tags = new string[]
     {
         "tan",
         "new",
         "crisp"
     }
 };

 await container.CreateItemAsync<Product>(saddle);

保存 script.cs 代码文件。
在 Visual Studio Code 中，打开 06-sdk-crud 文件夹的上下文菜单，然后选择“在集成终端中打开”以打开一个新的终端实例。
使用 dotnet run 命令生成并运行项目：
```
 dotnet run
```
关闭集成终端。
返回到 script.cs 代码文件的“编辑器”选项卡。

删除以下代码行：

 Product saddle = new()
 {
     id = "706cd7c6-db8b-41f9-aea2-0e0c7e8eb009",
     categoryId = "9603ca6c-9e28-4a02-9194-51cdb7fea816",
     name = "Road Saddle",
     price = 45.99d,
     tags = new string[]
     {
         "tan",
         "new",
         "crisp"
     }
 };

 await container.CreateItemAsync<Product>(saddle);

创建一个名为 id 的字符串变量，其值为 706cd7c6-db8b-41f9-aea2-0e0c7e8eb009：
```
 string id = "706cd7c6-db8b-41f9-aea2-0e0c7e8eb009";
```
创建一个名为 categoryId 的字符串变量，其值为 9603ca6c-9e28-4a02-9194-51cdb7fea816：
```
 string categoryId = "9603ca6c-9e28-4a02-9194-51cdb7fea816";
```
创建一个名为 partitionKey 的变量，其类型为 PartitionKey，将 categoryId 变量作为构造函数参数传入：
```
 PartitionKey partitionKey = new (categoryId);
```
异步调用 container 变量的泛型 ReadItemAsync<> 方法，将 id 和 partitionkey 变量作为方法参数传入，使用 Product 作为泛型类型，并将结果存储在 Product 类型的名为 saddle 的变量中：
```
 Product saddle = await container.ReadItemAsync<Product>(id, partitionKey);
```
调用静态 Console.WriteLine 方法，使用格式化的输出字符串输出 saddle 对象：
```
 Console.WriteLine($"[{saddle.id}]\t{saddle.name} ({saddle.price:C})");
```

完成后，代码文件现在应包含：

 using System;
 using Microsoft.Azure.Cosmos;

 string endpoint = "<cosmos-endpoint>";
 string key = "<cosmos-key>";

 CosmosClient client = new CosmosClient(endpoint, key);
    
 Database database = await client.CreateDatabaseIfNotExistsAsync("cosmicworks");
    
 Container container = await database.CreateContainerIfNotExistsAsync("products", "/categoryId", 400);

 string id = "706cd7c6-db8b-41f9-aea2-0e0c7e8eb009";

 string categoryId = "9603ca6c-9e28-4a02-9194-51cdb7fea816";
 PartitionKey partitionKey = new (categoryId);

 Product saddle = await container.ReadItemAsync<Product>(id, partitionKey);

 Console.WriteLine($"[{saddle.id}]\t{saddle.name} ({saddle.price:C})");

保存 script.cs 代码文件。
在 Visual Studio Code 中，打开 06-sdk-crud 文件夹的上下文菜单，然后选择“在集成终端中打开”以打开一个新的终端实例。
使用 dotnet run 命令生成并运行项目：
```
 dotnet run
```
查看终端输出。具体而言，请查看带有项的 id、Name和Price的格式化输出文本。
关闭集成终端。

使用 SDK 执行更新和删除点操作

在学习 SDK 期间，使用联机 Azure Cosmos DB SDK 帐户或仿真器来更新项，在执行操作时在数据资源管理器与所选的 IDE 之间来回切换，以及查看更改是否已应用，是很常见的情况。在本实验室中，当你使用 SDK 更新和删除项时，你就会这样做。

返回 Web 浏览器窗口或选项卡。
在 Azure Cosmos DB 帐户资源中，导航到“数据资源管理器”窗格。
在“数据资源管理器”** 中，展开“cosmicworks”** 数据库节点，然后在“NoSQL API”** 导航树中展开新“products”** 容器节点。
选择“Items”节点。选择容器中的唯一项，然后观察项的 name 和 price 属性的值。

属性值

名称 Road Saddle

价格 45.99 美元

📝 此时，自从你创建了这个项后，这些值不应发生更改。在本练习中，你将更改这些值。
返回到 Visual Studio Code。返回到 script.cs 代码文件的“编辑器”选项卡。

属性	值
名称	Road Saddle
价格	45.99 美元

删除以下代码行：

 Console.WriteLine($"[{saddle.id}]\t{saddle.name} ({saddle.price:C})");

通过将 price 属性的值设置为 32.55 来更改 saddle 变量：
```
 saddle.price = 32.55d;
```
通过将 name 属性的值设置为 Road LL Saddle，再次修改 saddle 变量：
```
 saddle.name = "Road LL Saddle";
```
异步调用 container 变量的泛型 UpsertItemAsync<> 方法，将 saddle 变量作为方法参数传入，并使用 Product 作为泛型类型：
```
 await container.UpsertItemAsync<Product>(saddle);
```

完成后，代码文件现在应包含：

 using System;
 using Microsoft.Azure.Cosmos;

 string endpoint = "<cosmos-endpoint>";
 string key = "<cosmos-key>";

 CosmosClient client = new CosmosClient(endpoint, key);
    
 Database database = await client.CreateDatabaseIfNotExistsAsync("cosmicworks");
    
 Container container = await database.CreateContainerIfNotExistsAsync("products", "/categoryId", 400);

 string id = "706cd7c6-db8b-41f9-aea2-0e0c7e8eb009";

 string categoryId = "9603ca6c-9e28-4a02-9194-51cdb7fea816";
 PartitionKey partitionKey = new (categoryId);

 Product saddle = await container.ReadItemAsync<Product>(id, partitionKey);

 saddle.price = 32.55d;
 saddle.name = "Road LL Saddle";
    
 await container.UpsertItemAsync<Product>(saddle);

保存 script.cs 代码文件。
在 Visual Studio Code 中，打开 06-sdk-crud 文件夹的上下文菜单，然后选择“在集成终端中打开”以打开一个新的终端实例。
使用 dotnet run 命令生成并运行项目：
```
 dotnet run
```
关闭集成终端。
返回 Web 浏览器窗口或选项卡。
在 Azure Cosmos DB 帐户资源中，导航到“数据资源管理器”窗格。
在“数据资源管理器”** 中，展开“cosmicworks”** 数据库节点，然后在“NoSQL API”** 导航树中展开新“products”** 容器节点。
选择“Items”节点。选择容器中的唯一项，然后观察项的 name 和 price 属性的值。

属性值

名称 Road LL Saddle

价格 32.55 美元

📝 此时，自从你观察到这个项后，这些值应发生更改。
返回到 Visual Studio Code。返回到 script.cs 代码文件的“编辑器”选项卡。

属性	值
名称	Road LL Saddle
价格	32.55 美元

删除以下代码行：

 Product saddle = await container.ReadItemAsync<Product>(id, partitionKey);

 saddle.price = 32.55d;
 saddle.name = "Road LL Saddle";
    
 await container.UpsertItemAsync<Product>(saddle);

异步调用 container 变量的泛型 DeleteItemAsync<> 方法，将 id 和 partitionkey 变量作为方法参数传入，并使用 Product 作为泛型类型：
```
 await container.DeleteItemAsync<Product>(id, partitionKey);
```
保存 script.cs 代码文件。
在 Visual Studio Code 中，打开 06-sdk-crud 文件夹的上下文菜单，然后选择“在集成终端中打开”以打开一个新的终端实例。
使用 dotnet run 命令生成并运行项目：
```
 dotnet run
```
关闭集成终端。
返回 Web 浏览器窗口或选项卡。
在 Azure Cosmos DB 帐户资源中，导航到“数据资源管理器”窗格。
在“数据资源管理器”** 中，展开“cosmicworks”** 数据库节点，然后在“NoSQL API”** 导航树中展开新“products”** 容器节点。
选择“Items”节点。应会看到项列表现在为空。
关闭 Web 浏览器窗口或选项卡。
关闭 Visual Studio Code。