教程:使用 JavaScript SDK 生成 Node.js 控制台应用以管理 Azure Cosmos DB SQL API 数据

适用于: SQL API

作为开发人员,你可能有使用 NoSQL 文件数据的应用程序。 可以使用 Azure Cosmos DB 中的 SQL API 帐户存储和访问此文档数据。 本教程介绍如何生成 Node.js 控制台应用程序,以便创建 Azure Cosmos DB 资源并对其进行查询。

在本教程中,将:

  • 创建并连接到 Azure Cosmos DB 帐户。
  • 设置应用程序。
  • 创建数据库。
  • 创建容器。
  • 向容器添加项。
  • 对项、容器和数据库执行基本操作。

先决条件

请确保具有以下资源:

创建 Azure Cosmos DB 帐户

让我们创建一个 Azure Cosmos DB 帐户。 如果已经有想要使用的帐户,可以跳到 安装 Node.js 应用程序。 如果使用 Azure Cosmos DB 模拟器,请遵循 Azure Cosmos DB 模拟器中的步骤设置该模拟器,并直接跳到设置 Node.js 应用程序

  1. 在 Azure 门户菜单或主页中,选择“创建资源” 。

  2. 在“新建”页面中搜索“Azure Cosmos DB”,然后选择它。

  3. 在“Azure Cosmos DB”页上,选择“创建”。

  4. 在“创建 Azure Cosmos DB 帐户”页中,输入新 Azure Cosmos 帐户的基本设置。

    设置 说明
    订阅 订阅名称 选择要用于此 Azure Cosmos 帐户的 Azure 订阅。
    资源组 资源组名称 选择一个资源组,或者选择“新建”,然后输入新资源组的唯一名称。
    帐户名 唯一的名称 输入标识此 Azure Cosmos 帐户的名称。 由于 documents.azure.cn 将追加到所提供的名称以创建 URI,因此,请使用唯一的名称。

    名称只能包含小写字母、数字和连字符 (-)。 它的长度必须介于 3 到 31 个字符之间。
    API 要创建的帐户的类型 选择“Core (SQL)”,以便使用 SQL 语法创建文档数据库并进行查询。

    API 确定要创建的帐户的类型。 Azure Cosmos DB 提供五种 API:适用于文档数据的 Core (SQL) 和 MongoDB、适用于图形数据的 Gremlin、Azure 表和 Cassandra。 目前,你必须为每种 API 创建单独的帐户。

    详细了解 SQL API
    位置 离用户最近的区域 选择用于托管 Azure Cosmos DB 帐户的地理位置。 使用离用户最近的位置,使他们能够以最快的速度访问数据。
    容量模式 预配吞吐量或无服务器 选择“预配吞吐量”以在预配吞吐量模式下创建帐户。 选择“无服务器”以在无服务器模式下创建帐户。
    应用 Azure Cosmos DB 免费层折扣 “应用”或“不应用” 使用 Azure Cosmos DB 免费层,你将在帐户中获得每秒前 1000 RU 的免费吞吐量和 25 GB 的免费存储。 了解免费层的详细信息。

    备注

    每个 Azure 订阅最多可以有一个免费层 Azure Cosmos DB 帐户,并且你必须在创建帐户时选择加入使用。 如果看不到用于应用免费层折扣的选项,这意味着订阅中的另一个帐户已启用免费层。

    Azure Cosmos DB 的“新建帐户”页面

  5. 在“全局分发”选项卡中,配置以下详细信息。 对于本快速入门,可以保留默认值:

    设置 说明
    异地冗余 禁用 通过将你的区域与另一区域进行配对来启用或禁用帐户的全局分发。 稍后可以将更多区域添加到帐户。
    多区域写入 禁用 借助多区域写入功能,可以利用全球数据库和容器的预配吞吐量。

    备注

    如果选择“无服务器”作为“容量模式”,则以下选项不可用 :

    • 应用免费层折扣
    • 异地冗余
    • 多区域写入
  6. (可选)可以在以下选项卡中配置其他详细信息:

    • 网络 - 配置从虚拟网络进行访问

    • 备份策略 -配置定期备份策略。

    • 加密 - 使用服务管理的密钥或客户管理的密钥

    • 标记 - 标记是名称/值对。通过将相同的标记应用到多个资源和资源组,可以对资源进行分类并查看合并的账单。

  7. 选择“查看 + 创建”。

  8. 检查帐户设置,然后选择“创建”。 创建帐户需要几分钟时间。 等待门户页显示“你的部署已完成”消息。

    Azure 门户“通知”窗格

  9. 选择“转到资源”,转到 Azure Cosmos DB 帐户页。

    Azure Cosmos DB 帐户页面

