教程：将 Node.js Web 应用与 Azure Cosmos DB for MongoDB (vCore) 连接

适用对象： MongoDB vCore

在本教程中，请生成一个 Node.js Web 应用程序，以连接到 vCore 体系结构中的 Azure Cosmos DB for MongoDB。 MongoDB、Express、React.js、Node.js (MERN) 堆栈是用于生成许多新式 Web 应用程序的常用技术集合。 使用 Azure Cosmos DB for MongoDB (vCore)，可以生成新的 Web 应用程序，或使用你已熟悉的 MongoDB 驱动程序迁移现有应用程序。 在本教程中，你将了解：

先决条件

若要完成本教程，需要以下各资源：

• 现有的 vCore 群集。
• 一个 GitHub 帐户。
  • GitHub 为所有用户提供免费的 Codespaces 小时数。

配置开发环境

提供开发容器环境，其中包含完成此项目中每个练习所需的所有依赖项。 可以在 GitHub Codespaces 中运行开发容器，也可以使用 Visual Studio Code 在本地运行。

使用 MongoDB 容器测试 MERN 应用程序的 API

首先使用本地 MongoDB 容器运行示例应用程序的 API，以验证应用程序是否正常工作。

1. 使用 Docker 运行 MongoDB 容器，然后发布典型的 MongoDB 端口（27017）。

   docker pull mongo:6.0
   
   docker run --detach --publish 27017:27017 mongo:6.0
   

2. 在侧栏中，选择 MongoDB 扩展。

   

3. 使用连接字符串 mongodb://localhost 向 MongoDB 扩展添加新连接。

   

4. 连接成功后，打开 data/products.mongodb 操场文件。

5. 选择“全部运行”图标以执行脚本。

   

6. 操场运行应在本地 MongoDB 集合中生成文档列表。 下面是截断的输出示例。

   [
     {
       "_id": { "$oid": "640a146e89286b79b6628eef" },
       "name": "Confira Watch",
       "category": "watches",
       "price": 105
     },
     {
       "_id": { "$oid": "640a146e89286b79b6628ef0" },
       "name": "Diannis Watch",
       "category": "watches",
       "price": 98,
       "sale": true
     },
     ...
   ]
   

   注意

   对象 ID（_id）是随机生成的，将不同于此截断的示例输出。

7. 在 server/ 目录中，创建新的 .env 文件。

8. 在 server/.env 文件中，为此值添加环境变量：

   环境变量	Value
   CONNECTION_STRING	Azure Cosmos DB for MongoDB (vCore) 群集的连接字符串。 现在，请使用 mongodb://localhost:27017?directConnection=true。

   CONNECTION_STRING=mongodb://localhost:27017?directConnection=true
   

9. 将终端的上下文更改为 server/ 文件夹。

   cd server
   

10. 从 Node 包管理器 (npm) 安装依赖项。

    npm install
    

11. 启动 Node.js 和 Express 应用程序。

    npm start
    

12. API 会自动打开浏览器窗口，以验证它是否返回一组产品文档。

13. 关闭额外的浏览器选项卡/窗口。

14. 关闭终端。

使用 Azure Cosmos DB for MongoDB (vCore) 群集测试 MERN 应用程序

现在，让我们验证应用程序是否与 Azure Cosmos DB for MongoDB (vCore) 无缝配合工作。 对于此任务，可通过 MongoDB shell 使用种子数据填充预先存在的群集，然后更新 API 的连接字符串。

