Leer en inglés

Compartir a través de

快速入门：将 Azure Cosmos DB for NoSQL 与用于 Node.js 的 Azure SDK 配合使用

  • Artículo
  • 09/05/2025
  • Se aplica a: ✅ NoSQL

在本快速入门中，你将使用 Azure SDK for Node.js部署基本的 Azure Cosmos DB for NoSQL 应用程序。 Azure Cosmos DB for NoSQL 是一种无架构数据存储，允许应用程序在云中存储非结构化数据。 使用适用于 Node.js的 Azure SDK 查询您的容器中的数据，并对单个项执行常见操作。

API 参考文档 | 库源代码 | 包 (npm) | Azure Developer CLI

先决条件

  • Azure 开发人员 CLI
  • Docker Desktop
  • Node.js 22 或更高版本

如果你没有 Azure 帐户，请在开始之前创建一个试用帐户。

初始化项目

使用 Azure 开发人员 CLI （azd） 创建 Azure Cosmos DB for NoSQL 帐户并部署容器化示例应用程序。 示例应用程序使用客户端库来管理、创建、读取和查询示例数据。

  1. 在空目录中打开终端。

  2. 如果尚未经过身份验证，请使用 azd auth login 向 Azure Developer CLI 进行身份验证。 按照该工具指定的步骤，使用首选 Azure 凭据向 CLI 进行身份验证。

    azd auth login

  3. 使用 azd init 来初始化项目。

    azd init --template cosmos-db-nosql-nodejs-quickstart

  4. 在初始化期间，配置唯一的环境名称。

  5. 使用 azd up 部署 Azure Cosmos DB 帐户。 Bicep 模板还部署示例 Web 应用程序。

    azd up

  6. 在预配过程中，选择订阅、所需位置和目标资源组。 等待预配过程完成。 此过程可能需要大约 5 分钟。

  7. 预配 Azure 资源后，输出中将包含指向正在运行的 Web 应用程序的 URL。

    Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

  8. 使用控制台中的 URL 在浏览器中导航到 Web 应用程序。 观察正在运行的应用的输出。

正在运行的 Web 应用程序的屏幕截图。

正在运行的 Web 应用程序的屏幕截图。

安装客户端库

客户端库可通过 Node 包管理器作为 @azure/cosmos 包使用。

  1. 打开终端并导航到 /src 文件夹。

    cd ./src

  2. 使用 @azure/cosmos 安装 npm install 包（如果尚未安装）。

    npm install --save @azure/cosmos

  3. 另请安装 @azure/identity 包（如果尚未安装）。

    npm install --save @azure/identity

  4. 打开并检查 src/package.json 文件以验证 azure-cosmos 和 azure-identity 条目是否都存在。

导入库文件

将 DefaultAzureCredential 和 CosmosClient 类型导入应用程序代码。

import { DefaultAzureCredential } from '@azure/identity';
import { CosmosClient } from '@azure/cosmos';

将所有必需的类型导入应用程序代码。

import { PagedAsyncIterableIterator } from '@azure/core-paging';
import { DefaultAzureCredential, TokenCredential } from '@azure/identity';
import { Container, CosmosClient, Database, FeedResponse, ItemResponse, SqlQuerySpec } from '@azure/cosmos';

对象模型

名称 描述
CosmosClient 此类是主要客户端类，用于管理帐户范围的元数据或数据库。
Database 此类表示帐户中的一个数据库。
Container 此类主要用于对容器或容器中存储的项执行读取、更新和删除操作。
PartitionKey 此类表示逻辑分区键。 许多常见操作和查询都需要此类。
SqlQuerySpec 此接口表示 SQL 查询和任何查询参数。

代码示例

模板中的示例代码使用名为 cosmicworks 的数据库和名为 products 的容器。 products 容器包含每个产品的名称、类别、数量、唯一标识符和销售标志等详细信息。 该容器使用 /category 属性作为逻辑分区键。

验证客户端

此示例创建一个 CosmosClient 类型的新实例并使用 DefaultAzureCredential 实例进行身份验证。

const credential = new DefaultAzureCredential();

const client = new CosmosClient({
    '<azure-cosmos-db-nosql-account-endpoint>',
    aadCredentials: credential
});

const credential: TokenCredential = new DefaultAzureCredential();

const client = new CosmosClient({
    '<azure-cosmos-db-nosql-account-endpoint>',
    aadCredentials: credential
});

获取数据库

使用 client.database 检索名为 cosmicworks 的现有数据库。

const database = client.database('cosmicworks');

const database: Database = client.database('cosmicworks');

获取容器

使用 products 检索现有的 database.container 容器。

const container = database.container('products');

const container: Container = database.container('products');

创建一个项目

使用要序列化为 JSON 的所有成员生成一个新对象。 在此示例中，该类型具有唯一标识符以及用于类别、名称、数量、价格和销售的字段。 使用 container.items.upsert 在容器中创建某个项。 如果该项已经存在，此方法会“更新插入”该项，从而有效地替换该项。

const item = {
    'id': 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

let response = await container.items.upsert(item);

const item: Product = {
    'id': 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

let response: ItemResponse<Product> = await container.items.upsert<Product>(item);

读取项

同时使用唯一标识符 (id) 和分区键字段来执行点读取操作。 使用 container.item 获取指向某个项的指针，并使用 item.read 高效检索特定项。

const id = 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb';
const partitionKey = 'gear-surf-surfboards';

let response = await container.item(id, partitionKey).read();
let read_item = response.resource;

const id = 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb';
const partitionKey = 'gear-surf-surfboards';

let response: ItemResponse<Product> = await container.item(id, partitionKey).read<Product>();
let read_item: Product = response.resource!;

查询项

使用 container.items.query 对容器中的多个项执行查询。 使用此参数化查询查找指定类别中的所有项：

SELECT * FROM products p WHERE p.category = @category

使用 query.fetchAll 提取查询的所有结果。 遍历查询的结果。

const querySpec = {
    query: 'SELECT * FROM products p WHERE p.category = @category',
    parameters: [
        {
            name: '@category',
            value: 'gear-surf-surfboards'
        }
    ]
};

let response = await container.items.query(querySpec).fetchAll();
for (let item of response.resources) {
    // Do something
}

const querySpec: SqlQuerySpec = {
    query: 'SELECT * FROM products p WHERE p.category = @category',
    parameters: [
        {
            name: '@category',
            value: 'gear-surf-surfboards'
        }
    ]
};

let response: FeedResponse<Product> = await container.items.query<Product>(querySpec).fetchAll();
for (let item of response.resources) {
    // Do something
}

探索您的数据

使用适用于 Azure Cosmos DB 的 Visual Studio Code 扩展来浏览 NoSQL 数据。 可以执行核心数据库操作，这些操作包括但不限于：

  • 使用剪贴簿或查询编辑器执行查询
  • 修改、更新、创建和删除项
  • 从其他源导入批量数据
  • 管理数据库和容器

有关详细信息，请参阅如何使用 Visual Studio Code 扩展来浏览 Azure Cosmos DB for NoSQL 数据。

清理资源

不再需要示例应用程序或资源时，请删除相应的部署和所有资源。

azd down

相关内容