Compartilhar via

Início Rápido: Biblioteca do Azure Cosmos DB for Table para .NET

  • Artigo

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 no recurso do Azure Cosmos DB usando o SDK do Azure para .NET

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

Pré-requisitos

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.

  1. Abra um terminal em um diretório vazio.

  2. 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

  3. Execute azd init para inicializar o projeto.

    azd init --template cosmos-db-table-dotnet-quickstart

  4. Durante a inicialização, configure um nome de ambiente exclusivo.

  5. Implante a conta do Azure Cosmos DB usando azd up. Os modelos do Bicep também implantam um aplicativo Web de exemplo.

    azd up

  6. 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.

  7. 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.

  8. 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.

  1. Abra um terminal e vá até a pasta /src/web.

    cd ./src/web

  2. Se o pacote Azure.Data.Tables ainda não estiver instalado, instale-o usando dotnet add package.

    dotnet add package Azure.Data.Tables

  3. Abra e examine o arquivo src/web/Microsoft.Samples.Cosmos.Table.Quickstart.Web.csproj para validar se a entrada Azure.Data.Tables existe.

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.

Exemplos de código

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 a chave de linha e a categoria como uma chave de partição.

Autenticar o cliente

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

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 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.

public record Product : ITableEntity
{
    public string RowKey { get; set; } = $"{Guid.NewGuid()}";

    public string PartitionKey { get; set; } = String.Empty;

    public string Name { get; set; } = String.Empty;

    public int Quantity { get; set; } = 0;

    public decimal Price { get; set; } = 0.0m;

    public bool Clearance { get; set; } = false;

    public ETag ETag { get; set; } = ETag.All;

    public DateTimeOffset? Timestamp { get; set; }
};

Crie um item na coleção usando a classe Product chamando TableClient.AddEntityAsync<T>.

Product entity = new()
{
    RowKey = "68719518391",
    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 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.

Response<Product> response = await client.GetEntityAsync<Product>(
    rowKey: "68719518391",
    partitionKey: "gear-surf-surfboards"
);

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.

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

Conteúdo relacionado