Guia de início rápido: Azure Cosmos DB for Table para .NET
APLICA-SE AO: Table
Este guia de início rápido mostra como usar o Azure Cosmos DB for Table em um aplicativo .NET. O Azure Cosmos DB for Table é um armazenamento de dados sem esquema para que os aplicativos armazenem dados de tabela estruturados na nuvem. Você aprenderá a criar tabelas, linhas e executar tarefas básicas em seu recurso do Azure Cosmos DB usando o Pacote Azure.Data.Tables (NuGet).
Observação
Os trechos de código de exemplo estão disponíveis no GitHub como um projeto .NET.
Documentação de referência da API para Table | Pacote Azure.Data.Tables (NuGet)
Pré-requisitos
- Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
- Conta do GitHub
- Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
- CLI do Desenvolvedor do Azure
- Docker Desktop
Configurando
Implante o contêiner de desenvolvimento deste projeto no seu ambiente. Depois, use o Azure Developer CLI (azd) para criar uma conta do Azure Cosmos DB for Table e implantar um aplicativo de exemplo conteinerizado. O aplicativo de exemplo usa a biblioteca de clientes para gerenciar, criar, ler e consultar dados de exemplo.
Importante
As contas do GitHub incluem um direito a horas de armazenamento e núcleo sem nenhum custo. Para obter mais informações, confira Horas de armazenamento e núcleo incluídas nas contas do GitHub.
Abra um terminal no diretório raiz do projeto.
Autentique-se no Azure Developer CLI usando
azd auth login
. Siga as etapas especificadas pela ferramenta para se autenticar na CLI usando suas credenciais preferenciais do Azure.azd auth login
Execute
azd init
para inicializar o projeto.azd init
Durante a inicialização, configure um nome de ambiente exclusivo.
Dica
O nome do ambiente também será usado como o nome do grupo de recursos de destino. Neste início rápido, considere o uso de
msdocs-cosmos-db
.Implante a conta do Azure Cosmos DB usando
azd up
. Os modelos do Bicep também implantam um aplicativo Web de exemplo.azd up
Durante o processo de provisionamento, selecione sua assinatura e o local desejado. Aguarde o processo de provisionamento ser concluído. O processo pode levar aproximadamente cinco minutos.
Depois que o provisionamento dos recursos do Azure for concluído, uma URL para o aplicativo Web em execução será incluída na saída.
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.
Use a URL no console para navegar até seu aplicativo Web no navegador. Observe a saída do aplicativo em execução.
Instalar a biblioteca de clientes
A biblioteca de clientes está disponível por meio do NuGet, como o pacote Microsoft.Azure.Cosmos
.
Abra um terminal e vá até a pasta
/src/web
.cd ./src/web
Se o pacote
Azure.Data.Tables
ainda não estiver instalado, instale-o usandodotnet add package
.dotnet add package Azure.Data.Tables
Instale também o pacote
Azure.Identity
, caso ainda não esteja instalado.dotnet add package Azure.Identity
Abra e analise o arquivo src/web/Cosmos.Samples.Table.Quickstart.Web.csproj para validar se as
Microsoft.Azure.Cosmos
e entradasAzure.Identity
ambas existem.
Exemplos de código
O código de exemplo descrito neste artigo cria uma tabela chamada adventureworks
. Cada linha da tabela contém os detalhes de um produto, como nome, categoria, quantidade e um indicador de venda. Cada produto também contém um identificador exclusivo.
Use a seguinte API para classes de tabela para interagir com esses recursos:
TableServiceClient
– Essa classe fornece métodos para executar operações de nível de serviço com o Azure Cosmos DB for Table.TableClient
– Essa classe permite que você interaja com tabelas hospedadas na API de Tabela do Azure Cosmos DB.TableEntity
– Essa classe é uma referência a uma linha em uma tabela que permite gerenciar propriedades e dados de coluna.
Autenticar o cliente
No diretório do projeto, abra o arquivo Program.cs. No editor, adicione uma diretiva de uso para Azure.Data.Tables
.
using Azure.Data.Tables;
Defina uma nova instância da classe TableServiceClient
usando o construtor e Environment.GetEnvironmentVariable
para ler as credenciais.
// New instance of the TableClient class
TableServiceClient tableServiceClient = new TableServiceClient(Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING"));
Criar uma tabela
Recupere uma instância do TableClient
usando a classe TableServiceClient
. Crie uma nova tabela se ela ainda não existir usando o TableClient.CreateIfNotExistsAsync
método noTableClient
. Esse método retorna uma referência à tabela existente ou recém-criada.
// New instance of TableClient class referencing the server-side table
TableClient tableClient = tableServiceClient.GetTableClient(
tableName: "adventureworks"
);
await tableClient.CreateIfNotExistsAsync();
Criar um item
A maneira mais fácil de criar um item em uma tabela é criar uma classe que implemente a interface ITableEntity
. Em seguida, você pode adicionar suas propriedades à classe para preencher colunas de dados nessa linha de tabela.
// C# record type for items in the table
public record Product : ITableEntity
{
public string RowKey { get; set; } = default!;
public string PartitionKey { get; set; } = default!;
public string Name { get; init; } = default!;
public int Quantity { get; init; }
public bool Sale { get; init; }
public ETag ETag { get; set; } = default!;
public DateTimeOffset? Timestamp { get; set; } = default!;
}
Crie um item na coleção usando a classe Product
chamando TableClient.AddEntityAsync<T>
.
// Create new item using composite key constructor
var prod1 = new Product()
{
RowKey = "68719518388",
PartitionKey = "gear-surf-surfboards",
Name = "Ocean Surfboard",
Quantity = 8,
Sale = true
};
// Add new item to server-side table
await tableClient.AddEntityAsync<Product>(prod1);
Obter um item
Você pode recuperar um item específico de uma tabela usando o método TableClient.GetEntityAsync<T>
. Forneça partitionKey
e rowKey
como parâmetros para identificar a linha correta a fim de executar uma leitura de ponto rápida desse item.
// Read a single item from container
var product = await tableClient.GetEntityAsync<Product>(
rowKey: "68719518388",
partitionKey: "gear-surf-surfboards"
);
Console.WriteLine("Single product:");
Console.WriteLine(product.Value.Name);
Itens de consulta
Depois de inserir um item, você também pode executar uma consulta para obter todos os itens que correspondem a um filtro específico usando o método TableClient.Query<T>
. Este exemplo filtra produtos por categoria usando a sintaxe Linq, que é um benefício do uso de modelos ITableEntity
tipados como a classe Product
.
Observação
Você também pode consultar itens usando a sintaxe OData. Você pode ver um exemplo dessa abordagem no tutorial Dados de Consulta.
// Read multiple items from container
var prod2 = new Product()
{
RowKey = "68719518390",
PartitionKey = "gear-surf-surfboards",
Name = "Sand Surfboard",
Quantity = 5,
Sale = false
};
await tableClient.AddEntityAsync<Product>(prod2);
var products = tableClient.Query<Product>(x => x.PartitionKey == "gear-surf-surfboards");
Console.WriteLine("Multiple products:");
foreach (var item in products)
{
Console.WriteLine(item.Name);
}
Executar o código
Este aplicativo cria uma tabela da API do Azure Cosmos DB for Table. O exemplo cria um item e lê exatamente o mesmo item de volta. Por fim, o exemplo cria um segundo item e executa uma consulta que deve retornar vários itens. A cada etapa, o exemplo envia metadados para o console sobre as etapas executadas.
Para executar o aplicativo, use um terminal para navegar até o diretório do aplicativo e execute o aplicativo.
dotnet run
A saída do aplicativo deve ser semelhante a este exemplo:
Single product name:
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard
Limpar os recursos
Quando você não precisar mais da conta do Azure Cosmos DB for Table, poderá excluir o grupo de recursos correspondente.
Use o az group delete
comando para excluir o grupo de recursos.
az group delete --name $resourceGroupName
Próximas etapas
Neste guia de início rápido, você aprendeu a criar uma conta do Azure Cosmos DB for Table, criar uma tabela e gerenciar entradas usando o SDK do .NET. Agora você pode se aprofundar no SDK para saber como executar consultas de dados mais avançadas e tarefas de gerenciamento em seus recursos do Azure Cosmos DB for Table.