快速入门：使用 Node.js 连接和查询 Azure Cosmos DB SQL API 帐户中的数据

  • 项目

适用于： SQL API

在本快速入门中，你将通过 Azure 门户并使用从 GitHub 克隆的 Node.js 应用来创建和管理 Azure Cosmos DB SQL API 帐户。 Azure Cosmos DB 是一种多模型数据库服务，可让你通过多区域分布和水平缩放功能快速创建和查询文档、表、键/值和图数据库。

先决条件

创建 Azure Cosmos 帐户

  1. 导航到 Azure 中国门户，然后使用有效订阅登录。

  2. 登录成功后，应在 Azure 订阅内创建帐户。

添加容器

现在可以在 Azure 门户中使用数据资源管理器工具来创建数据库和容器。

  1. 选择“数据资源管理器”>“新建容器”。

    “添加容器”区域显示在最右侧，可能需要向右滚动才能看到它。

    The Azure portal Data Explorer, Add Container pane

  2. 在“添加容器”页中，输入新容器的设置。

    设置 建议的值 说明
    数据库 ID ToDoList 输入 Tasks 作为新数据库的名称。 数据库名称必须包含 1 到 255 个字符，不能包含 /, \\, #, ? 或尾随空格。 选中“跨容器共享吞吐量”选项，这样就可以在数据库中的所有容器之间共享在该数据库上预配的吞吐量。 此选项还有助于节省成本。
    数据库吞吐量 可以预配“自动缩放”或“手动”吞吐量 。 “手动”吞吐量使你可以自行缩放 RU/秒，而自动缩放吞吐量使系统可以根据使用情况缩放 RU/秒。 对于此示例，请选择“手动”。

    将吞吐量保留为每秒 400 个请求单位 (RU/s)。 如果希望减少延迟，可以稍后通过使用容量计算器估算所需的 RU/秒来纵向扩展吞吐量。

    注意：在无服务器帐户中创建新容器时，此设置不可用。
    容器 ID Items 输入 Items 作为新容器的名称。 容器 ID 与数据库名称的字符要求相同。
    分区键 /category 本文中所述的示例使用 /category 作为分区键。

    请勿为此示例添加“唯一键”或启用“分析存储” 。 使用唯一键可将数据完整性层添加到数据库，因为它能确保每个分区键的一个或多个值的唯一性。 有关详细信息，请参阅 Azure Cosmos DB 中的唯一键。分析存储用于针对操作数据启用大规模分析，而不会对事务工作负载产生任何影响。

    选择“确定”。 数据资源管理器将显示新的数据库和容器。

添加示例数据

现在可以使用数据资源管理器将数据添加到新容器。

  1. 在“数据资源管理器”中展开“Tasks”数据库，然后展开“Items”容器。 依次选择“项”、“新建项”。

    Create new documents in Data Explorer in the Azure portal

  2. 现在，将文档添加到具有以下结构的容器。

    {
    "id": "1",
    "category": "personal",
    "name": "groceries",
    "description": "Pick up apples and strawberries.",
    "isComplete": false
}

  3. 将 json 添加到“文档”选项卡以后，即可选择“保存”。

    Copy in json data and select Save in Data Explorer in the Azure portal

  4. 再创建并保存一个文档，在其中插入 id 属性的唯一值，并将其他属性更改为适当值。 新文档可以具有所需的任何结构，因为 Azure Cosmos DB 不对数据施加任何架构。

查询数据

可以在数据资源管理器中使用查询来检索和筛选数据。

  1. 在数据资源管理器的“项”选项卡顶部，查看默认查询 SELECT * FROM c。 此查询检索并显示容器中按 ID 排序的所有文档。

    Default query in Data Explorer is SELECT * FROM c

  2. 若要更改查询，请选择“编辑筛选器”，将默认查询替换为 ORDER BY c._ts DESC，然后选择“应用筛选器”。

    Change the default query by adding ORDER BY c._ts DESC and clicking Apply Filter

    此修改后的查询根据文档的时间戳按降序显示文档，所以现在最先列出的是第二个文档。

    Changed query to ORDER BY c._ts DESC and clicking Apply Filter

如果熟悉 SQL 语法，可以在查询谓词框中输入任何受支持的 SQL 查询。 还可以使用数据资源管理器创建存储过程、UDF 和触发器以执行服务器端业务逻辑。

数据资源管理器可以通过 Azure 门户轻松访问 API 中提供的所有内置编程数据访问功能。 也可通过门户缩放吞吐量、获取密钥和连接字符串，以及查看 Azure Cosmos DB 帐户的指标和 SLA。

