快速入门:使用 .NET SDK 和 Azure Cosmos DB 生成表 API 应用

适用于: 表 API

本快速入门演示如何从 .NET 应用程序访问 Azure Cosmos DB 表 API。 Cosmos DB 表 API 是一种无架构数据存储,允许应用程序在云中存储结构化 NoSQL 数据。 由于数据存储在无架构设计中,因此将具有新特性的对象添加到表中时,系统会自动向表中添加新属性(列)。

.NET 应用程序可以使用 Azure.Data.Tables NuGet 包访问 Cosmos DB 表 API。 Azure.Data.Tables 包是 .NET Standard 2.0 库,适用于 .NET Framework(4.7.2 及更高版本)和 .NET Core(2.0 及更高版本)应用程序。

先决条件

示例应用程序采用 .NET Core 3.1 进行编写,不过原则同时适用于 .NET Framework 和 .NET Core 应用程序。 可以使用 Visual StudioVisual Studio for MacVisual Studio Code 作为 IDE。

如果还没有 Azure 订阅,可以在开始前创建一个试用帐户

示例应用程序

可以从存储库 https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-dotnet 克隆或下载本教程的示例应用程序。 入门应用和完整应用都包含在示例存储库中。

git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-dotnet

示例应用程序使用天气数据作为示例来演示表 API 的功能。 表示天气观察值的对象使用表 API 进行存储和检索,包括存储具有附加属性的对象以演示表 API 的无架构功能。

已完成应用程序的屏幕截图,其中显示了使用表 API 存储在 Cosmos DB 中的数据。

1 - 创建 Azure Cosmos DB 帐户

首先需要创建将包含在应用程序中使用的表的 Cosmos DB 表 API 帐户。 可以使用 Azure 门户、Azure CLI 或 Azure PowerShell 执行此操作。

登录 Azure 门户,并按照以下步骤创建 Cosmos DB 帐户。

说明 屏幕快照
在 Azure 门户中:
  1. 在 Azure 门户顶部的搜索栏中,输入“cosmos db”。
  2. 在搜索栏下方出现的菜单上的“服务”下,选择标有“Azure Cosmos DB”的项。
显示如何使用顶部工具栏中的搜索框在 Azure 中查找 Cosmos DB 帐户的屏幕截图。
在“Azure Cosmos DB”页上,选择“+创建”。 显示 Azure 中 Cosmos DB 帐户页上的“创建”按钮位置的屏幕截图。
在“创建 Azure Cosmos DB 帐户”页上填写表单,如下所示。
  1. 通过选择“资源组”下的“新建”链接,为名为 rg-msdocs-tables-sdk-demo 的 Azure Cosmos DB 帐户创建新的资源组。

  2. 为 Azure Cosmos DB 帐户指定名称 cosmos-msdocs-tables-sdk-demo-XYZ,其中的 XYZ 是三个任意的随机字符,用于创建独一无二的帐户名称。 Azure Cosmos DB 帐户名称必须为 3 到 44 个字符长,并且只能包含小写字母、数字或连字符 (-)。

  3. 选择 Azure Cosmos DB 帐户的区域。

  4. 在“容量模式”下,为此示例选择“预配吞吐量”。

  5. 对于此示例,请在“应用免费层折扣”下选择“应用”。

  6. 选择屏幕底部的“查看 + 创建”按钮,然后选择摘要屏幕上的“创建”以创建 Azure Cosmos DB 帐户。 此过程可能需要数分钟。

显示如何在 Cosmos DB 帐户创建页上填写字段的屏幕截图。

2 - 创建表

接下来,需要在 Cosmos DB 帐户中创建表,以供应用程序使用。 与传统数据库不同,只需指定表的名称,无需指定表中的属性(列)。 将数据加载到表中时,属性(列)会根据需要自动创建。

Azure 门户中,完成以下步骤,以在 Cosmos DB 帐户中创建表。

