開始搭配 Azure Cosmos DB for MongoDB 使用 JavaScript

發行項
03/22/2024

適用於： MongoDB

本文說明如何使用原生 MongoDB npm 套件連線到 Azure Cosmos DB for MongoDB。連線之後，您即可在資料庫、集合和文件上執行作業。

注意

範例程式碼片段可在 GitHub 上以 JavaScript 專案形式取得。

API for MongoDB 參考文件 | 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 的殼層變數。

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

使用 az cosmosdb list 命令來擷取資源群組中第一個 Azure Cosmos DB 帳戶的名稱，並將其儲存在 accountName 殼層變數中。

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

建立 RESOURCE_GROUP_NAME 的殼層變數。

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

使用 Get-AzCosmosDBAccountKey Cmdlet 擷取資源群組中第一個 Azure Cosmos DB 帳戶的名稱，並將其儲存在 accountName 殼層變數中。

# 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

記錄 PRIMARY KEY 值。稍後您將使用這些認證。

使用 Cmdlet，從帳戶的金鑰和連接字串清單中尋找 CONNECTION STRINGGet-AzCosmosDBAccountKey。

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

記錄 CONNECTION STRING 值。稍後您將使用這些認證。

設定環境變數

若要在程式碼內使用 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 用戶端類別與適用於 API for MongoDB 的 Azure Cosmos DB 搭配使用

在開始建置應用程式之前，讓我們看一下 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 中建立資料庫