快速入门：将 Azure DocumentDB 与用于 Node.js的 MongoDB 驱动程序配合使用

在本快速入门中，你将使用 Node.js创建基本的 Azure DocumentDB 应用程序。 Azure DocumentDB 是一种NoSQL数据存储，允许应用程序将文档存储在云中，并使用官方 MongoDB 驱动程序访问文档。本指南演示如何使用 Node.js在 Azure DocumentDB 群集中创建文档和执行基本任务。

API 参考 | 源代码 | 包（npm）

先决条件

一份 Azure 订阅。如果没有 Azure 订阅，请创建一个试用帐户。

Node.js 22 或更高版本

创建 Azure DocumentDB 群集

若要开始，首先需要创建一个 Azure DocumentDB 群集，该群集充当存储和管理NoSQL数据的基础。

登录到 Azure 门户（https://portal.azure.cn）。
在Azure门户菜单或 Home 页面中，选择创建资源。
在 New 页上，搜索并选择 Azure DocumentDB。
在 Create Azure DocumentDB 群集页上，并在 Basics 节中，在 Cluster 层节中选择 Configure 选项。
在“ 缩放 ”页上，配置这些选项，然后选择“ 保存 ”以将更改保存到群集层。

价值

群集层 M30 tier, 2 vCore, 8-GiB RAM

每个分片的存储量 128 GiB

	价值
群集层	`M30 tier, 2 vCore, 8-GiB RAM`
每个分片的存储量	`128 GiB`

返回 “基本信息 ”部分，配置以下选项：

	价值
Subscription	选择Azure订阅
资源组	创建新的资源组，或选择现有资源组
群集名称	提供一个全局唯一的名称
位置	为订阅选择受支持的Azure区域
MongoDB 版本	选择 `8.0`
管理员用户名	创建用户名以以用户管理员身份访问群集
密码	使用与用户名关联的唯一密码

显示群集参数的屏幕截图。

小窍门

记录用于用户名和密码的值。本指南稍后会使用这些值。有关有效值的详细信息，请参阅群集限制。

选择下一步：网络。
在“网络”选项卡上的“防火墙规则”部分中，配置以下选项：

价值

连接方法 Public access

允许Azure中的服务和资源公开访问此群集 已启用
为当前客户端设备添加防火墙规则，通过选择 “+ 添加当前客户端 IP 地址”来授予对群集的访问权限。

小窍门

在许多企业环境中，由于 VPN 或其他企业网络的设置，开发人员计算机 IP 地址会隐藏。在这些情况下，可以通过将 IP 地址范围添加 0.0.0.0 - 255.255.255.255 为防火墙规则来暂时允许访问所有 IP 地址。将此防火墙规则暂时用作连接测试和开发的一部分。
选择“查看 + 创建”。
查看提供的设置，然后选择“创建”。创建群集需要几分钟时间。等待资源部署完成。
最后，选择转到资源导航到门户中的 Azure DocumentDB 群集。

	价值
连接方法	`Public access`
允许Azure中的服务和资源公开访问此群集	已启用

显示 goto 资源选项的屏幕截图。

获取群集凭据

获取用于连接到群集的凭据。

在群集页上，在资源菜单中选择 “连接字符串 ”选项。
在 “连接字符串 ”部分中，复制或记录 “连接字符串 ”字段中的值。

显示连接字符串选项的屏幕截图。

重要

门户中的连接字符串不包含密码值。必须将占位符替换为 <password> 在创建群集时输入的凭据，或以交互方式输入密码。

初始化项目

在当前目录中创建新的 Node.js 项目。

从空目录中开始。
在当前目录中打开终端。
初始化 Node.js 项目。
```
npm init -y
```
安装 TypeScript 并初始化 TypeScript 配置（TypeScript 支持可选）。
```
npm install -D typescript @types/node
npx tsc --init
```

安装客户端库

客户端库可通过 npm 作为 mongodb 包使用。

使用 npm 安装 MongoDB Node.js 驱动程序。
```
npm install mongodb
```
打开并查看 package.json 文件，以验证包条目是否存在。

将所需的模块导入应用程序代码：

import { MongoClient, Db, Collection, Document } from 'mongodb';

const { MongoClient } = require('mongodb');

对象模型

Name	Description
`MongoClient`	用于连接到 MongoDB 的类型。
`Db`	表示群集中的数据库。
`Collection<Document>`	表示群集中数据库内的集合。

此应用程序中的代码连接到名为adventureworks的数据库和名为products的集合。该 products 集合包含每个产品的名称、类别、数量、唯一标识符和销售标志等详细信息。此处的代码示例在处理集合时执行最常见的作。

对客户端进行身份验证

首先，使用基本的连接字符串连接到客户端。

创建主函数并设置连接字符串。替换 <your-cluster-name>、<your-username> 和 <your-password> 为实际群集信息。

