Azure.Data.Tables 12.9.0

适用于 .NET 的 Azure 表客户端库

Azure 表存储是一种将大量结构化NoSQL数据存储在云中的服务，它提供了一个无模式设计的键/属性存储。

Azure Cosmos DB 为需要像

• 托管全球分布
• 全球专用吞吐量
• 99.9%的尾端低于10毫秒的延迟
• 保证高可用性
• 自动二级索引

Azure 表客户端库可以无缝地针对Azure Table存储或Azure Cosmos DB表服务端点，无需更改代码。

源代码 | 包 (NuGet) | API参考文档 | 示例 | 变更记录

入门指南

安装包

使用 NuGet 安装 Azure Tables 客户端库 for .NET

dotnet add package Azure.Data.Tables

先决条件

• 一个 Azure 订阅。
• 一个具有指定的 Azure Table API 的现有 Azure 存储账户或 Azure Cosmos DB 数据库。

如果您需要创建这些中的任何一个，可以使用 Azure CLI。

创建存储账户

在订阅 MySubscription 中的 West US 区域内创建一个名为 mystorageaccount 的存储账户，所属资源组为 MyResourceGroup。

az storage account create -n mystorageaccount -g MyResourceGroup -l westus --subscription MySubscription

创建 Cosmos DB

在 MyResourceGroup 资源组中创建一个名为 MyCosmosDBDatabaseAccount 的 Cosmos DB 账户，并在该账户中创建一个名为 MyTableName 的表。

az cosmosdb create --name MyCosmosDBDatabaseAccount --capabilities EnableTable --resource-group MyResourceGroup --subscription MySubscription

az cosmosdb table create --name MyTableName --resource-group MyResourceGroup --account-name MyCosmosDBDatabaseAccount

客户端认证

了解更多关于认证选项 （包括连接字符串、共享密钥、共享密钥签名和 TokenCredentials） 的信息，请参阅我们的示例。

关键概念

• TableServiceClient - 提供创建、列出和删除表等与 Table 服务级别交互方法的客户端。
• TableClient - 提供创建、查询和删除表内实体等与单个表实体级别交互方法的客户端。
• Table - 表以集合的形式存储数据。
• Entity - 实体类似于行。一个实体具有一个主键和一组属性。属性是一个名称值对，类似于列。

Table 服务常见的用途包括

• 存储 TB 级的 structed 数据，可服务于规模化的网络应用程序
• 存储无需复杂联合、外键或存储过程的数據集，可以进行反规范化以提高访问速度
• 使用集群索引快速查询数据
• 使用 OData 协议和 LINQ 过滤表达式访问数据

线程安全

我们保证所有客户端实例方法都是线程安全且相互独立的 (指导原则)。这确保了重用客户端实例的建议总是安全的，即使在多线程的环境中也是如此。

其他概念

客户端选项 | 访问响应 | 长时间运行的操作 | 处理失败 | 诊断 | Mocking | 客户端生命周期

示例

• 创建 Table 服务客户端
  • 创建 Azure 表
  • 获取 Azure 表
  • 删除 Azure 表
• 创建 Table 客户端
  • 添加表实体
  • 查询表实体
  • 删除表实体

创建 Table 服务客户端

首先，我们需要构建一个 TableServiceClient。

// Construct a new "TableServiceClient using a TableSharedKeyCredential.

var serviceClient = new TableServiceClient(
    new Uri(storageUri),
    new TableSharedKeyCredential(accountName, storageAccountKey));

创建 Azure 表

接下来，我们可以创建一个新的表。

// Create a new table. The TableItem class stores properties of the created table.
TableItem table = serviceClient.CreateTableIfNotExists(tableName);
Console.WriteLine($"The created table's name is {table.Name}.");

获取 Azure 表

可以使用 OData 过滤查询现有的 Azure 表集合。

// Use the <see cref="TableServiceClient"> to query the service. Passing in OData filter strings is optional.

Pageable<TableItem> queryTableResults = serviceClient.Query(filter: $"TableName eq '{tableName}'");

Console.WriteLine("The following are the names of the tables in the query results:");

// Iterate the <see cref="Pageable"> in order to access queried tables.