说明 屏幕快照
在Azure 门户,导航到 Azure Cosmos DB 帐户的概述页。 可以通过在顶部搜索栏中键入 Cosmos DB 帐户的名称 (cosmos-msdocs-tables-sdk-demo-XYZ) 并在资源标题下进行查看,导航到 Cosmos DB 帐户的概述页。选择 Azure Cosmos DB 帐户的名称以转到概述页。 显示如何使用顶部工具栏中的搜索框查找 Cosmos DB 帐户的屏幕截图。
在概述页面上,选择“+添加表”。 “新建表”对话框将从页面右侧滑出。 显示“添加表”按钮位置的屏幕截图。
在“新建表”对话框中填充表单,如下所示。
  1. 输入名称“WeatherData”作为“表 ID”。 这是表的名称。
  2. 对于此示例,请在“表吞吐量(自动缩放)”下选择“手动”。
  3. 在估计的 RU/秒下,使用默认值 400。
  4. 选择“确定”按钮以创建表。
显示 Cosmos DB 表的“新建表”对话框的屏幕截图。

3 - 获取 Cosmos DB 连接字符串

若要在 Cosmos DB 中访问表,应用需要 CosmosDB 存储帐户的表连接字符串。 可以使用 Azure 门户、Azure CLI 或 Azure PowerShell 检索该连接字符串。

说明 屏幕快照
在 Azure Cosmos DB 帐户页左侧的“设置”标题下找到名为“连接字符串”的菜单项,并将其选中。 此时会转到一个页面,你可以在其中检索 Azure Cosmos DB 帐户的连接字符串。 显示 Cosmos DB 页面上的连接字符串链接位置的屏幕截图。
复制“主连接字符串”值以在应用程序中使用。 显示在应用程序中选择和使用的连接字符串的屏幕截图。

Cosmos DB 帐户的连接字符串被视为应用机密,必须如同任何其他应用机密或密码一样进行保护。 此示例使用机密管理器工具在开发过程中存储连接字符串,并提供给应用程序使用。 可以从 Visual Studio 或 .NET CLI 访问机密管理器工具。

若要从 Visual Studio 打开机密管理器工具,请右键单击项目,然后从上下文菜单中选择“管理用户机密”。 这会打开项目的 secrets.json 文件。 将该文件的内容替换为下面的 JSON,从而替换为 Cosmos DB 表连接字符串。

{
  "ConnectionStrings": {
    "CosmosTableApi": "<cosmos db table connection string>"
  }  
}

4 - 安装 Azure.Data.Tables NuGet 包

若要从 .NET 应用程序访问 Cosmos DB 表 API,请安装 Azure.Data.Tables NuGet 包。

Install-Package Azure.Data.Tables

5 - 在 Startup.cs 中配置表客户端

Azure SDK 使用客户端对象与 Azure 通信,以对 Azure 执行不同的操作。 TableClient 对象是用于与 Cosmos DB 表 API 通信的对象。

应用程序通常会为每个表创建单个 TableClient 对象,以在整个应用程序中使用。 建议使用依赖项注入 (DI) 并将 TableClient 对象注册为单一实例来实现此目的。 有关将 DI 与 Azure SDK 一起使用的详细信息,请参阅依赖项 注入与用于 .NET 的 Azure SDK

在应用程序的 Startup.cs 文件中,编辑 ConfigureServices() 方法以匹配以下代码片段:

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages()
        .AddMvcOptions(options =>
        {
            options.Filters.Add(new ValidationFilter());
        });

    var connectionString = Configuration.GetConnectionString("CosmosTableApi");
    services.AddSingleton<TableClient>(new TableClient(connectionString, "WeatherData"));

    services.AddSingleton<TablesService>();
}

还需要将下面的 using 语句添加到 Startup.cs 文件顶部。

using Azure.Data.Tables;

6 - 实现 Cosmos DB 表操作

示例应用的所有 Cosmos DB 表操作都在位于 Services 目录中的 TableService 类中实现。 需要在此文件顶部导入 AzureAzure.Data.Tables 命名空间,以使用 Azure.Data.Tables SDK 包中的对象。

using Azure;
using Azure.Data.Tables;