设置 Node.js 应用程序

在开始编写生成应用程序所需的代码之前,可以生成应用的框架。 运行以下步骤,设置包含框架代码的 Node.js 应用程序:

  1. 打开最喜爱的终端。

  2. 找到想要在其中保存 Node.js 应用程序的文件夹或目录。

  3. 使用以下命令创建空的 JavaScript 文件:

    • Windows:

      • fsutil file createnew app.js 0
      • fsutil file createnew config.js 0
      • md data
      • fsutil file createnew data\databaseContext.js 0
    • Linux/OS X:

      • touch app.js
      • touch config.js
      • mkdir data
      • touch data/databaseContext.js
  4. 创建并初始化 package.json 文件。 使用以下命令:

    • npm init -y
  5. 通过 npm 安装 @azure/cosmos 模块。 使用以下命令:

    • npm install @azure/cosmos --save

设置应用的配置

有了应用以后,需确保它可以与 Azure Cosmos DB 通信。 如以下步骤所示,更新一些配置设置即可将应用设置为与 Azure Cosmos DB 通信:

  1. 在你喜欢使用的文本编辑器中打开 config.js 文件。

  2. 将以下代码片段复制并粘贴到 config.js 文件中,并将属性 endpointkey 设置为 Azure Cosmos DB 终结点 URI 和主密钥。 数据库和容器名称设置为“Tasks”和“Items”。 将用于此应用程序的分区键是 /category。

    // @ts-check
    
    const config = {
        endpoint: "<Your Azure Cosmos account URI>",
        key: "<Your Azure Cosmos account key>",
        databaseId: "Tasks",
        containerId: "Items",
        partitionKey: { kind: "Hash", paths: ["/category"] }
    };
    
    module.exports = config;
    

    可在 Azure 门户的“键”窗格中找到终结点和键详细信息。

    从 Azure 门户获取密钥的屏幕截图

JavaScript SDK 使用通用术语“容器”和“项”。 容器可以是集合、图或表。 项可以是文档、边缘/顶点或行,是容器中的内容。 在前面的代码片段中,module.exports = config; 代码用于导出 config 对象,以便你在 app.js 文件中引用它。

创建数据库和容器

  1. 在你喜欢使用的文本编辑器中打开 databaseContext.js 文件。

  2. 将以下代码复制并粘贴到 databaseContext.js 文件中。 此代码定义了一个函数,该函数创建“Tasks”数据库和“Items”容器(如果它们在 Azure Cosmos 帐户中不存在):

    const config = require("../config");
    const CosmosClient = require("@azure/cosmos").CosmosClient;
    
    /*
    // This script ensures that the database is setup and populated correctly
    */
    async function create(client, databaseId, containerId) {
        const partitionKey = config.partitionKey;
    
        /**
        * Create the database if it does not exist
        */
        const { database } = await client.databases.createIfNotExists({
            id: databaseId
        });
        console.log(`Created database:\n${database.id}\n`);
    
        /**
         * Create the container if it does not exist
         */
        const { container } = await client
            .database(databaseId)
            .containers.createIfNotExists(
            { id: containerId, partitionKey },
            { offerThroughput: 400 }
        );
    
        console.log(`Created container:\n${container.id}\n`);
    }
    
    module.exports = { create };
    
    

    数据库是跨容器分区的项的逻辑容器。 使用 Databases 类的 createIfNotExists 或 create 函数创建数据库。 在使用 SQL API 的情况下,包含项的容器为 JSON 文档。 使用 Containers 类的 createIfNotExists 或 create 函数创建容器。 创建容器后,你可以存储并查询数据。

    警告

    创建容器涉及到定价。 请访问定价页,了解相关信息。

