Guia de início rápido: Azure Cosmos DB for Table for .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 Pacote Azure.Data.Tables (NuGet).
Nota
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 Tabela Azure.Data.Tables Package (NuGet)
Pré-requisitos
- Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
- Conta do GitHub
- Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
- CLI do desenvolvedor do Azure
- Área de trabalho do Docker
Configuração
Implante o contêiner de desenvolvimento deste projeto em seu ambiente. Em seguida, 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.
Importante
As contas do GitHub incluem um direito de armazenamento e horas essenciais sem nenhum custo. Para obter mais informações, consulte armazenamento incluído e horas principais para contas do GitHub.
Abra um terminal no diretório raiz do projeto.
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
Durante a inicialização, configure um nome de ambiente exclusivo.
Gorjeta
O nome do ambiente também será usado como o nome do grupo de recursos de destino. Para este guia de início rápido, considere usar
msdocs-cosmos-db
o .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 e o local desejado. 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 Microsoft.Azure.Cosmos
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
Além disso, instale o
Azure.Identity
pacote se ainda não estiver instalado.dotnet add package Azure.Identity
Abra e revise o arquivo src/web/Cosmos.Samples.Table.Quickstart.Web.csproj para validar se as
Microsoft.Azure.Cosmos
entradas eAzure.Identity
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 Table para interagir com esses recursos:
TableServiceClient
- Esta classe fornece métodos para executar operações de nível de serviço com o Azure Cosmos DB for Table.TableClient
- Esta classe permite que você interaja com tabelas hospedadas na API de tabela do Azure Cosmos DB.TableEntity
- Esta 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 using para Azure.Data.Tables
.
using Azure.Data.Tables;
Defina uma nova instância da TableServiceClient
classe usando o construtor e Environment.GetEnvironmentVariable
leia 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 TableServiceClient
classe. Crie uma nova tabela se ela ainda não existir usando o TableClient.CreateIfNotExistsAsync
método no TableClient
. 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 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.
// 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 Product
classe 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 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.
// 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 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.
// 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 de API de tabela do Azure Cosmos DB. Em seguida, o exemplo cria um item e, em seguida, lê exatamente o mesmo item de volta. Finalmente, o exemplo cria um segundo item e, em seguida, executa uma consulta que deve retornar vários itens. Com 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 executar 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
Clean up resources (Limpar recursos)
Quando não precisar mais da conta do Azure Cosmos DB for Table, você 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óximos passos
Neste início rápido, você aprendeu como 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.