TableService 类的开头,添加用于 TableClient 对象的成员变量以及一个构造函数,以允许将 TableClient 对象注入该类。

private TableClient _tableClient;

public TablesService(TableClient tableClient)
{
    _tableClient = tableClient;
}

从表中获取行

TableClient 类包含名为 Query 的方法,可用于从表中选择行。 在此示例中,由于未向该方法传递任何参数,因此会从表中选择所有行。

该方法还采用类型为 ITableEntity 的泛型参数,该参数指定返回的模型类数据。 在此例中,将使用内置类 TableEntity,这意味着 Query 方法会返回 Pageable\<TableEntity\> 集合作为其结果。

public IEnumerable<WeatherDataModel> GetAllRows()
{
    Pageable<TableEntity> entities = _tableClient.Query<TableEntity>();

    return entities.Select(e => MapTableEntityToWeatherDataModel(e));
}

Azure.Data.Tables 包中定义的 TableEntity 类具有适用于表中的分区键和行键值的属性。 这两个值共同表示表中行的唯一键。 在此示例应用程序中,气象站的名称(城市)存储在分区键中,观测日期/时间存储在行键中。 所有其他属性(温度、湿度、风速)存储在 TableEntity 对象中的字典内。

常见做法是将 TableEntity 对象映射到具有你自己定义的对象。 示例应用程序在 Models 目录中定义了一个类 WeatherDataModel 来实现此目的。 此类具有分区键和行键将映射到的气象站名称和观察日期属性,可为这些值提供更有意义的属性名称。 它随后使用字典将所有其他属性存储在对象中。 这是使用表存储时的常见模式,因为行可以具有任意数量的任意属性,并且我们希望模型对象能够捕获所有这些属性。 此类还包含列出类中的属性的方法。

public class WeatherDataModel 
{
    // Captures all of the weather data properties -- temp, humidity, wind speed, etc
    private Dictionary<string, object> _properties = new Dictionary<string, object>();

    public string StationName { get; set; }

    public string ObservationDate { get; set; }

    public DateTimeOffset? Timestamp { get; set; }

    public string Etag { get; set; }

    public object this[string name] 
    { 
        get => ( ContainsProperty(name)) ? _properties[name] : null; 
        set => _properties[name] = value; 
    }

    public ICollection<string> PropertyNames => _properties.Keys;

    public int PropertyCount => _properties.Count;

    public bool ContainsProperty(string name) => _properties.ContainsKey(name);       
}

MapTableEntityToWeatherDataModel 方法用于将 TableEntity 对象映射到 WeatherDataModel 对象。 TableEntity 对象包含一个 Keys 属性,用于获取对象的表中包含的所有属性名称(实际上是表中此行的列名称)。 MapTableEntityToWeatherDataModel 方法直接映射 PartitionKeyRowKeyTimestampEtag 属性,然后使用 Keys 属性循环访问 TableEntity 对象中的其他属性,并将这些属性映射到 WeatherDataModel 对象(不包括已直接映射的属性)。

编辑 MapTableEntityToWeatherDataModel 方法中的代码以匹配以下代码块。

public WeatherDataModel MapTableEntityToWeatherDataModel(TableEntity entity)
{
    WeatherDataModel observation = new WeatherDataModel();
    observation.StationName = entity.PartitionKey;
    observation.ObservationDate = entity.RowKey;
    observation.Timestamp = entity.Timestamp;
    observation.Etag = entity.ETag.ToString();

    var measurements = entity.Keys.Where(key => !EXCLUDE_TABLE_ENTITY_KEYS.Contains(key));
    foreach (var key in measurements)
    {
        observation[key] = entity[key];
    }
    return observation;            
}

筛选从表返回的行

若要筛选从表中返回的行,可以将 OData 样式筛选字符串传递给 Query 方法。 例如,如果你想要获取 2021 年 7 月 1 日午夜到 2021 年 7 月 2 日午夜(含)的所有上海天气读数,可以传入以下筛选字符串。

PartitionKey eq 'Shanghai' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'

可以在 OData 网站上的筛选器系统查询选项部分中查看所有 OData 筛选器运算符。

