Biblioteca de clientes das Tabelas do Azure para .NET – versão 12.8.1

O Armazenamento de Tabelas do Azure é um serviço que armazena grandes quantidades de dados NoSQL estruturados na nuvem, fornecendo um repositório de chave/atributo com um design sem esquema.

O Azure Cosmos DB fornece uma API de Tabela para aplicativos escritos para o armazenamento de Tabelas do Azure que precisam de recursos premium, como:

• Distribuição global turnkey.
• Taxa de transferência dedicada em todo o mundo.
• Latências de dígito único em milissegundos no percentil 99.
• Alta disponibilidade garantia.
• Indexação automática secundária.

A biblioteca de cliente de Tabelas do azure pode ser direcionada diretamente o armazenamento de Tabelas do Azure ou os pontos de extremidade do serviço de tabelas do Azure Cosmos DB, sem alterações de código.

Código-fonte | Pacote (NuGet) | Documentação | de referência da APIAmostras | Log de Alterações

Introdução

Instalar o pacote

Instale a biblioteca de clientes das Tabelas do Azure para .NET com o NuGet:

dotnet add package Azure.Data.Tables

Pré-requisitos

• Uma assinatura do Azure.
• Uma conta de armazenamento do Azure existente ou um banco de dados do Azure Cosmos DB com a API de Tabela do Azure especificada.

Se você precisar criar uma dessas opções, poderá usar a CLI do Azure.

Criando uma conta de armazenamento

Crie uma conta mystorageaccount de armazenamento no grupo MyResourceGroup de recursos na assinatura MySubscription na região Oeste dos EUA.

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

Criando um Cosmos DB

Crie uma conta MyCosmosDBDatabaseAccount do Cosmos DB no grupo MyResourceGroup de recursos na assinatura MySubscription e uma tabela chamada MyTableName na conta.

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

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

Autenticar o cliente

Saiba mais sobre as opções de autenticação (incluindo Cadeias de Conexão, Chave Compartilhada, Assinaturas de Chave Compartilhada e TokenCredentials)em nossos exemplos.

Principais conceitos

• TableServiceClient – Cliente que fornece métodos para interagir no nível do Serviço tabela, como criar, listar e excluir tabelas
• TableClient – Cliente que fornece métodos para interagir em um nível de entidade de tabela, como criar, consultar e excluir entidades dentro de uma tabela.
• Table – As tabelas armazenam dados como coleções de entidades.
• Entity – As entidades são semelhantes às linhas. Uma entidade tem uma chave primária e um conjunto de propriedades. Uma propriedade é um par de valores de nome, semelhante a uma coluna.

Os usos comuns do serviço Tabela incluem:

• Armazenamento de TBs de dados estruturados capazes de atender a aplicativos de dimensionamento da Web
• Armazenar conjuntos de dados que não exigem junções complexas, chaves estrangeiras ou procedimentos armazenados e podem ser des normalizados para acesso rápido
• Consulta rápida de dados usando um índice clusterizado
• Acessando dados usando o protocolo OData e expressões de filtro LINQ

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Opções do | clienteAcessando a resposta | Operações de execução longa | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente

Exemplos

• Criar o cliente do serviço Tabela
  • Criar uma tabela do Azure
  • Obter uma tabela do Azure
  • Excluir uma tabela do Azure
• Criar o cliente tabela
  • Adicionar entidades de tabela
  • Consultar entidades de tabela
  • Excluir entidades de tabela

Criar o cliente do serviço Tabela

Primeiro, precisamos construir um TableServiceClient.

// Construct a new "TableServiceClient using a TableSharedKeyCredential.

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

Criar uma tabela do Azure

Em seguida, podemos criar uma nova tabela.

// 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}.");

Obter uma tabela do Azure

O conjunto de tabelas existentes do Azure pode ser consultas usando um filtro OData.

// 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);
}

Excluir uma tabela do Azure

Tabelas individuais podem ser excluídas do serviço.

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

Criar o cliente tabela

Para interagir com entidades de tabela, primeiro devemos construir um 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();

Adicionar entidades de tabela

Vamos definir um novo TableEntity para que possamos adicioná-lo à tabela.

// 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")}.");

Usando o TableClient , agora podemos adicionar nossa nova entidade à tabela.

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

Entidades da tabela de consulta

Para inspecionar o conjunto de entidades de tabela existentes, podemos consultar a tabela usando um filtro 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.");

Se você preferir expressões de consulta de estilo LINQ, podemos consultar a tabela usando essa sintaxe também. Para demonstrar essa sintaxe, você precisará de um modelo fortemente tipado, como o mostrado abaixo:

// 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; }
}

Dada essa definição de classe de modelo, veja como você escreveria uma consulta:

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

Excluir entidades de tabela

Se não precisarmos mais de nossa nova entidade de tabela, ela poderá ser excluída.

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

Solução de problemas

Ao usar a biblioteca de tabelas do Azure, os erros retornados pelo serviço são relatados usando os mesmos códigos http status retornados para solicitações da API REST.

Por exemplo, se você tentar criar uma tabela que já existe, um 409 erro será retornado, indicando "Conflito".

// 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());
}

Configuração do registro em log do console

A maneira mais simples de ver os logs é habilitar o log do console. Para criar um ouvinte de log do SDK do Azure que gera mensagens para o console, use o método AzureEventSourceListener.CreateConsoleLogger.

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

Para saber mais sobre outros mecanismos de registro em log, confira aqui.

Próximas etapas

Introdução aos nossos exemplos de Tabela.

Problemas conhecidos

Uma lista de problemas conhecidos no momento relacionados aos pontos de extremidade de tabela do Cosmos DB pode ser encontrada aqui.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.