Guia de início rápido: Biblioteca do Azure Cosmos DB for Table para .NET
APLICA-SE A: Tabela
Este guia de início rápido mostra como começar a usar o Azure Cosmos DB for Table a partir de um aplicativo .NET. O Azure Cosmos DB for Table é um armazenamento de dados sem esquema que permite que os aplicativos armazenem dados de tabela estruturada na nuvem. Você aprende a criar tabelas, linhas e executar tarefas básicas em seu recurso do Azure Cosmos DB usando o SDK do Azure para .NET
Documentação | de referência da API Pacote de código-fonte | da biblioteca (NuGet) | CLI do desenvolvedor do Azure
Pré-requisitos
- Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
- CLI do desenvolvedor do Azure
- Área de trabalho do Docker
- .NET 9.0
Inicializar o projeto
Use a CLI do Desenvolvedor do Azure (azd
) para criar uma conta do Azure Cosmos DB for Table e implantar um aplicativo de exemplo em contêiner. O aplicativo de exemplo usa a biblioteca de cliente 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 CLI do Desenvolvedor do Azure usando
azd auth login
o . Siga as etapas especificadas pela ferramenta para autenticar na CLI usando suas credenciais preferidas do Azure.azd auth login
Use
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
o . Os modelos Bicep também implantam um aplicativo Web de exemplo.azd up
Durante o processo de provisionamento, selecione sua assinatura, o local desejado e o grupo de recursos de destino. Aguarde a conclusão do processo de provisionamento. 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 o URL no console para navegar até seu aplicativo Web no navegador. Observe a saída do aplicativo em execução.
Instalar a biblioteca de cliente
A biblioteca do cliente está disponível através do NuGet, como o Azure.Data.Tables
pacote.
Abra um terminal e navegue até a
/src/web
pasta.cd ./src/web
Se ainda não estiver instalado, instale o pacote usando
dotnet add package
oAzure.Data.Tables
.dotnet add package Azure.Data.Tables
Abra e revise o arquivo src/web/Microsoft.Samples.Cosmos.Table.Quickstart.Web.csproj para validar se a
Azure.Data.Tables
entrada existe.
Modelo de objeto
Nome | Descrição |
---|---|
TableServiceClient | Essa classe é a classe de cliente principal e é usada para gerenciar metadados ou bancos de dados em toda a conta. |
TableClient | Esta classe representa o cliente para uma tabela dentro da conta. |
Exemplos de código
O código de exemplo no modelo usa uma tabela chamada cosmicworks-products
. A cosmicworks-products
tabela 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 categoria como uma chave de partição.
Autenticar o cliente
Este exemplo cria uma nova instância da TableServiceClient
classe.
TableServiceClient serviceClient = new(
endpoint: new Uri("<azure-cosmos-db-table-account-endpoint>"),
credential
);
Obter uma mesa
Este exemplo cria uma instância da TableClient
classe usando o GetTableClient
método da TableServiceClient
classe.
TableClient client = serviceClient.GetTableClient(
tableName: "<azure-cosmos-db-table-name>"
);
Criar um item
A maneira mais fácil de criar um novo item em uma tabela é criar uma classe que implemente a ITableEntity
interface. Em seguida, você pode adicionar suas próprias propriedades à classe para preencher colunas de dados nessa linha da 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 Product
classe 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 TableClient.GetEntityAsync<T>
método. Forneça os partitionKey
parâmetros e rowKey
como para identificar a linha correta para executar uma leitura rápida do ponto 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 TableClient.Query<T>
método. Este exemplo filtra produtos por categoria usando a sintaxe Linq , que é um benefício de usar modelos tipados ITableEntity
como a Product
classe.
Nota
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 um loop em cada página de resultados usando um loop assíncrono.
List<Product> entities = new();
await foreach (Product product in results)
{
entities.Add(product);
}
Clean up resources (Limpar recursos)
Quando você não precisar mais do aplicativo ou recursos de exemplo, remova a implantação correspondente e todos os recursos.
azd down