從使用 JavaScript 開始操作 Azure Cosmos DB for MongoDB

適用於: ✅ MongoDB

適用於： MongoDB

Important

您是否想要遷移現有的 MongoDB 應用程式或使用 MongoDB 查詢語言（MQL）功能？可以考慮 Azure DocumentDB。

您是否正在尋找一種適用於高擴展性場景的資料庫解決方案，且具有 99.999% 可用性的服務等級協定（SLA）、即時自動擴展，以及跨多個區域的自動容錯切換？考慮使用Azure Cosmos DB作為NoSQL的選擇。

這篇文章會教你如何利用原生的 MongoDB npm 套件連接 Azure Cosmos DB for MongoDB。連線之後，您即可在資料庫、集合和文件上執行作業。

Note

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

API for MongoDB 參考文件 | MongoDB 套件 (npm)

Prerequisites

建立一個新的 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 原生驅動程式至適用於 MongoDB 的 Azure Cosmos DB

若要連接 MongoDB 原生驅動以Azure Cosmos DB，請建立一個 MongoClient 類別的實例。此類別是針對資料庫執行所有作業的起點。

MongoClient 最常見的建構函數有兩個參數：

參數	範例值	Description
`url`	`COSMOS_CONNECTION_STRING` 環境變數	用於所有請求的 MongoDB 連接字串 API
`options`	`{ssl: true, tls: true, }`	MongoDB 的連結選項。

請參閱連線問題的疑難排解指南。

取得資源名稱

建立 resourceGroupName 的 shell 變數。

# 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 的 Shell 變數。

# 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

擷取連接字串

使用命令，從帳戶的連接字串清單中尋找 API for MongoDB az cosmosdb keys list。

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

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

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

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

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

小提示

針對本指南，我們建議使用資源組名稱 msdocs-cosmos。

請登入Azure portal。
瀏覽至現有的 Azure Cosmos DB for MongoDB 帳戶頁面。
從 Azure Cosmos DB for MongoDB 帳戶頁面中，選取 [連接字串] 導覽功能表選項。
記錄 [PRIMARY 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 套件。

// Use official mongodb driver to connect to the server
import { MongoClient } from '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 會在由帳戶、資料戶、集合和文件所組成的階層中建立資源。

適用於 MongoDB 的 Azure Cosmos DB 階層圖，包括帳戶、資料庫、集合和檔。

每種資源類型由一個或多個相關的 JavaScript 類別表示。以下是最常見類別的清單：

Class	Description
`MongoClient`	此類別提供 Azure Cosmos DB 上 API for MongoDB 層的用戶端邏輯表示法。用戶端物件會用於設定及執行針對服務的要求。
`Db`	這個類別是對一個資料庫的參考，該資料庫可能已經存在，也可能尚未存在於服務中。當你嘗試存取資料庫或執行操作時，該資料庫會被伺服器端驗證。
`Collection`	此類別為集合參考，也可能尚未存在於服務中。當您嘗試使用集合時，集合會在伺服器端進行驗證。

以下指南將說明如何使用這些類別來組建應用程式。

指南：

另請參閱

下一步

既然您已連線到 API for MongoDB 帳戶，請使用下一個指南來建立和管理資料庫。

使用 JavaScript 在 Azure Cosmos DB 中建立 MongoDB 資料庫

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-04-27