使用 Azure Cosmos DB for NoSQL SDK 执行查询

利用最新版本的用于 Azure Cosmos DB for NoSQL 的 .NET SDK 可以更容易地查询容器，并使用 C# 中的最新最佳做法和语言功能异步遍历结果集。

此库的特殊功能可以让你更轻松地使用 [https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.cosmos.feediterator?view=azure-dotnet] 查询 Azure Cosmos DB。

在此实验室中，你将使用异步流来遍历从 Azure Cosmos DB for NoSQL 返回的大型结果集。你将使用 .NET SDK 查询和遍历结果。

准备开发环境

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

启动 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。

使用数据为 Azure Cosmos DB for NoSQL 帐户设定种子

cosmicworks 命令行工具将示例数据部署到任何 Azure Cosmos DB for NoSQL 帐户。该工具是开源工具，可通过 NuGet 获得。将此工具安装到 Azure Cloud Shell，然后使用它来设定数据库种子。

在 Visual Studio Code 中，打开“终端”菜单，然后选择“新建终端”以打开新的终端实例。
在计算机上安装可全局使用的 cosmicworks 命令行工具。
```
 dotnet tool install cosmicworks --global --version 1.*
```
💡 此命令可能需要几分钟时间才能完成。如果你过去已经安装了此工具的最新版本，此命令将输出警告消息（*工具 “cosmicworks” 已安装）。

使用以下命令行选项运行 cosmicworks 以设置 Azure Cosmos DB 种子帐户：

选项	值
–endpoint	之前在本实验室中复制的终结点值
–key	之前在本实验室中复制的键值
–datasets	product

 cosmicworks --endpoint <cosmos-endpoint> --key <cosmos-key> --datasets product

📝 例如，如果终结点为：https://dp420.documents.azure.com:443/，密钥为：fDR2ci9QgkdkvERTQ==，则命令为：cosmicworks --endpoint https://dp420.documents.azure.com:443/ --key fDR2ci9QgkdkvERTQ== --datasets product

等待 cosmicworks 命令完成对帐户的数据库、容器和项的填充。
关闭集成终端。

使用 SDK 来遍历 SQL 查询的结果

现在你将使用一个异步流在 Azure Cosmos DB 的分页结果上创建一个简单易懂的 foreach 循环。在后台，SDK 将管理源迭代器，确保正确调用后续请求。

在 Visual Studio Code 的“资源管理器”窗格中，浏览到 09-execute-query-sdk 文件夹。
打开 product.cs 代码文件。
观察 Product 类及其对应的属性。具体而言，此实验室将使用 id、name 和 price 属性。
返回到 Visual Studio Code 的“资源管理器”窗格，打开 script.cs 代码文件。
更新名为 endpoint 的现有变量，将其值设置为前面创建的 Azure Cosmos DB 帐户的终结点。
```
 string endpoint = "<cosmos-endpoint>";
```
📝 例如，如果终结点为：https://dp420.documents.azure.com:443/，则 C# 语句将为：string endpoint = “https://dp420.documents.azure.com:443/”;。
更新名为 key 的现有变量，将其值设置为前面创建的 Azure Cosmos DB 帐户的键。
```
 string key = "<cosmos-key>";
```
📝 例如，如果键为：fDR2ci9QgkdkvERTQ==，则 C# 语句应为：string key = “fDR2ci9QgkdkvERTQ==”;。
****** 让我们将一些附加代码追加到 script.cs 文件的末尾，创建一个名为 sql 且类型为 string 的新变量，使其值为 SELECT * FROM products p：
```
 string sql = "SELECT * FROM products p";
```
创建一个 QueryDefinition 类型的新变量，并传入 sql 变量作为构造函数的参数：
```
 QueryDefinition query = new (sql);
```
创建一个新的 while** 循环，方法是通过调用 CosmosContainer 类的泛型 GetItemQueryIterator 方法，并传入 query** 变量作为参数，然后遍历结果：
```
 using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
     queryDefinition: query
 );

 while (feed.HasMoreResults)
 {
 }
```

在 while** 循环中，异步读取下一结果，使用内置的 Console.WriteLine** 静态方法格式化并输出 product** 变量的 id、name** 和 price** 属性：

 FeedResponse<Product> response = await feed.ReadNextAsync();
 foreach (Product product in response)
 {
     Console.WriteLine($"[{product.id}]\t{product.name,35}\t{product.price,15:C}");
 }

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

 using System;
 using Microsoft.Azure.Cosmos;

 string endpoint = "<cosmos-endpoint>";

 string key = "<cosmos-key>";

 CosmosClient client = new (endpoint, key);

 Database database = await client.CreateDatabaseIfNotExistsAsync("cosmicworks");

 Container container = await database.CreateContainerIfNotExistsAsync("products", "/categoryId");

 string sql = "SELECT * FROM products p";
 QueryDefinition query = new (sql);

 using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
     queryDefinition: query
 );

 while (feed.HasMoreResults)
 {
     FeedResponse<Product> response = await feed.ReadNextAsync();
     foreach (Product product in response)
     {
         Console.WriteLine($"[{product.id}]\t{product.name,35}\t{product.price,15:C}");
     }
 }

保存 script.cs 文件。
在 Visual Studio Code 中，打开 09-execute-query-sdk 文件夹的上下文菜单，然后选择“在集成终端中打开”以打开一个新的终端实例。
使用以下命令从 NuGet 添加 [Microsoft.Azure.Cosmos][nuget.org/packages/microsoft.azure.cosmos/3.22.1] 包：
```
 dotnet add package Microsoft.Azure.Cosmos --version 3.22.1
```
使用 dotnet run 命令生成并运行项目：
```
 dotnet run
```
该脚本现在将输出容器中的每一个产品
关闭集成终端。
关闭 Visual Studio Code。