1. 登录到 Azure 门户 (https://portal.azure.cn)。

2. 导航到现有 Azure Cosmos DB for MongoDB (vCore) 群集页。

3. 从 Azure Cosmos DB for MongoDB (vCore) 群集页中，选择“连接字符串”导航菜单选项。

   

4. 记录“连接字符串”字段的值。

   

   重要

   门户中的连接字符串不包括用户名和密码值。 必须将 <user> 和 <password> 占位符替换为最初创建群集时使用的凭据。

5. 返回到集成开发环境 (IDE)，打开一个新终端。

6. 使用 mongosh 命令和之前记录的连接字符串启动 MongoDB Shell。 确保将 <user> 和 <password> 占位符替换为最初创建群集时使用的凭据。

   mongosh "<mongodb-cluster-connection-string>"
   

   注意

   可能需要对连接字符串的特定值进行编码。 在此示例中，群集的名称为 msdocs-cosmos-tutorial，用户名为 clusteradmin，密码为 P@ssw.rd。 在密码中，需要使用 %40 对 @ 字符进行编码。 此处提供了一个示例连接字符串，其中包含正确的密码编码。

   CONNECTION_STRING=mongodb+srv://clusteradmin:P%40ssw.rd@msdocs-cosmos-tutorial.mongocluster.cosmos.azure.cn/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000
   

7. 在 shell 中运行以下命令以创建数据库、创建集合，并使用初学者数据设定种子。

use('cosmicworks');

db.products.drop();

db.products.insertMany([
  { name: "Confira Watch", category: "watches", price: 105.00 },
  { name: "Diannis Watch", category: "watches", price: 98.00, sale: true },
  { name: "Sterse Gloves", category: "gloves", price: 42.00 },
  { name: "Peache Sunglasses", category: "eyewear", price: 32.00, sale: false, sizes: [ "S", "M", "L" ] },
  { name: "Icento Pack", category: "bags", price: 58.00 },
  { name: "Iroowl Bracelet", category: "watches", price: 66.00 },
  { name: "Glaark Bag", category: "bags", price: 56.00, sale: true },
  { name: "Windry Mittens", category: "gloves", price: 35.00 },
  { name: "Tuvila Hat", category: "hats", price: 120.00 },
  { name: "Klinto Hat", category: "hats", subcategory: "hats-beanies", price: 65.00 }
]);

db.products.find({});

1. 命令应生成本地 MongoDB 集合中的文档列表。 下面是截断的输出示例。

   [
     {
       "_id": { "$oid": "640a146e89286b79b6628eef" },
       "name": "Confira Watch",
       "category": "watches",
       "price": 105
     },
     {
       "_id": { "$oid": "640a146e89286b79b6628ef0" },
       "name": "Diannis Watch",
       "category": "watches",
       "price": 98,
       "sale": true
     },
     ...
   ]
   

   注意

   对象 ID（_id）是随机生成的，将不同于此截断的示例输出。

2. 退出 MongoDB shell。

   exit
   

3. 在“client/”目录中，创建新的 .env 文件。

4. 在 client/.env 文件中，为此值添加环境变量：

   环境变量	Value
   CONNECTION_STRING	Azure Cosmos DB for MongoDB (vCore) 群集的连接字符串。 使用与 mongo shell 一起使用的相同连接字符串。

   CONNECTION_STRING=<your-connection-string>
   

5. 验证应用程序是否正在使用数据库服务，其方法是将终端的上下文更改为 server/ 文件夹，从 Node 包管理器 (npm) 安装依赖项，然后启动应用程序。

   cd server
   
   npm install
   
   npm start
   

6. API 会自动打开浏览器窗口，以验证它是否返回一组产品文档。

7. 关闭额外的浏览器选项卡/窗口。 然后，关闭终端。

将 MERN 应用程序部署到 Azure 应用服务

将服务和客户端部署到 Azure 应用服务，以证明应用程序端到端工作。 使用 Web 应用中的机密存储带有凭据和 API 终结点的环境变量。

1. 在集成开发环境中 (IDE) 中，打开一个新终端。

2. 为名为 resourceGroupName 的预先存在的资源组的名称创建 Shell 变量。

   # Variable for resource group name
   resourceGroupName="<existing-resource-group>"
   

3. 为名为 serverAppName 和 clientAppName 的两个 Web 应用创建 shell 变量。

   # Variable for randomnly generated suffix
   let suffix=$RANDOM*$RANDOM
   
   # Variable for web app names with a randomnly generated suffix
   serverAppName="server-app-$suffix"
   clientAppName="client-app-$suffix"
   

4. 如果尚未登录，请使用 az login --use-device-code 命令登录到 Azure CLI。

5. 将当前工作目录更改为 server/ 路径。

   cd server
   

6. 使用 az webapp up 为 MERN 应用程序的服务器组件创建新的 Web 应用。

   az webapp up \
       --resource-group $resourceGroupName \
       --name $serverAppName \
       --sku F1 \
       --runtime "NODE|18-lts"
   

7. 使用 az webapp config connection-string set 为名为 CONNECTION_STRING 的服务器 Web 应用创建新的连接字符串设置。 对前面在本教程中用于 MongoDB shell 和 .env 文件的连接字符串使用相同的值。

   az webapp config connection-string set \
       --resource-group $resourceGroupName \
       --name $serverAppName \
       --connection-string-type custom \
       --settings "CONNECTION_STRING=<mongodb-connection-string>"
   

8. 使用 az webapp show 获取服务器 Web 应用的 URI，并将其存储在名为 serverUri 的 shell 变量中。

   serverUri=$(az webapp show \
       --resource-group $resourceGroupName \
       --name $serverAppName \
       --query hostNames[0] \
       --output tsv)
   

9. 将 NuGet 中的 open-cli 包和命令与 npx 一起使用，以使用服务器 Web 应用的 URI 打开浏览器窗口。 验证服务器应用是否从 MongoDB (vCore) 群集返回 JSON 数组数据。

   npx open-cli "https://$serverUri/products" --yes
   

   提示

   有时，部署可以异步完成。 如果看不到预期内容，请再等待一分钟，然后刷新浏览器窗口。

10. 将工作目录更改为 client/ 路径。

    cd ../client
    

11. 使用 az webapp up 为 MERN 应用程序的客户端组件创建新的 Web 应用。

    az webapp up \
        --resource-group $resourceGroupName \
        --name $clientAppName \
        --sku F1 \
        --runtime "NODE|18-lts"
    

12. 使用 az webapp config appsettings set 为名为 REACT_APP_API_ENDPOINT 的客户端 Web 应用创建新的应用设置。 使用存储在 serverUri shell 变量中的服务器 API 终结点。

    az webapp config appsettings set \
        --resource-group $resourceGroupName \
        --name $clientAppName \
        --settings "REACT_APP_API_ENDPOINT=https://$serverUri"
    

13. 使用 az webapp show 获取客户端 Web 应用的 URI，并将其存储在名为 clientUri 的 shell 变量中。

    clientUri=$(az webapp show \
        --resource-group $resourceGroupName \
        --name $clientAppName \
        --query hostNames[0] \
        --output tsv)
    

14. 将 NuGet 中的 open-cli 包和命令与 npx 一起使用，以使用客户端 Web 应用的 URI 打开浏览器窗口。 验证客户端应用是否正在呈现来自服务器应用的 API 的数据。

    npx open-cli "https://$clientUri" --yes
    

    提示

    有时，部署可以异步完成。 如果看不到预期内容，请再等待一分钟，然后刷新浏览器窗口。

15. 关闭终端。

清理资源

在自己的订阅中操作时，最好在项目结束时删除不再需要的资源。 持续运行资源可能会产生费用。 可以逐个删除资源，也可以删除资源组以删除整个资源集。

1. 要删除整个资源组，请使用 az group delete。

   az group delete \
       --name $resourceGroupName \
       --yes
   

2. 验证是否已使用 az group list 删除该资源组。

   az group list
   

清理开发环境

你可能还想要清理开发环境或将其返回到其典型状态。

下一步

现在，你已为 MongoDB (vCore) 群集生成第一个应用程序，请了解如何将数据迁移到 Azure Cosmos DB。