在示例应用程序中,FilterResultsInputModel 对象旨在捕获用户提供的任何筛选条件。

public class FilterResultsInputModel : IValidatableObject
{
    public string PartitionKey { get; set; }
    public string RowKeyDateStart { get; set; }
    public string RowKeyTimeStart { get; set; }
    public string RowKeyDateEnd { get; set; }
    public string RowKeyTimeEnd { get; set; }
    [Range(-100, +200)]
    public double? MinTemperature { get; set; }
    [Range(-100,200)]
    public double? MaxTemperature { get; set; }
    [Range(0, 300)]
    public double? MinPrecipitation { get; set; }
    [Range(0,300)]
    public double? MaxPrecipitation { get; set; }
}

将此对象传递到 TableService 类中的 GetFilteredRows 方法时,它会为每个非 null 属性值创建一个筛选器字符串。 它随后会使用“and”子句将所有值联接在一起,以创建合并筛选器字符串。 此合并筛选器字符串会传递到 TableClient 对象上的 Query 方法,仅返回与筛选器字符串匹配的行。 可以在代码中使用类似方法,根据应用程序的要求构造合适的筛选器字符串。

public IEnumerable<WeatherDataModel> GetFilteredRows(FilterResultsInputModel inputModel)
{
    List<string> filters = new List<string>();

    if (!String.IsNullOrEmpty(inputModel.PartitionKey))
        filters.Add($"PartitionKey eq '{inputModel.PartitionKey}'");
    if (!String.IsNullOrEmpty(inputModel.RowKeyDateStart) && !String.IsNullOrEmpty(inputModel.RowKeyTimeStart))
        filters.Add($"RowKey ge '{inputModel.RowKeyDateStart} {inputModel.RowKeyTimeStart}'");
    if (!String.IsNullOrEmpty(inputModel.RowKeyDateEnd) && !String.IsNullOrEmpty(inputModel.RowKeyTimeEnd))
        filters.Add($"RowKey le '{inputModel.RowKeyDateEnd} {inputModel.RowKeyTimeEnd}'");
    if (inputModel.MinTemperature.HasValue)
        filters.Add($"Temperature ge {inputModel.MinTemperature.Value}");
    if (inputModel.MaxTemperature.HasValue)
        filters.Add($"Temperature le {inputModel.MaxTemperature.Value}");
    if (inputModel.MinPrecipitation.HasValue)
        filters.Add($"Precipitation ge {inputModel.MinTemperature.Value}");
    if (inputModel.MaxPrecipitation.HasValue)
        filters.Add($"Precipitation le {inputModel.MaxTemperature.Value}");

    string filter = String.Join(" and ", filters);
    Pageable<TableEntity> entities = _tableClient.Query<TableEntity>(filter);

    return entities.Select(e => MapTableEntityToWeatherDataModel(e));
}

使用 TableEntity 对象插入数据

将数据添加到表的最简单方法是使用 TableEntity 对象。 在此示例中,数据会从输入模型对象映射到 TableEntity 对象。 输入对象中表示气象站名称和观察日期/时间的属性分别映射到 PartitionKeyRowKey 属性,这些属性共同构成表中行的唯一键。 输入模型对象上的其他属性随后会映射到 TableEntity 对象上的字典属性。 最后,TableClient 对象上的 AddEntity 方法用于将数据插入表中。

修改示例应用程序中的 InsertTableEntity 类,以包含以下代码。

public void InsertTableEntity(WeatherInputModel model)
{
    TableEntity entity = new TableEntity();
    entity.PartitionKey = model.StationName;
    entity.RowKey = $"{model.ObservationDate} {model.ObservationTime}";

    // The other values are added like a items to a dictionary
    entity["Temperature"] = model.Temperature;
    entity["Humidity"] = model.Humidity;
    entity["Barometer"] = model.Barometer;
    entity["WindDirection"] = model.WindDirection;
    entity["WindSpeed"] = model.WindSpeed;
    entity["Precipitation"] = model.Precipitation;

    _tableClient.AddEntity(entity);
}