克隆示例应用程序

现在让我们从 GitHub 克隆 Node.js 应用，设置连接字符串并运行。

  1. 运行下列命令以克隆示例存储库。 此命令在计算机上创建示例应用程序的副本。

    git clone https://github.com/Azure-Samples/azure-cosmos-db-sql-api-nodejs-getting-started.git

查看代码

此步骤是可选的。 如果有意了解如何使用代码创建 Azure Cosmos 数据库资源，可以查看以下代码片段。 否则，可以直接跳转到更新连接字符串。

如果你熟悉旧版 SQL JavaScript SDK，则可能习惯于看到术语“集合”和“文档”。 由于 Azure Cosmos DB 支持多 API 模型，因此 2.0+ 版的 JavaScript SDK 使用通用术语“容器”（可能为集合、图形或表），并使用“项”来描述容器的内容。

Cosmos DB JavaScript SDK 称为“@azure/cosmos”，可以从 npm 安装...

npm install @azure/cosmos

以下代码片段全部摘自 app.js 文件。

  • CosmosClient 从 @azure/cosmos npm 包导入。

    const CosmosClient = require("@azure/cosmos").CosmosClient;

  • 新的 CosmosClient 对象已初始化。

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

  • 选择“Tasks”数据库。

    const database = client.database(databaseId);

  • 选择“Items”容器/集合。

    const container = database.container(containerId);

  • 选择“Items”容器中的所有项目。

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

const { resources: items } = await container.items
    .query(querySpec)
    .fetchAll();

  • 创建新项

    const { resource: createdItem } = await container.items.create(newItem);

  • 更新项

    const { id, category } = createdItem;

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

  • 删除项

    const { resource: result } = await container.item(id, category).delete();

注意

在“update”和“delete”方法中，必须通过调用 container.item() 从数据库中选择项。 传入的两个参数是项的 ID 和项的分区键。 在这种情况下，分区键是“category”字段的值。

更新连接字符串

现在，返回 Azure 门户，获取 Azure Cosmos 帐户的连接字符串详细信息。 将连接字符串复制到应用，以便其连接数据库。

  1. 在 Azure 门户中，在你的 Azure Cosmos DB 帐户中，从左侧导航栏中选择“密钥”，然后选择“读写密钥”。 在下一步中，使用屏幕右侧的复制按钮将 URI 和主密钥复制到 app.js 文件中。

    View and copy an access key in the Azure portal, Keys blade

  2. 打开 config.js 文件。

  3. 从门户中复制 URI 值（使用复制按钮），并在 config.js 中将其设为终结点密钥的值。

    endpoint: "<Your Azure Cosmos account URI>"

  4. 然后从门户复制“主密钥”的值，并在 config.js 中将其设为 config.key 的值。 现已使用与 Azure Cosmos DB 进行通信所需的所有信息更新应用。

    key: "<Your Azure Cosmos account key>"

运行应用

  1. 在终端中运行 npm install，安装“@azure/cosmos”npm 包

  2. 在终端中运行 node app.js，启动 node 应用程序。

  3. 之前在本快速入门中创建的两个项已列出。新项已创建。 该项上的“isComplete”标志更新为“true”，最后该项被删除。

可以继续试用此示例应用程序，也可以返回到数据资源管理器来修改和处理数据。

在 Azure 门户中查看 SLA

Azure 门户监视 Cosmos DB 帐户吞吐量、存储、可用性、延迟和一致性。 与 Azure Cosmos DB 服务级别协议 (SLA) 关联的指标的图表显示与实际性能相比的 SLA 值。 此套指标使得监视 SLA 十分透明。

若要查看指标和 SLA，请执行以下操作：

  1. 在 Cosmos DB 帐户的导航菜单中选择“指标”。

  2. 选择一个选项卡，如“延迟”，然后选择右侧的时间范围。 比较图表上的“实际”和“SLA”线。

    Azure Cosmos DB metrics suite

  3. 查看其他选项卡上的指标。

后续步骤

在本快速入门中，你已了解了如何创建 Azure Cosmos DB 帐户、如何使用数据资源管理器创建容器，以及如何运行 Node.js 应用。 现在可以将其他数据导入 Azure Cosmos DB 帐户了。

尝试为迁移到 Azure Cosmos DB 进行容量规划？ 可以使用有关现有数据库群集的信息进行容量规划。

将数据导入 Azure Cosmos DB