async function main(): Promise<void> {
    // Connection string for Azure DocumentDB cluster
    const connectionString = "mongodb+srv://<your-username>:<your-password>@<your-cluster-name>.global.mongocluster.cosmos.azure.cn/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000";

    // Create a new client and connect to the server
    const client = new MongoClient(connectionString);

async function main() {
    // Connection string for Azure DocumentDB cluster
    const connectionString = "mongodb+srv://<your-username>:<your-password>@<your-cluster-name>.global.mongocluster.cosmos.azure.cn/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000";

    // Create a new client and connect to the server
    const client = new MongoClient(connectionString);

连接到 MongoDB 客户端并验证连接。

    try {
        // Connect to the MongoDB cluster
        await client.connect();

        // Ping the server to verify connection
        await client.db("admin").command({ ping: 1 });
        console.log("Successfully connected and pinged Azure DocumentDB");

    try {
        // Connect to the MongoDB cluster
        await client.connect();

        // Ping the server to verify connection
        await client.db("admin").command({ ping: 1 });
        console.log("Successfully connected and pinged Azure DocumentDB");

获取集合

现在获取数据库和集合。如果数据库和集合尚不存在，请使用驱动程序自动创建它。

获取对数据库的引用。

        // Get database reference
        const database: Db = client.db("adventureworks");
        console.log(`Connected to database: ${database.databaseName}`);

        // Get database reference
        const database = client.db("adventureworks");
        console.log(`Connected to database: ${database.databaseName}`);

获取对数据库中集合的引用。

        // Get collection reference
        const collection: Collection<Document> = database.collection("products");
        console.log("Connected to collection: products");

        // Get collection reference
        const collection = database.collection("products");
        console.log("Connected to collection: products");

创建文档

然后，在集合中创建几个新文档。向上插入文档，以确保它已使用同一唯一标识符替换任何现有文档。

创建示例产品文档。

        // Create sample products
        interface Product {
            _id: string;
            name: string;
            category: string;
            quantity: number;
            price: number;
            sale: boolean;
        }

        const products: Product[] = [
            {
                _id: "00000000-0000-0000-0000-000000004018",
                name: "Windry Mittens",
                category: "apparel-accessories-gloves-and-mittens",
                quantity: 121,
                price: 35.00,
                sale: false,
            },
            {
                _id: "00000000-0000-0000-0000-000000004318",
                name: "Niborio Tent",
                category: "gear-camp-tents",
                quantity: 140,
                price: 420.00,
                sale: true,
            }
        ];

        // Create sample products
        const products = [
            {
                _id: "00000000-0000-0000-0000-000000004018",
                name: "Windry Mittens",
                category: "apparel-accessories-gloves-and-mittens",
                quantity: 121,
                price: 35.00,
                sale: false,
            },
            {
                _id: "00000000-0000-0000-0000-000000004318",
                name: "Niborio Tent",
                category: "gear-camp-tents",
                quantity: 140,
                price: 420.00,
                sale: true,
            }
        ];

通过upsert操作插入文档。

        // Insert documents with upsert
        for (const product of products) {
            const filter = { _id: product._id };
            const options = { upsert: true };

            await collection.replaceOne(filter, product, options);
            console.log(`Upserted product: ${product.name}`);
        }

        // Insert documents with upsert
        for (const product of products) {
            const filter = { _id: product._id };
            const options = { upsert: true };

            await collection.replaceOne(filter, product, options);
            console.log(`Upserted product: ${product.name}`);
        }

检索文档

接下来，执行点读取操作，从集合中检索特定文档。

定义筛选器以按 ID 查找特定文档。

        // Retrieve a specific document by ID
        const filter = { _id: "00000000-0000-0000-0000-000000004018" };

        // Retrieve a specific document by ID
        const filter = { _id: "00000000-0000-0000-0000-000000004018" };

执行查询并检索结果。

        const retrievedProduct = await collection.findOne(filter);

        if (retrievedProduct) {
            console.log(`Retrieved product: ${retrievedProduct.name} - $${retrievedProduct.price}`);
        } else {
            console.log("Product not found");
        }

        const retrievedProduct = await collection.findOne(filter);

        if (retrievedProduct) {
            console.log(`Retrieved product: ${retrievedProduct.name} - $${retrievedProduct.price}`);
        } else {
            console.log("Product not found");
        }

查询文档

最后，使用 MongoDB 查询语言（MQL）查询多个文档。

定义查询以查找符合特定条件的文档。

        // Query for products on sale
        const saleFilter = { sale: true };
        const saleProducts = await collection.find(saleFilter).toArray();

        // Query for products on sale
        const saleFilter = { sale: true };
        const saleProducts = await collection.find(saleFilter).toArray();

遍历结果以显示匹配的文档。

        console.log("Products on sale:");
        for (const product of saleProducts) {
            console.log(`- ${product.name}: $${product.price.toFixed(2)} (Category: ${product.category})`);
        }

    } catch (error) {
        console.error("An error occurred:", error);
    } finally {
        await client.close();
    }
}

main().catch(console.error);

        console.log("Products on sale:");
        for (const product of saleProducts) {
            console.log(`- ${product.name}: $${product.price.toFixed(2)} (Category: ${product.category})`);
        }

    } catch (error) {
        console.error("An error occurred:", error);
    } finally {
        await client.close();
    }
}

main().catch(console.error);

使用 Visual Studio Code 浏览数据

使用 用于 Visual Studio Code 的 DocumentDB 扩展浏览数据并运行查询，而无需离开编辑器。安装扩展，然后按照使用 Visual Studio Code 连接连接到群集。

对于公共连接，允许您的客户端 IP 地址。对于专用连接，请使用可以访问群集专用终结点的开发环境。

在边栏中展开集群，然后打开包含此快速入门创建的 products 集合的数据库。
打开 products 的上下文菜单，然后选择“新建查询游乐场”。 Playground 会自动连接到该群集和数据库。

将生成的示例替换为以下查询：

db.products.find({
  price: { $gt: 200 },
  sale: true
})
.sort({ price: -1 })
.limit(3)

选择块上方的 “运行”。结果显示在侧面板中。
将脚本保存为 .documentdb.js 文件，以便稍后再次运行。

清理资源

完成 Azure DocumentDB 群集后，可以删除创建的Azure资源，以免产生更多费用。

在Azure门户搜索栏中，搜索并选择资源组。
在列表中选择为本快速入门使用的资源组。
在资源组页上，选择“删除资源组”。
在删除确认对话框中，输入资源组的名称以确认要删除它。最后，选择“删除”以永久删除资源组。

Azure DocumentDB 是什么？

Se actualizó por última vez el 2026-11-03