通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：将 Azure Cosmos DB for Table 与用于 .NET 的 Azure SDK 配合使用

  • 项目
  • 适用于:
    ✅ Table

在本快速入门中，你将使用适用于 .NET 的 Azure SDK 部署一个基本的 Azure Cosmos DB for Table 应用程序。 Azure Cosmos DB for Table 是一种无架构数据存储，允许应用程序在云中存储结构化表数据。 你将了解如何使用用于 .NET 的 Azure SDK 在 Azure Cosmos DB 资源中创建表、行并执行基本任务。

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

先决条件

  • Azure 开发人员 CLI
  • Docker Desktop
  • .NET 9.0

如果没有 Azure 帐户，请在开始前创建一个免费帐户。

初始化项目

使用 Azure Developer CLI (azd) 创建 Azure Cosmos DB for Table 帐户并部署容器化示例应用程序。 示例应用程序使用客户端库来管理、创建、读取和查询示例数据。

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

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

    azd auth login

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

    azd init --template cosmos-db-table-dotnet-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 应用程序的屏幕截图。

安装客户端库

客户端库可通过 NuGet 作为 Azure.Data.Tables 包使用。

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

    cd ./src/web

  2. 使用 dotnet add package 安装 Azure.Data.Tables 包（如果尚未安装）。

    dotnet add package Azure.Data.Tables

  3. 打开并查看 src/web/Microsoft.Samples.Cosmos.Table.Quickstart.Web.csproj 文件以验证 Azure.Data.Tables 条目是否存在。

对象模型

名称 描述
TableServiceClient 此类是主要客户端类，用于管理帐户范围的元数据或数据库。
TableClient 此类表示帐户中表的客户端。

代码示例

模板中的示例代码使用名为 cosmicworks-products 的表。 cosmicworks-products 表包含每个产品的详细信息，例如名称、类别、数量、价格、唯一标识符和销售标志。 容器使用唯一标识符作为行键，使用类别作为分区键。

验证客户端

此示例创建 TableServiceClient 类的新实例。

DefaultAzureCredential credential = new();

TableServiceClient serviceClient = new(
    endpoint: new Uri("<azure-cosmos-db-table-account-endpoint>"),
    credential
);

获取表

此示例使用 TableServiceClient 类的 GetTableClient 方法创建 TableClient 类的实例。

TableClient client = serviceClient.GetTableClient(
    tableName: "<azure-cosmos-db-table-name>"
);

创建实体

在表中创建新实体的最简单方法是创建一个实现 ITableEntity 接口的类。 然后，可以将自己的属性添加到类中，以填充该表行中的数据列。

public record Product : ITableEntity
{
    public required string RowKey { get; set; }

    public required string PartitionKey { get; set; }

    public required string Name { get; set; }

    public required int Quantity { get; set; }

    public required decimal Price { get; set; }

    public required bool Clearance { get; set; }

    public ETag ETag { get; set; } = ETag.All;

    public DateTimeOffset? Timestamp { get; set; }
};

通过调用 TableClient.AddEntityAsync<T> 并使用 Product 类在表中创建实体。

Product entity = new()
{
    RowKey = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    PartitionKey = "gear-surf-surfboards",
    Name = "Surfboard",
    Quantity = 10,
    Price = 300.00m,
    Clearance = true
};

Response response = await client.UpsertEntityAsync<Product>(
    entity: entity,
    mode: TableUpdateMode.Replace
);

获取实体

可使用 TableClient.GetEntityAsync<T> 方法从表中检索特定实体。 提供 partitionKey 和 rowKey 作为参数，用于识别正确的行以执行该实体的快速点读取。

Response<Product> response = await client.GetEntityAsync<Product>(
    rowKey: "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    partitionKey: "gear-surf-surfboards"
);

查询实体

插入实体后，还可以使用 TableClient.Query<T> 方法运行查询以获取与特定筛选器匹配的所有实体。 此示例使用语言集成查询 (LINQ) 语法按类别筛选产品，这是使用类型 ITableEntity 模型（如 Product 类）的好处。

string category = "gear-surf-surfboards";

AsyncPageable<Product> results = client.QueryAsync<Product>(
    product => product.PartitionKey == category
);

通过使用异步循环遍历每个结果页来解析查询的分页结果。

List<Product> entities = new();
await foreach (Product product in results)
{
    entities.Add(product);
}

清理资源

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

azd down

相关内容