Guia de início rápido: Azure Cosmos DB for Table para .NET

Artigo
03/10/2024

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 usando dotnet 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 entradas Azure.Identity ambas existem.

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.

Você usará as seguintes classes da API para Table 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 a cadeia de conexão definida anteriormente.

// 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. Use o método TableClient.CreateIfNotExistsAsync no TableClient para criar uma tabela, se ela ainda não existir. Esse método retornará 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 TableEntity.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 gera 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

Use o Remove-AzResourceGroup cmdlet para excluir o grupo de recursos.

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

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.

Introdução ao Azure Cosmos DB for Table e ao .NET