開始搭配使用 Azure Cosmos DB for NoSQL 與 JavaScript
適用於:NoSQL
本文顯示如何使用 JavaScript SDK 連線至 Azure Cosmos DB for NoSQL。 連線之後,您即可在資料庫、容器和項目上執行作業。
套件 (npm) | 範例 | API 參考 | 程式庫原始程式碼 | 提供意見反應
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
- Azure Cosmos DB for NoSQL 帳戶。 建立 API for NoSQL 帳戶。
- Node.js LTS
- Azure 命令列介面 (CLI) 或 Azure PowerShell
設定本機專案
在 Bash 殼層中,建立您 JavaScript 專案的新目錄。
mkdir cosmos-db-nosql-javascript-samples && cd ./cosmos-db-nosql-javascript-samples
搭配使用
npm init
命令與主控台範本來建立新的 JavaScript 應用程式。npm init -y
安裝 Azure Cosmos DB for NoSQL JavaScript SDK 所需的相依性。
npm install @azure/cosmos
連線至 Azure Cosmos DB for NoSQL
若要連線到 Azure Cosmos DB 的 API for NoSQL,請建立 CosmosClient
類別的執行個體。 此類別是針對資料庫執行所有作業的起點。 使用 CosmosClient 類別連線到 API for NoSQL 帳戶有三種核心方法:
與端點和金鑰連線
CosmosClient 最常見的建構函式有兩個參數:
參數 | 範例值 | 描述 |
---|---|---|
accountEndpoint |
COSMOS_ENDPOINT 環境變數 |
供所有要求使用的 API for NoSQL 端點 |
authKeyOrResourceToken |
COSMOS_KEY 環境變數 |
驗證時要使用的帳戶金鑰或資源權杖 |
擷取您的帳戶端點和金鑰
建立 resourceGroupName 的殼層變數。
# Variable for resource group name resourceGroupName="msdocs-cosmos-javascript-howto-rg"
使用
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 )
使用
az cosmosdb show
命令取得帳戶的 API for NoSQL 端點 URI。az cosmosdb show \ --resource-group $resourceGroupName \ --name $accountName \ --query "documentEndpoint"
使用
az-cosmosdb-keys-list
命令,從帳戶的金鑰清單中尋找 PRIMARY KEY。az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "keys" \ --query "primaryMasterKey"
記錄 URI 和 PRIMARY KEY 值。 之後您將需要這些認證。
若要在程式碼中使用 URI 和 PRIMARY KEY 值,請將其保存在執行應用程式本機電腦上新的環境變數中。
$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"
使用帳戶端點和金鑰建立 CosmosClient
使用 COSMOS_ENDPOINT
和 COSMOS_KEY
環境變數作為參數,建立 CosmosClient 類別的新執行個體。
const client = new CosmosClient({ endpoint, key });
使用連接字串來連線
CosmosClient 的另一個建構函式僅包含單一參數:
參數 | 範例值 | 描述 |
---|---|---|
accountEndpoint |
COSMOS_ENDPOINT 環境變數 |
供所有要求使用的 API for NoSQL 端點 |
connectionString |
COSMOS_CONNECTION_STRING 環境變數 |
API for NoSQL 帳戶的連接字串 |
擷取您的帳戶連接字串
使用
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 )
使用
az-cosmosdb-keys-list
命令,從帳戶的連接字串清單中尋找 PRIMARY CONNECTION STRING。az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "connection-strings" \ --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"
若要在程式碼內使用 PRIMARY CONNECTION STRING 值,請將其持續保存至執行應用程式的本機電腦上的新環境變數。
$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"
使用連接字串建立 CosmosClient
使用 COSMOS_CONNECTION_STRING
環境變數作為唯一參數,建立 CosmosClient 類別的新執行個體。
// New instance of CosmosClient class using a connection string
const cosmosClient = new CosmosClient(process.env.COSMOS_CONNECTION_STRING);
使用 Microsoft 身分識別平台進行連線
若要使用 Microsoft 身分識別平台和 Microsoft Entra ID 與您的 API for NoSQL 帳戶連線,請使用安全性主體。 主體的確切類型取決於您裝載應用程式碼的位置。 下表可作為快速參考指南。
應用程式的執行位置 | 安全性主體 |
---|---|
本機電腦 (開發和測試) | 使用者身分識別或服務主體 |
Azure | 受控識別 |
Azure 外部的伺服器或用戶端 | 服務主體 |
匯入 @azure/identity
@azure/identity npm 套件包含所有 Azure SDK 程式庫之間共用的核心驗證功能。
使用
npm install
命令來匯入 @azure/identity npm 套件。npm install @azure/identity
在程式碼編輯器中,新增相依性。
const { DefaultAzureCredential } = require("@azure/identity");
使用預設認證實作建立 CosmosClient
如果您要在本機電腦上進行測試,或應用程式將在 Azure 服務上執行,並直接支援受控識別,請建立 DefaultAzureCredential
執行個體以取得 OAuth 權杖。 然後,使用 COSMOS_ENDPOINT
環境變數和 TokenCredential 物件作為參數,建立 CosmosClient 類別的新執行個體。
const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");
const credential = new DefaultAzureCredential();
const cosmosClient = new CosmosClient({
endpoint,
aadCredentials: credential
});
使用自訂的認證實作建立 CosmosClient
如果您規劃將應用程式部署至 Azure 外部,則可以使用適用於 JavaScript 的 @azure/identity 用戶端程式庫中的其他類別,來取得 OAuth 權杖。 這些其他類別也是衍生自 TokenCredential
類別。
在此範例中,我們會使用用戶端和租用戶識別碼以及用戶端密碼來建立 ClientSecretCredential
執行個體。
在 Microsoft Entra ID 中註冊應用程式時,您可以取得用戶端識別碼、租用戶識別碼和用戶端祕密。 如需註冊 Microsoft Entra 應用程式的詳細資訊,請參閱使用 Microsoft 身分識別平台註冊應用程式。
使用 COSMOS_ENDPOINT
環境變數和 TokenCredential 物件作為參數,建立 CosmosClient 類別的新執行個體。
const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");
const credential = new ClientSecretCredential(
tenantId: process.env.AAD_TENANT_ID,
clientId: process.env.AAD_CLIENT_ID,
clientSecret: process.env.AAD_CLIENT_SECRET
);
const cosmosClient = new CosmosClient({
endpoint,
aadCredentials: credential
});
建置您的 應用程式
組建應用程式時,程式碼主要與四種資源互動:
API for NoSQL 帳戶是 Azure Cosmos DB 資料的唯一最上層命名空間。
資料庫,用於組織帳戶中的容器。
容器,其中包含資料庫中的一組個別項目。
項目,代表容器中的 JSON 文件。
下圖顯示資源之間的關係。
在頂端顯示 Azure Cosmos DB 帳戶的階層式圖表。 帳戶有兩個子資料庫節點。 其中一個資料庫節點包含兩個子容器節點。 另一個資料庫節點包含單一子容器節點。 該單一容器節點有三個子項目節點。
每種資源都會以一或多個相關聯類別來代表。 以下是最常見類別的清單:
類別 | 描述 |
---|---|
CosmosClient |
此類別提供適用於 Azure Cosmos DB 服務的用戶端邏輯表示法。 用戶端物件會用於設定及執行針對服務的要求。 |
Database |
此類別是服務中可能或可能不存在的資料庫參考。 當您嘗試存取資料庫或對其執行作業時,資料庫為已驗證的伺服器端。 |
Container |
此類別為容器參考,可能尚未於伺服器中存在。 當您嘗試使用此項目時,容器為已驗證的伺服器端。 |
下列指南說明如何以上每個類別來組建應用程式。
指南 | 描述 |
---|---|
建立資料庫 | 建立資料庫 |
建立容器 | 建立容器 |
建立和讀取項目 | 點讀取特定項目 |
查詢項目 | 查詢多個項目 |
另請參閱
下一步
既然您已連線到 API for NoSQL 帳戶,請使用下一個指南來建立和管理資料庫。