导入配置

  1. 在你喜欢使用的文本编辑器中打开 app.js 文件。

  2. 复制并粘贴以下代码,以便导入在前面的步骤中定义的 @azure/cosmos 模块、配置和 databaseContext。

    const CosmosClient = require("@azure/cosmos").CosmosClient;
    const config = require("./config");
    const dbContext = require("./data/databaseContext");
    

连接到 Azure Cosmos 帐户

在 app.js 文件中,复制并粘贴以下代码,以便使用前面保存的终结点和键来创建新的 CosmosClient 对象。

const { endpoint, key, databaseId, containerId } = config;

const client = new CosmosClient({ endpoint, key });

const database = client.database(databaseId);
const container = database.container(containerId);

// Make sure Tasks database is already setup. If not, create it.
await dbContext.create(client, databaseId, containerId);

备注

如果连接到 Cosmos DB 模拟器,请为节点进程禁用 TLS 验证:

process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
const client = new CosmosClient({ endpoint, key });

现已获得用于初始化 Azure Cosmos DB 客户端的代码,接下来请看如何使用 Azure Cosmos DB 资源。

查询项

Azure Cosmos DB 支持对存储在每个容器中的 JSON 项进行各种查询。 以下示例代码展示了一个可以针对容器中项运行的查询。可以使用 Items 类的 query 函数来查询项。 将以下代码添加到 app.js 文件中,以便从 Azure Cosmos 帐户查询项:

console.log(`Querying container: Items`);

// query to return all items
const querySpec = {
  query: "SELECT * from c"
};

// read all items in the Items container
const { resources: items } = await container.items
  .query(querySpec)
  .fetchAll();

items.forEach(item => {
  console.log(`${item.id} - ${item.description}`);
});

创建项

可以使用 Items 类的 create 函数创建项。 使用 SQL API 时,项会投射为文档,后者是用户定义的(任意)JSON 内容。 在本教程中,我们在 tasks 数据库中创建一个新项。

  1. 在 app.js 文件中,定义项定义:

    const newItem = {
      id: "3",
      category: "fun",
      name: "Cosmos DB",
      description: "Complete Cosmos DB Node.js Quickstart ⚡",
      isComplete: false
    };
    
  2. 添加以下代码,以便创建前面定义的项:

    /** Create new item
    * newItem is defined at the top of this file
    */
    const { resource: createdItem } = await container.items.create(newItem);
    
    console.log(`\r\nCreated new item: ${createdItem.id} - ${createdItem.description}\r\n`);
    
    

更新项

Azure Cosmos DB 支持替换项的内容。 将以下代码复制并粘贴到 app.js 文件中。 此代码获取容器中的某个项,并将 isComplete 字段更新为 true。

/** Update item
 * Pull the id and partition key value from the newly created item.
 * Update the isComplete field to true.
 */
const { id, category } = createdItem;

createdItem.isComplete = true;

const { resource: updatedItem } = await container
  .item(id, category)
  .replace(createdItem);

console.log(`Updated item: ${updatedItem.id} - ${updatedItem.description}`); 
console.log(`Updated isComplete to ${updatedItem.isComplete}\r\n`);

删除项

Azure Cosmos DB 支持删除 JSON 项。 以下代码展示了如何通过项 ID 获取项并将其删除。 将以下代码复制并粘贴到 app.js 文件中:

