通过 JavaScript 使用 Azure Cosmos DB for MongoDB 入门

项目
09/14/2024

适用对象： MongoDB

本文介绍如何使用本机 MongoDB npm 包连接到 Azure Cosmos DB for MongoDB。连接后，可对数据库、集合和文档执行操作。

注意

示例代码片段在 GitHub 上作为 JavaScript 项目提供。

MongoDB API 参考文档 | MongoDB 包 (npm)

先决条件

创建新的 JavaScript 应用

使用首选终端在空文件夹中创建新的 JavaScript 应用程序。使用 npm init 命令开始提示用户创建 package.json 文件。接受提示的默认值。
```
npm init
```
将 MongoDB npm 包添加到 JavaScript 项目。使用 npm install package 命令指定 npm 包的名称。 dotenv 包用于在本地开发期间从 .env 文件中读取环境变量。
```
npm install mongodb dotenv
```
若要运行应用，请使用终端导航到应用程序目录并运行该应用程序。
```
node index.js
```

使用 MongoDB 本机驱动程序连接到 Azure Cosmos DB for MongoDB

若要使用 MongoDB 本机驱动程序连接到 Azure Cosmos DB，请创建 MongoClient 类的实例。此类是针对数据库执行所有操作的起点。

MongoClient 的最常见构造函数有两个参数：

参数	示例值	说明
`url`	`COSMOS_CONNECTION_STRING` 环境变量	用于所有请求的 API for MongoDB 连接字符串
`options`	`{ssl: true, tls: true, }`	用于连接的 MongoDB 选项。

有关连接问题，请参阅故障排除指南。

获取资源名称

为 resourceGroupName 创建 shell 变量。

# Variable for resource group name
resourceGroupName="msdocs-cosmos"

使用 az cosmosdb list 命令检索资源组中第一个 Azure Cosmos DB 帐户的名称，并将其存储在 accountName shell 变量中。

# Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

为 RESOURCE_GROUP_NAME 创建 shell 变量。

# Variable for resource group name
$RESOURCE_GROUP_NAME = "msdocs-cosmos"

使用 Get-AzCosmosDBAccountKey cmdlet 检索资源组中第一个 Azure Cosmos DB 帐户的名称，并将其存储在 accountName shell 变量中。

# Get the name of the first Azure Cosmos DB account in your resource group
$ACCOUNT_NAME = (Get-AzCosmosDBAccount -ResourceGroupName $RESOURCE_GROUP_NAME)[0].Name

检索连接字符串

使用 az cosmosdb keys list 命令，从帐户的连接字符串列表中查找 API for MongoDB 连接字符串。

az cosmosdb keys list --type connection-strings \
    --resource-group $resourceGroupName \
    --name $accountName

请记下“主密钥”值。稍后将使用这些凭据。

使用 Get-AzCosmosDBAccountKey cmdlet，从帐户的密钥和连接字符串列表中查找“连接字符串”。

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
    Type = "ConnectionStrings"
}    
Get-AzCosmosDBAccountKey @parameters |
    Select-Object -Property "Primary MongoDB Connection String"

请记下“连接字符串”值。稍后将使用这些凭据。

配置环境变量

若要在代码中使用“连接字符串”值，请在运行应用程序的本地环境中设置此值。若要设置环境变量，请使用首选终端运行以下命令：

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

export COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

.env 文件是将环境变量存储在项目中的标准方式。在项目的根目录中创建 .env 文件。将以下代码行添加到 .env 文件：

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

使用连接字符串创建 MongoClient

添加依赖项以引用 MongoDB 和 DotEnv npm 包。

// Read .env file and set environment variables
require('dotenv').config();

// Use official mongodb driver to connect to the server
const { MongoClient } = require('mongodb');

使用构造函数定义 MongoClient 类的新实例，并通过 process.env. 使用连接字符串。

// New instance of MongoClient with connection string
// for Cosmos DB
const url = process.env.COSMOS_CONNECTION_STRING;
const client = new MongoClient(url);

// connect to the server
await client.connect();

// client options
const options = client.options
console.log(`Options:\n${Object.keys(options).map(key => `\t${key}: ${options[key]}\n`)}`);

有关创建 MongoClient 实例的不同方法的详细信息，请参阅 MongoDB NodeJS 驱动程序快速入门。

关闭 MongoClient 连接

在应用程序完成连接后，请记得将其关闭。 .close() 调用应在执行所有数据库调用之后进行。

client.close()

将 MongoDB 客户端类与 Azure Cosmos DB for API for MongoDB 配合使用

在开始构建应用程序之前，我们先来了解 Azure Cosmos DB 中的资源层次结构。 Azure Cosmos DB 具有用于创建和访问资源的特定对象模型。 Azure Cosmos DB 在由帐户、数据库、集合和文档组成的层次结构中创建资源。

Azure Cosmos DB 层次结构示意图，其中包括帐户、数据库、集合和文档。

每种类型的资源由一个或多个关联的 JavaScript 类表示。下面列出了最常见的类：

类	说明
`MongoClient`	此类为 Azure Cosmos DB 上的 API for MongoDB 层提供客户端逻辑表示。此客户端对象用于对服务进行配置和执行请求。
`Db`	此类是对服务中可能存在或可能不存在的数据库的引用。在尝试访问该数据库或对其执行操作时，会在服务器端验证该数据库。
`Collection`	此类是对服务中可能不存在的集合的引用。在尝试使用该集合时，会在服务器端对其进行验证。

以下指南介绍了如何使用上述每个类来生成应用程序。

指南：

请参阅

后续步骤

现在，你已连接到 API for MongoDB 帐户，请使用下一指南创建和管理数据库。

使用 JavaScript 在 Azure Cosmos DB for MongoDB 中创建数据库

通过