foreach (TableItem table in queryTableResults)
{
    Console.WriteLine(table.Name);
}

删除 Azure 表

可以将单独的表从服务中删除。

// Deletes the table made previously.
serviceClient.DeleteTable(tableName);

创建 Table 客户端

要与表实体交互，我们必须首先构建一个 TableClient。

// Construct a new <see cref="TableClient" /> using a <see cref="TableSharedKeyCredential" />.
var tableClient = new TableClient(
    new Uri(storageUri),
    tableName,
    new TableSharedKeyCredential(accountName, storageAccountKey));

// Create the table in the service.
tableClient.Create();

添加表实体

让我们定义一个新的 TableEntity，以便我们可以将其添加到表中。

// Make a dictionary entity by defining a <see cref="TableEntity">.
var tableEntity = new TableEntity(partitionKey, rowKey)
{
    { "Product", "Marker Set" },
    { "Price", 5.00 },
    { "Quantity", 21 }
};

Console.WriteLine($"{tableEntity.RowKey}: {tableEntity["Product"]} costs ${tableEntity.GetDouble("Price")}.");

使用 TableClient 我们现在可以将我们的新实体添加到表中。

// Add the newly created entity.
tableClient.AddEntity(tableEntity);

查询表实体

为了检查现有表实体集，我们可以使用OData过滤器查询表。

Pageable<TableEntity> queryResultsFilter = tableClient.Query<TableEntity>(filter: $"PartitionKey eq '{partitionKey}'");

// Iterate the <see cref="Pageable"> to access all queried entities.
foreach (TableEntity qEntity in queryResultsFilter)
{
    Console.WriteLine($"{qEntity.GetString("Product")}: {qEntity.GetDouble("Price")}");
}

Console.WriteLine($"The query returned {queryResultsFilter.Count()} entities.");

如果您更喜欢LINQ查询表达式风格，我们也可以使用该语法来查询表。为了演示这个语法，您需要一个如下所示的强类型模型：

// Define a strongly typed entity by implementing the ITableEntity interface.
public class OfficeSupplyEntity : ITableEntity
{
    public string Product { get; set; }
    public double Price { get; set; }
    public int Quantity { get; set; }
    public string PartitionKey { get; set; }
    public string RowKey { get; set; }
    public DateTimeOffset? Timestamp { get; set; }
    public ETag ETag { get; set; }
}

给定了这个模型类定义，以下是编写查询的方式

double priceCutOff = 6.00;
Pageable<OfficeSupplyEntity> queryResultsLINQ = tableClient.Query<OfficeSupplyEntity>(ent => ent.Price >= priceCutOff);

删除表实体

如果我们不再需要我们的新表实体，它可以被删除。

// Delete the entity given the partition and row key.
tableClient.DeleteEntity(partitionKey, rowKey);

故障排除

当使用Azure表库时，服务返回的错误是通过与REST API请求相同的HTTP状态代码报告的。

例如，如果您尝试创建一个已存在的表，将返回一个409错误，表示“冲突”。

// Construct a new TableClient using a connection string.

var client = new TableClient(
    connectionString,
    tableName);

// Create the table if it doesn't already exist.

client.CreateIfNotExists();

// Now attempt to create the same table unconditionally.

try
{
    client.Create();
}
catch (RequestFailedException ex) when (ex.Status == (int)HttpStatusCode.Conflict)
{
    Console.WriteLine(ex.ToString());
}

设置控制台日志

查看日志最简单的方法是启用控制台日志。要创建一个输出消息到控制台的自定义日志监听器，请使用AzureEventSourceListener.CreateConsoleLogger方法。

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

有关其他日志机制的更多信息，请参阅这里。

下一步

开始使用我们的表示例。

已知问题

有关Cosmos DB表端点的当前已知问题列表，可以在这里找到。

贡献

本项目欢迎贡献和建议。大多数贡献都需要您同意一个《贡献者许可协议》（CLA），该协议声明您有权实际上授予我们使用您贡献的权利。有关详细信息，请访问cla.microsoft.com。

本项目已采用Microsoft开源准则。如需更多信息，请参阅准则常见问题解答，或通过[email protected]联系以获取任何额外的问题或评论。