/**
 * Delete item
 * Pass the id and partition key value to delete the item
 */
const { resource: result } = await container.item(id, category).delete();
console.log(`Deleted item with id: ${id}`);

运行 Node.js 应用程序

总起来看,代码应如下所示:

// @ts-check
//  <ImportConfiguration>
const CosmosClient = require("@azure/cosmos").CosmosClient;
const config = require("./config");
const dbContext = require("./data/databaseContext");
//  </ImportConfiguration>

//  <DefineNewItem>
const newItem = {
  id: "3",
  category: "fun",
  name: "Cosmos DB",
  description: "Complete Cosmos DB Node.js Quickstart ⚡",
  isComplete: false
};
//  </DefineNewItem>

async function main() {

  // <CreateClientObjectDatabaseContainer>
  const { endpoint, key, databaseId, containerId } = config;

  const client = new CosmosClient({ endpoint, key });

  const database = client.database(databaseId);
  const container = database.container(containerId);

  // Make sure Tasks database is already setup. If not, create it.
  await dbContext.create(client, databaseId, containerId);
  // </CreateClientObjectDatabaseContainer>

  try {
    // <QueryItems>
    console.log(`Querying container: Items`);

    // query to return all items
    const querySpec = {
      query: "SELECT * from c"
    };

    // read all items in the Items container
    const { resources: items } = await container.items
      .query(querySpec)
      .fetchAll();

    items.forEach(item => {
      console.log(`${item.id} - ${item.description}`);
    });
    // </QueryItems>

    // <CreateItem>
    /** Create new item
     * newItem is defined at the top of this file
     */
    const { resource: createdItem } = await container.items.create(newItem);

    console.log(`\r\nCreated new item: ${createdItem.id} - ${createdItem.description}\r\n`);
    // </CreateItem>

    // <UpdateItem>
    /** Update item
     * Pull the id and partition key value from the newly created item.
     * Update the isComplete field to true.
     */
    const { id, category } = createdItem;

    createdItem.isComplete = true;

    const { resource: updatedItem } = await container
      .item(id, category)
      .replace(createdItem);

    console.log(`Updated item: ${updatedItem.id} - ${updatedItem.description}`); 
    console.log(`Updated isComplete to ${updatedItem.isComplete}\r\n`);
    // </UpdateItem>

    // <DeleteItem>    
    /**
     * Delete item
     * Pass the id and partition key value to delete the item
     */
    const { resource: result } = await container.item(id, category).delete();
    console.log(`Deleted item with id: ${id}`);
    // </DeleteItem>  

  } catch (err) {
    console.log(err.message);
  }
}

main();

在终端中,找到 app.js 文件并运行以下命令:

node app.js

应该看到已启动应用的输出。 输出应该匹配下面的示例文本。

Created database:
Tasks

Created container:
Items

Querying container: Items
1 - Pick up apples and strawberries.

Created new item: 3 - Complete Cosmos DB Node.js Quickstart ⚡

Updated item: 3 - Complete Cosmos DB Node.js Quickstart ⚡
Updated isComplete to true

Deleted item with id: 3

获取完整的 Node.js 教程解决方案

如果没有时间完成本教程中的步骤,或者只需下载代码,则可从 GitHub 获取。

若要运行包含本文所有代码的入门解决方案,需要以下项:

通过 npm 安装项目的依赖项。 使用以下命令:

  • npm install

接下来,在 config.js 文件中更新 config.endpoint 和 config.key 的值,如步骤 3:设置应用的配置中所述。

然后在终端中找到 app.js 文件并运行以下命令:

node app.js 

清理资源

不再需要资源组、Azure Cosmos DB 帐户和所有相关的资源时,可将这些资源删除。 为此,请选择用于 Azure Cosmos DB 帐户的资源组,接着选择“删除”,然后确认要删除的资源组的名称。

后续步骤