快速入门：使用 Azure Cosmos DB API for MongoDB 生成 .NET Web API

适用对象： MongoDB

本快速入门演示如何：

1. 创建 Azure Cosmos DB API for MongoDB 帐户
2. 使用 MongoDB .NET 驱动程序生成产品目录 Web API
3. 导入示例数据

运行示例应用的先决条件

• 具有 Azure 开发工作负载的最新 Visual Studio。 一开始可以使用免费的 Visual Studio Community IDE。 在安装 Visual Studio 的过程中，请启用“Azure 开发”工作负载。

• .NET 5.0

• 具有活动订阅的 Azure 帐户。 创建 Azure 帐户。

创建数据库帐户

1. 在新浏览器窗口中，登录到 Azure 门户。

2. 在左侧菜单中，选择“创建资源”。

   

3. 在“新建”页上，选择“数据库”“Azure Cosmos DB”。

   

4. 在“Azure Cosmos DB”页上，选择“创建”。

5. 在“创建 Azure Cosmos DB 帐户”页中，输入新 Azure Cosmos DB 帐户的设置。

   设置	值	说明
   订阅	订阅名称	选择要用于此 Azure Cosmos DB 帐户的 Azure 订阅。
   资源组	资源组名称	选择一个资源组，或者选择“新建”，然后输入新资源组的唯一名称。
   帐户名	输入唯一的名称	输入标识此 Azure Cosmos DB 帐户的唯一名称。 帐户 URI 将是追加到唯一帐户名称的“mongo.cosmos.azure.cn” 。 帐户名称只能使用小写字母、数字及连字符 (-)，必须为 3 到 44 个字符长。
   位置	离用户最近的区域	选择用于托管 Azure Cosmos DB 帐户的地理位置。 使用离用户最近的位置，使他们能够以最快的速度访问数据。
   容量模式	预配吞吐量或无服务器	选择“预配吞吐量”以在预配吞吐量模式下创建帐户。 选择“无服务器”以在无服务器模式下创建帐户。 注意：无服务器帐户仅支持 API for MongoDB 版本 4.2、4.0 和 3.6。 选择版本 3.2 将强制帐户处于配置的吞吐量模式。
   应用 Azure Cosmos DB 免费层折扣	“应用”或“不应用”	使用 Azure Cosmos DB 免费层，你将在帐户中获得每秒前 1000 RU 的免费吞吐量和 25 GB 的免费存储。 了解免费层的详细信息。
   版本	选择所需的服务器版本	Azure Cosmos DB for MongoDB 与服务器版本 4.2、4.0、3.6 和 3.2 兼容。 创建帐户后，可以对其进行升级或降级。

   注意

   每个 Azure 订阅最多可以有一个免费层 Azure Cosmos DB 帐户，并且你必须在创建帐户时选择加入使用。 如果看不到用于应用免费层折扣的选项，这意味着订阅中的另一个帐户已启用免费层。

   

6. 在“全局分发”选项卡中，配置以下详细信息。 对于本快速入门，可以保留默认值：

   设置	值	说明
   异地冗余	禁用	通过将你的区域与某个配对区域进行配对来启用或禁用帐户的多区域分发。 稍后可以将更多区域添加到帐户。
   多区域写入	禁用	借助多区域写入功能，可以利用全中国的数据库和容器的预配吞吐量。

   注意

   如果选择“无服务器”作为“容量模式”，则以下选项不可用 ：

   • 应用免费层折扣
   • 异地冗余
   • 多区域写入

7. （可选）可以在以下选项卡中配置其他详细信息：

   • 网络 - 配置来自虚拟网络的访问。
   • 备份策略- 配置定期或连续备份策略。
   • 加密 - 使用服务管理的密钥或客户管理的密钥。
   • 标记 - 标记是名称/值对，通过将相同的标记应用到多个资源和资源组，可以对资源进行分类并查看合并的账单。

8. 选择“查看 + 创建”。

9. 创建帐户需要几分钟时间。 等待门户中显示“祝贺你! Azure Cosmos DB for MongoDB 帐户已准备就绪”页面。

   

了解对象模型

在继续生成应用程序之前，先研究 API for MongoDB 中资源的层次结构以及用于创建和访问这些资源的对象模型。 API for MongoDB 按以下顺序创建资源：

• Azure Cosmos DB API for MongoDB 帐户
• 数据库
• 集合
• 文档

若要详细了解实体的层次结构，请参阅 Azure Cosmos DB 资源模型一文。

安装示例应用模板

本示例是一个 dotnet 项目模板，可以安装该模板来创建本地副本。 在命令窗口中运行以下命令：

mkdir "C:\cosmos-samples"
cd "C:\cosmos-samples"
dotnet new -i Microsoft.Azure.Cosmos.Templates
dotnet new cosmosmongo-webapi

前面的命令：

1. 为示例创建 C:\cosmos-samples 目录。 选择适合你的操作系统的文件夹。
2. 将当前目录更改为 C:\cosmos-samples 文件夹。
3. 安装项目模板，通过 dotnet CLI 使此模板在多区域中可用。
4. 使用项目模板创建本地示例应用。

如果不想使用 dotnet CLI，也可以下载 ZIP 文件格式的项目模板。 此示例位于 Templates/APIForMongoDBQuickstart-WebAPI 文件夹中。

查看代码

可选择执行以下步骤。 如果有意了解如何使用代码创建数据库资源，请查看以下代码片段。 否则，请跳到更新应用程序设置。

设置连接

以下代码片段来自 Services/MongoService.cs 文件。

