快速入门：使用 Node.js 在 Azure Cosmos DB 中构建 API for Table 应用

示例应用程序

可以从存储库 https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js 克隆或下载本教程的示例应用程序。入门应用和完整应用都包含在示例存储库中。
git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js
示例应用程序使用天气数据作为示例来演示 API for Table 的功能。 表示天气观察值的对象使用 API for Table 进行存储和检索，其中就包括存储具有附加属性的对象以演示 API for Table 的无架构功能。
1 - 创建 Azure Cosmos DB 帐户
首先需要创建一个 Azure Cosmos DB Tables API 帐户，该帐户将包含应用程序中使用的表。  可以使用 Azure 门户、Azure CLI 或 Azure PowerShell 执行此操作。
Azure 门户
Azure CLI
Azure PowerShell
在“创建 Azure Cosmos DB 帐户 - Azure 表”页上填写表单，如下所示。
通过选择“资源组”下的“新建”链接，为名为 rg-msdocs-tables-sdk-demo 的存储帐户创建一个新资源组。
为存储帐户指定名称 cosmos-msdocs-tables-sdk-demo-XYZ，其中的 XYZ 是三个任意的随机字符，用于创建独一无二的帐户名称。  Azure Cosmos DB 帐户名称必须为 3 到 44 个字符长，并且只能包含小写字母、数字或连字符 (-)。
选择存储帐户的区域。
选择“标准”性能。
在“容量模式”下，为此示例选择“预配吞吐量”。
对于此示例，请在“应用免费层折扣”下选择“应用”。
选择屏幕底部的“查看 + 创建”按钮，然后选择摘要屏幕上的“创建”以创建 Azure Cosmos DB 帐户。 此过程可能需要数分钟。
使用 az cosmosdb create 命令来创建 Cosmos DB 帐户。 必须包含 --capabilities EnableTable 选项才能在 Azure Cosmos DB 中启用表存储。  由于所有 Azure 资源都必须包含在资源组中，因此以下代码片段还会为 Azure Cosmos DB 帐户创建资源组。
Azure Cosmos DB 帐户名称的长度必须介于 3 到 44 个字符之间，并且只能包含小写字母、数字和连字符 (-) 字符。  此外，Azure Cosmos DB 帐户名称在整个 Azure 中必须唯一。
可以在 Azure Cloud Shell 中或装有 Azure CLI 的工作站上运行 Azure CLI 命令。
Azure Cosmos DB 帐户创建过程通常需要几分钟才能完成。
LOCATION='eastus'
RESOURCE_GROUP_NAME='rg-msdocs-tables-sdk-demo'
COSMOS_ACCOUNT_NAME='cosmos-msdocs-tables-sdk-demo-123'    # change 123 to a unique set of characters for a unique name
COSMOS_TABLE_NAME='WeatherData'
az group create \
    --location $LOCATION \
    --name $RESOURCE_GROUP_NAME
az cosmosdb create \
    --name $COSMOS_ACCOUNT_NAME \
    --resource-group $RESOURCE_GROUP_NAME \
    --capabilities EnableTable
Azure Cosmos DB 帐户使用 New-AzCosmosDBAccount cmdlet 来创建。 必须包含 -ApiKind "Table" 选项才能在 Azure Cosmos DB 中启用表存储。  由于所有 Azure 资源都必须包含在资源组中，因此以下代码片段还会为 Azure Cosmos DB 帐户创建资源组。
Azure Cosmos DB 帐户名称的长度必须介于 3 到 44 个字符之间，并且只能包含小写字母、数字和连字符 (-) 字符。  Azure Cosmos DB 帐户名称还必须在 Azure 中是唯一的。
Azure PowerShell 命令可以在 Azure Cloud Shell 中或是安装了 Azure PowerShell 的工作站上运行。
Azure Cosmos DB 帐户创建过程通常需要几分钟才能完成。
$location = 'eastus'
$resourceGroupName = 'rg-msdocs-tables-sdk-demo'
$cosmosAccountName = 'cosmos-msdocs-tables-sdk-demo-123'  # change 123 to a unique set of characters for a unique name
# Create a resource group
New-AzResourceGroup `
    -Location $location `
    -Name $resourceGroupName
# Create an Azure Cosmos DB 
New-AzCosmosDBAccount `
    -Name $cosmosAccountName `
    -ResourceGroupName $resourceGroupName `
    -Location $location `
    -ApiKind "Table"
2 - 创建表
接下来，需要在 Azure Cosmos DB 帐户中创建表，以供应用程序使用。  与传统数据库不同，只需指定表的名称，无需指定表中的属性（列）。  将数据加载到表中时，属性（列）会根据需要自动创建。
Azure 门户
Azure CLI
Azure PowerShell
az cosmosdb table create \
    --account-name $COSMOS_ACCOUNT_NAME \
    --resource-group $RESOURCE_GROUP_NAME \
    --name $COSMOS_TABLE_NAME \
    --throughput 400