使用 TableEntity 对象更新插入数据

如果尝试向表中插入的行具有该表中已存在的分区键/行键组合,则会收到错误。 因此,在向表添加行时,通常最好使用 UpsertEntity 而不是 AddEntity 方法。 如果表中已存在给定分区键/行键组合,则 UpsertEntity 方法会更新现有行。 否则,行会添加到表中。

public void UpsertTableEntity(WeatherInputModel model)
{
    TableEntity entity = new TableEntity();
    entity.PartitionKey = model.StationName;
    entity.RowKey = $"{model.ObservationDate} {model.ObservationTime}";

    // The other values are added like a items to a dictionary
    entity["Temperature"] = model.Temperature;
    entity["Humidity"] = model.Humidity;
    entity["Barometer"] = model.Barometer;
    entity["WindDirection"] = model.WindDirection;
    entity["WindSpeed"] = model.WindSpeed;
    entity["Precipitation"] = model.Precipitation;

    _tableClient.UpsertEntity(entity);
}

使用变量属性插入或更新插入数据

使用 Cosmos DB 表 API 的优点之一是,如果要加载到表的对象包含任何新属性,则这些属性会自动添加到表中并且值存储在 Cosmos DB 中。 无需如同传统数据库中一样,运行 ALTER TABLE 等 DDL 语句来添加列。

在处理可能会随着时间推移添加或修改需要捕获的数据的数据源时,或者在不同的输入向应用程序提供不同的数据时,此模型可使应用程序具有灵活性。 在示例应用程序中,我们可以模拟一个不仅发送基本天气数据,而且还发送一些附加值的气象站。 首次将具有这些新属性的对象存储在表中时,对应属性(列)会自动添加到表中。

在示例应用程序中,ExpandableWeatherObject 类围绕内部字典进行构建,以支持对象上的任何属性集。 此类表示对象需要包含任意属性集时的典型模式。

public class ExpandableWeatherObject
{
    public Dictionary<string, object> _properties = new Dictionary<string, object>();

    public string StationName { get; set; }

    public string ObservationDate { get; set; }

    public object this[string name]
    {
        get => (ContainsProperty(name)) ? _properties[name] : null;
        set => _properties[name] = value;
    }

    public ICollection<string> PropertyNames => _properties.Keys;

    public int PropertyCount => _properties.Count;

    public bool ContainsProperty(string name) => _properties.ContainsKey(name);
}

若要使用表 API 插入或更新插入 此类对象,请将可扩充对象的属性映射到 TableEntity 对象,并根据需要对 TableClient 对象使用 AddEntityUpsertEntity 方法。

public void InsertExpandableData(ExpandableWeatherObject weatherObject)
{
    TableEntity entity = new TableEntity();
    entity.PartitionKey = weatherObject.StationName;
    entity.RowKey = weatherObject.ObservationDate;

    foreach (string propertyName in weatherObject.PropertyNames)
    {
        var value = weatherObject[propertyName];
        entity[propertyName] = value;
    }
    _tableClient.AddEntity(entity);
}

public void UpsertExpandableData(ExpandableWeatherObject weatherObject)
{
    TableEntity entity = new TableEntity();
    entity.PartitionKey = weatherObject.StationName;
    entity.RowKey = weatherObject.ObservationDate;

    foreach (string propertyName in weatherObject.PropertyNames)
    {
        var value = weatherObject[propertyName];
        entity[propertyName] = value;
    }
    _tableClient.UpsertEntity(entity);
}

更新条目

可以通过对 TableClient 对象调用 UpdateEntity 方法来更新实体。 由于使用表 API 存储的实体(行)可以包含任意属性集,因此创建基于字典对象的更新对象(类似于前面讨论的 ExpandableWeatherObject)通常很有用。 在此情况下,唯一的区别是添加 Etag 属性,该属性用于在更新期间进行并发控制。

public class UpdateWeatherObject
{
    public Dictionary<string, object> _properties = new Dictionary<string, object>();

    public string StationName { get; set; }
    public string ObservationDate { get; set; }
    public string Etag { get; set; }