• 以下类表示客户端，并由 .NET Framework 注入到使用它的服务中：

  public class MongoService
  {
      private static MongoClient _client;
  
      public MongoService(IDatabaseSettings settings)
      {
          _client = new MongoClient(settings.MongoConnectionString);
      }
  
      public MongoClient GetClient()
      {
          return _client;
      }
  }
  

设置产品目录数据服务

以下代码片段来自 Services/ProductService.cs 文件。

• 以下代码将检索数据库和集合，如果不存在，则进行创建：

  private readonly IMongoCollection<Product> _products;        
  
  public ProductService(MongoService mongo, IDatabaseSettings settings)
  {
      var db = mongo.GetClient().GetDatabase(settings.DatabaseName);
      _products = db.GetCollection<Product>(settings.ProductCollectionName);
  }
  

• 以下代码将按唯一产品标识符 SKU 检索文档：

  public Task<Product> GetBySkuAsync(string sku)
  {
      return _products.Find(p => p.Sku == sku).FirstOrDefaultAsync();
  }
  

• 以下代码将创建产品并将其插入到集合中：

  public Task CreateAsync(Product product)
  {
      _products.InsertOneAsync(product);
  }
  

• 以下代码将查找并更新产品：

  public Task<Product> UpdateAsync(Product update)
  {
      return _products.FindOneAndReplaceAsync(
          Builders<Product>.Filter.Eq(p => p.Sku, update.Sku), 
          update, 
          new FindOneAndReplaceOptions<Product> { ReturnDocument = ReturnDocument.After });
  }
  

  同样，可以使用 collection.DeleteOne() 方法来删除文档。

更新应用程序设置

从 Azure 门户复制连接字符串信息：

1. 在 Azure 门户中选择 Cosmos DB 帐户，在左侧导航栏中，选择“连接字符串”，然后选择“读写密钥” 。 在后续步骤中，你将使用屏幕右侧的复制按钮将主连接字符串复制到 appsettings.json 文件中。

2. 打开 appsettings.json 文件。

3. 从门户中复制主连接字符串值（使用复制按钮），并将其设置为 appsettings.json 文件中 DatabaseSettings.MongoConnectionString 属性的值。

4. 查看 appsettings.json 文件的 DatabaseSettings.DatabaseName 属性中的“数据库名称”值。

5. 查看 appsettings.json 文件的 DatabaseSettings.ProductCollectionName 属性中的“集合名称”值。

   警告

   切勿将密码或其他敏感数据签入源代码。

现在，你已在应用中更新了全部所需信息，它可以与 Cosmos DB 进行通信。

加载示例数据

下载mongoimport，这是一种 CLI 工具，可轻松导入少量 JSON、CSV 或 TSV 数据。 我们将使用 mongoimport 加载此项目的 Data 文件夹中提供的示例产品数据。

从 Azure 门户中复制连接信息，并在下面的命令中输入该信息：

mongoimport --host <HOST>:<PORT> -u <USERNAME> -p <PASSWORD> --db cosmicworks --collection products --ssl --jsonArray --writeConcern="{w:0}" --file Data/products.json

1. 在 Azure 门户中，选择 Azure Cosmos DB API for MongoDB 帐户，在左侧导航栏中，选择“连接字符串”，然后选择“读写密钥” 。

2. 从门户中复制“主机”值（使用复制按钮）并输入它来代替 <HOST>。

3. 从门户中复制“端口”值（使用复制按钮）并输入它来代替 <PORT>。

4. 从门户中复制“用户名”值（使用复制按钮）并输入它来代替 <USERNAME>。

5. 从门户中复制“密码”值（使用复制按钮）并输入它来代替 <PASSWORD>。

6. 查看“数据库名称”值，如果你创建的不是 cosmicworks，则更新该值。

7. 查看“集合名称”值，如果你创建的不是 products，则更新该值。

   注意

   若要跳过此步骤，可以使用作为此 Web API 项目的一部分提供的 POST 终结点创建具有正确架构的文档。

运行应用

在 Visual Studio 中，选择 CTRL + F5 运行应用。 默认浏览器随应用一起启动。

如果你喜欢使用 CLI，请在命令窗口中运行以下命令，以启动示例应用。 此命令还将安装项目依赖项并构建项目，但不会自动启动浏览器。

dotnet run

应用程序运行后，导航到 https://localhost:5001/swagger/index.html，以查看 Web API 的 Swagger 文档并提交示例请求。

选择要测试的 API，然后选择“试用”。

输入任何必要的参数并选择“执行”。

清理资源

执行完应用和 Azure Cosmos DB 帐户的操作以后，可以删除所创建的 Azure 资源，以免产生更多费用。 若要删除资源，请执行以下操作：

1. 在 Azure 门户的“搜索”栏中，搜索并选择“资源组” 。

2. 从列表中选择为本快速入门创建的资源组。

   

3. 在资源组“概览”页上，选择“删除资源组” 。

   

4. 在下一窗口中输入要删除的资源组的名称，然后选择“删除” 。

后续步骤

本快速入门介绍了如何创建 API for MongoDB 帐户、使用代码创建数据库和集合，以及运行 Web API 应用。 你现在可以向数据库导入更多数据。

正在尝试为迁移到 Azure Cosmos DB 进行容量计划？ 可以使用有关现有数据库群集的信息进行容量规划。

• 如果只知道现有数据库群集中的 vCore 和服务器数量，请阅读使用 vCore 或 vCPU 估算请求单位
• 若知道当前数据库工作负载的典型请求速率，请阅读使用 Azure Cosmos DB 容量计划工具估算请求单位