# Create the table for the application to use
New-AzCosmosDBTable `
    -Name $cosmosTableName `
    -AccountName $cosmosAccountName `
    -ResourceGroupName $resourceGroupName
3 - 获取 Azure Cosmos DB 连接字符串
若要访问 Azure Cosmos DB 中的表，你的应用需要 CosmosDB 存储帐户的表连接字符串。  可以使用 Azure 门户、Azure CLI 或 Azure PowerShell 检索该连接字符串。
Azure 门户
Azure CLI
Azure PowerShell
若要使用 Azure CLI 获取主表存储连接字符串，请使用 az cosmosdb keys list 命令及选项 --type connection-strings。  此命令使用 JMESPath 查询，以便仅显示主表连接字符串。
# This gets the primary Table connection string
az cosmosdb keys list \
    --type connection-strings \
    --resource-group $RESOURCE_GROUP_NAME \
    --name $COSMOS_ACCOUNT_NAME \
    --query "connectionStrings[?description=='Primary Table Connection String'].connectionString" \
    --output tsv
若要使用 Azure PowerShell 获取主表存储连接字符串，请使用 Get-AzCosmosDBAccountKey cmdlet。
# This gets the primary Table connection string
$(Get-AzCosmosDBAccountKey `
    -ResourceGroupName $resourceGroupName `
    -Name $cosmosAccountName `
    -Type "ConnectionStrings")."Primary Table Connection String"
Azure Cosmos DB 帐户的连接字符串被视为应用机密，必须像其他应用机密或密码一样加以保护。
4 - 安装适用于 JS 的 Azure 数据表 SDK
若要从 nodejs 应用程序访问 Azure Cosmos DB for Table，请安装 Azure 数据表 SDK 包。
  npm install @azure/data-tables