    public object this[string name]
    {
        get => (ContainsProperty(name)) ? _properties[name] : null;
        set => _properties[name] = value;
    }

    public ICollection<string> PropertyNames => _properties.Keys;

    public int PropertyCount => _properties.Count;

    public bool ContainsProperty(string name) => _properties.ContainsKey(name);
}

在示例应用中,此对象会传递到 TableService 类中的 UpdateEntity 方法。 此方法首先对 TableClient 使用 GetEntity 方法,从表 API 加载现有实体。 它随后更新该实体对象,并使用 UpdateEntity 方法将更新保存到数据库。 请注意 UpdateEntity 方法如何获取对象的当前 Etag,以确保对象自最初加载以来未发生更改。 如果希望无论如何都更新实体,则可以将 Etag.Any 值传递到 UpdateEntity 方法。

public void UpdateEntity(UpdateWeatherObject weatherObject)
{
    string partitionKey = weatherObject.StationName;
    string rowKey = weatherObject.ObservationDate;

    // Use the partition key and row key to get the entity
    TableEntity entity = _tableClient.GetEntity<TableEntity>(partitionKey, rowKey).Value;

    foreach (string propertyName in weatherObject.PropertyNames)
    {
        var value = weatherObject[propertyName];
        entity[propertyName] = value;
    }

    _tableClient.UpdateEntity(entity, new ETag(weatherObject.Etag));
}

删除实体

若要从表中删除实体,请使用对象的分区键和行键对 TableClient 对象调用 DeleteEntity 方法。

public void RemoveEntity(string partitionKey, string rowKey)
{
    _tableClient.DeleteEntity(partitionKey, rowKey);           
}

7 - 运行代码

运行示例应用程序以与 Cosmos DB 表 API 交互。 首次运行应用程序时没有数据,因为表为空。 使用应用程序顶部的任何按钮将数据添加到表。

应用程序的屏幕截图,其中显示用于通过表 API 将数据插入到 Cosmos DB 中的按钮位置。

选择“使用表实体插入”按钮会打开一个对话框,使你可以使用 TableEntity 对象插入或更新插入新行。

应用程序的屏幕截图,其中显示用于通过 TableEntity 对象插入数据的对话框。

选择“使用可扩充数据插入”按钮会打开一个对话框,使你可以使用自定义属性插入对象,演示了 Cosmos DB 表 API 如何在需要时自动向表添加属性(列)。 使用“添加自定义字段”按钮添加一个或多个新属性并演示此功能。

应用程序的屏幕截图,其中显示用于通过带有自定义字段的对象插入数据的对话框。

使用“插入示例数据”按钮将一些示例数据加载到 Cosmos DB 表中。

应用程序的屏幕截图,其中显示示例数据插入按钮的位置。

选择顶部菜单中的“筛选结果”项以进入“筛选结果”页面。 在此页面上,填写筛选条件以演示如何构建筛选子句并传递到 Cosmos DB 表 API。

应用程序的屏幕截图,其中显示筛选结果页面,并突出显示了用于导航到该页面的菜单项。

清理资源

完成示例应用程序后,应从你的 Azure 帐户中删除与本文相关的所有 Azure 资源。 可以通过删除资源组来进行这种清理。

可以在 Azure 门户中执行以下操作来删除资源组。

说明 屏幕快照
若要转到资源组,在搜索栏中键入资源组的名称。 然后在“资源组”选项卡上,选择资源组的名称。 显示如何搜索资源组的屏幕截图。
从“资源组”页顶部的工具栏中选择“删除资源组”。 显示“删除资源组”按钮位置的屏幕截图。
屏幕右侧会弹出一个对话框,要求确认是否删除该资源组。
  1. 按说明在文本框中键入确认删除的资源组的完整名称。
  2. 选择页面底部的“删除”按钮。
显示用于删除资源组的确认对话框的屏幕截图。

后续步骤

在本快速入门教程中,已了解如何创建 Azure Cosmos DB 帐户、使用数据资源管理器创建表和运行应用。 现在可以使用表 API 进行数据查询了。