你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
开始通过 JavaScript 使用 Azure Cosmos DB for NoSQL
适用范围: 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 shell 中为 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 创建 shell 变量。
# Variable for resource group name resourceGroupName="msdocs-cosmos-javascript-howto-rg"
使用
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 )
使用
az cosmosdb show
命令获取帐户的 API for NoSQL 终结点 URI。az cosmosdb show \ --resource-group $resourceGroupName \ --name $accountName \ --query "documentEndpoint"
使用
az-cosmosdb-keys-list
命令从帐户的密钥列表中查找主密钥。az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "keys" \ --query "primaryMasterKey"
记录 URI 和主密钥值。 稍后将使用这些凭据。
若要在代码中使用“URI”和“主密钥”值,请将其保存到运行应用程序的本地计算机上的新环境变量。
$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 shell 变量中。# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
使用
az-cosmosdb-keys-list
命令,从帐户的连接字符串列表中查找主连接字符串。az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "connection-strings" \ --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"
若要在代码中使用“主连接字符串”值,请将其保存到运行应用程序的本地计算机上的新环境变量。
$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 中注册应用程序时,可以获取客户端 ID、租户 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 帐户,请使用下一指南创建和管理数据库。