5 - 在 env.js 文件中配置表客户端
从 Azure 门户复制 Azure Cosmos DB 或存储帐户连接字符串，并使用复制的连接字符串创建 TableServiceClient 对象。 切换到文件夹 1-strater-app 或 2-completed-app。 然后，在 configure/env.js 文件中添加相应环境变量的值。
const env = {
  connectionString:"A connection string to an Azure Storage or Azure Cosmos DB account.",
  tableName: "WeatherData",
Azure SDK 使用客户端对象与 Azure 通信，以对 Azure 执行不同的操作。 TableClient 类是用于与 Azure Cosmos DB for Table 通信的类。 应用程序通常会为每个表创建单个 serviceClient 对象，以在整个应用程序中使用。
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
  env.connectionString,
  env.tableName
6 - 实现 Azure Cosmos DB 表操作
在“服务”目录下的 tableClient.js 文件的 serviceClient 对象中，实现示例应用的所有 Azure Cosmos DB 表操作。
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
  env.connectionString,
  env.tableName
从表中获取行
serviceClient 对象包含名为 listEntities 的方法，可用于从表中选择行。  在此示例中，由于未向该方法传递任何参数，因此会从表中选择所有行。
const allRowsEntities = serviceClient.listEntities();
筛选从表返回的行
若要筛选从表返回的行，可以将 OData 样式筛选器字符串传递到 listEntities 方法。 例如，如果要获取 2021 年 7 月 1 日午夜到 2021 年 7 月 2 日午夜（含）之间的所有芝加哥天气读数，则传入以下筛选器字符串。
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00' and RowKey le '2021-07-02 12:00'
可以在筛选器系统查询选项部分中查看 OData 网站上的所有 OData 筛选器运算符。
将 request.args 参数传递到 serviceClient 类中的 listEntities 方法时，它会为每个非 null 属性值创建一个筛选器字符串。 它随后会使用“and”子句将所有值联接在一起，以创建合并筛选器字符串。 此合并筛选器字符串会传递到 serviceClient 对象上的 listEntities 方法，仅返回与筛选器字符串匹配的行。 可以在代码中使用类似方法，根据应用程序的要求构造合适的筛选器字符串。
const filterEntities = async function (option) {
    You can query data according to existing fields
    option provides some conditions to query,eg partitionKey, rowKeyDateTimeStart, rowKeyDateTimeEnd
    minTemperature, maxTemperature, minPrecipitation, maxPrecipitation
  const filterEntitiesArray = [];
  const filters = [];
  if (option.partitionKey) {
    filters.push(`PartitionKey eq '${option.partitionKey}'`);
  if (option.rowKeyDateTimeStart) {
    filters.push(`RowKey ge '${option.rowKeyDateTimeStart}'`);
  if (option.rowKeyDateTimeEnd) {
    filters.push(`RowKey le '${option.rowKeyDateTimeEnd}'`);
  if (option.minTemperature !== null) {
    filters.push(`Temperature ge ${option.minTemperature}`);
  if (option.maxTemperature !== null) {
    filters.push(`Temperature le ${option.maxTemperature}`);
  if (option.minPrecipitation !== null) {
    filters.push(`Precipitation ge ${option.minPrecipitation}`);
  if (option.maxPrecipitation !== null) {
    filters.push(`Precipitation le ${option.maxPrecipitation}`);
  const res = serviceClient.listEntities({
    queryOptions: {
      filter: filters.join(" and "),
  for await (const entity of res) {
    filterEntitiesArray.push(entity);
  return filterEntitiesArray;
使用 TableEntity 对象插入数据
将数据添加到表的最简单方法是使用 TableEntity 对象。 在此示例中，数据会从输入模型对象映射到 TableEntity 对象。 输入对象中表示气象站名称和观察日期/时间的属性分别映射到 PartitionKey 和 RowKey 属性，这些属性共同构成表中行的唯一键。 输入模型对象上的其他属性随后会映射到 TableEntity 对象上的字典属性。 最后，serviceClient 对象上的 createEntity 方法用于将数据插入表中。
修改示例应用程序中的 insertEntity 函数，以包含以下代码。
const insertEntity = async function (entity) {
  await serviceClient.createEntity(entity);
使用 TableEntity 对象更新插入数据
如果尝试向表中插入的行具有该表中已存在的分区键/行键组合，则会收到错误。 因此，在向表添加行时，通常最好使用 upsertEntity 而不是 createEntity 方法。 如果表中已存在给定分区键/行键组合，则 upsertEntity 方法会更新现有行。 否则，行会添加到表中。
const upsertEntity = async function (entity) {
  await serviceClient.upsertEntity(entity, "Merge");
使用变量属性插入或更新插入数据
使用 Azure Cosmos DB for Table 的一个好处是，如果要加载到表的对象包含任何新属性，那这些属性会自动添加到表中并且值存储在 Azure Cosmos DB 中。 无需如同传统数据库中一样，运行 ALTER TABLE 等 DDL 语句来添加列。
在处理可能会随着时间推移添加或修改需要捕获的数据的数据源时，或者在不同的输入向应用程序提供不同的数据时，此模型可使应用程序具有灵活性。 在示例应用程序中，我们可以模拟一个不仅发送基本天气数据，而且还发送一些附加值的气象站。 首次将具有这些新属性的对象存储在表中时，对应属性（列）会自动添加到表中。
若要使用 API for Table 插入或更新插入此类对象，请将可扩充对象的属性映射到 TableEntity 对象，并根据需要对 serviceClient 对象使用 upsertEntity 或 createEntity 方法。
在示例应用程序中，upsertEntity 函数还可实现使用变量属性插入或更新插入数据的功能
const insertEntity = async function (entity) {
  await serviceClient.createEntity(entity);
const upsertEntity = async function (entity) {
  await serviceClient.upsertEntity(entity, "Merge");
可以通过对 serviceClient 对象调用 updateEntity 方法来更新实体。
在示例应用中，此对象会传递到 serviceClient 对象中的 upsertEntity 方法。 它更新该实体对象，并使用 upsertEntity 方法将更新保存到数据库。
const updateEntity = async function (entity) {
  await serviceClient.updateEntity(entity, "Replace");
7 - 运行代码
运行示例应用程序以与 Azure Cosmos DB for Table 交互。  首次运行应用程序时没有数据，因为表为空。  使用应用程序顶部的任何按钮将数据添加到表。
选择“使用表实体插入”按钮会打开一个对话框，使你可以使用 TableEntity 对象插入或更新插入新行。
选择“使用可扩展数据插入”按钮后，将会打开一个对话框，在其中可以插入具有自定义属性的对象，并演示 Azure Cosmos DB for Table 如何根据需要自动将属性（列）添加到表中。  使用“添加自定义字段”按钮添加一个或多个新属性并演示此功能。
使用“插入示例数据”按钮将一些示例数据加载到 Azure Cosmos DB 表中。
选择顶部菜单中的“筛选结果”项以进入“筛选结果”页面。  在此页面上，填写筛选条件以演示如何生成筛选子句并传递到 Azure Cosmos DB for Table。
完成示例应用程序后，应从你的 Azure 帐户中删除与本文相关的所有 Azure 资源。  可以通过删除资源组来进行这种清理。
Azure 门户
Azure CLI
Azure PowerShell
若要使用 Azure CLI 删除资源组，请结合要删除的资源组的名称使用 az group delete 命令。  删除某个资源组也会删除该资源组中包含的所有 Azure 资源。
az group delete --name $RESOURCE_GROUP_NAME
若要使用 Azure PowerShell 删除资源组，请结合要删除的资源组的名称使用 Remove-AzResourceGroup 命令。  删除某个资源组还会删除该资源组中包含的所有 Azure 资源。
Remove-AzResourceGroup -Name $resourceGroupName
在本快速入门教程中，已了解如何创建 Azure Cosmos DB 帐户、使用数据资源管理器创建表和运行应用。 现在可以使用 API for Table 进行数据查询了。
使用 API for Table 查询 Azure Cosmos DB