Início rápido: usar o Azure Cosmos DB for Table com o SDK do Azure para .NET

Aplica-se a: ✅ Table

Neste início rápido, você implantará um aplicativo básico do Azure Cosmos DB for Table usando o SDK do Azure para .NET. O Azure Cosmos DB for Table é um armazenamento de dados sem esquema que permite que aplicativos armazenem dados de tabela estruturados na nuvem. Você aprenderá a criar tabelas, linhas e executar tarefas básicas dentro do seu recurso do Azure Cosmos DB usando o Azure SDK para .NET.

Documentação de referência da API | Código-fonte da biblioteca | Pacote (NuGet) | Azure Developer CLI

Pré-requisitos

Azure Developer CLI
Área de Trabalho do Docker
.NET 9.0

Se você ainda não tiver uma conta do Azure, crie uma conta gratuita antes de começar.

Inicializar o projeto

Use a Azure Developer CLI (azd) para criar uma conta do Azure Cosmos DB for Table e implantar um aplicativo de exemplo em contêineres. O aplicativo de exemplo usa a biblioteca de clientes para gerenciar, criar, ler e consultar dados de exemplo.

Abra um terminal em um diretório vazio.
Se você ainda não estiver autenticado, autentique-se na 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 --template cosmos-db-table-dotnet-quickstart

Durante a inicialização, configure um nome de ambiente exclusivo.
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 a sua assinatura, o local desejado e o grupo de recursos de destino. 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.

Captura de tela do aplicativo Web em execução.

Instalar a biblioteca de clientes

A biblioteca de clientes está disponível por meio do NuGet, como o pacote Azure.Data.Tables.

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 usando dotnet add package.
```
dotnet add package Azure.Data.Tables
```
Abra e examine o arquivo src/web/Microsoft.Samples.Cosmos.Table.Quickstart.Web.csproj para validar se a entrada Azure.Data.Tables existe.

Importar bibliotecas

Importar os namespaces Azure.Identity e Azure.Data.Tables para o código do aplicativo.

using Azure.Identity;

using Azure.Data.Tables;

Modelo de objeto

Nome	Descrição
TableServiceClient	Essa é a classe de cliente principal e é usada para gerenciar metadados ou bancos de dados em toda a conta.
TableClient	Essa classe representa o cliente de uma tabela dentro da conta.

O código de exemplo no modelo usa uma tabela chamada cosmicworks-products. A tabela cosmicworks-products contém detalhes como nome, categoria, quantidade, preço, um identificador exclusivo e um sinalizador de venda para cada produto. O contêiner usa um identificador exclusivo como chave de linha e categoria como chave de partição.

Autenticar o cliente

Este exemplo cria uma nova instância da classe TableServiceClient.

DefaultAzureCredential credential = new();

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

Obter uma tabela

Este exemplo cria uma instância da classe TableClient usando o método GetTableClient da classe TableServiceClient.

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

Criar uma entidade

A maneira mais fácil de criar uma nova entidade 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.

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

Crie uma entidade na tabela usando a classe Product chamando TableClient.AddEntityAsync<T>.

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

Obter uma entidade

Você pode recuperar uma entidade específica de uma tabela usando o método TableClient.GetEntityAsync<T>. Forneça partitionKey e rowKey como parâmetros para identificar a linha correta para executar uma leitura de ponto rápida dessa entidade.

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

Consultar entidades

Depois de inserir uma entidade, você também pode executar uma consulta para obter todas as entidades que correspondem a um filtro específico usando o método TableClient.Query<T>. Este exemplo filtra produtos por categoria usando a sintaxe de consulta integrada à linguagem (LINQ), que é um benefício do uso de modelos tipados ITableEntity como a classe Product.

string category = "gear-surf-surfboards";

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

Analise os resultados paginados da consulta fazendo loop em cada página de resultados usando loop assíncrono.

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

Limpar os recursos

Quando você não precisar mais dos recursos ou do aplicativo de exemplo, remova a implantação correspondente e todos os recursos.

azd down

Comentários

Esta página foi útil?

Last updated on 2025-10-13