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

APLICA-SE A: Tabela

• .NET
• Java
• Node.js
• Python

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ê aprenderá como 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.

1. Abra um terminal no diretório raiz do projeto.

2. Autentique-se na CLI do Desenvolvedor do Azure usando azd auth logino . Siga as etapas especificadas pela ferramenta para autenticar na CLI usando suas credenciais preferidas do Azure.

   azd auth login
   

3. Use azd init para inicializar o projeto.

   azd init
   

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

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

   azd up
   

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

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

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

   cd ./src/web
   

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

   dotnet add package Azure.Data.Tables
   

3. Além disso, instale o Azure.Identity pacote se ainda não estiver instalado.

   dotnet add package Azure.Identity
   

4. Abra e revise o arquivo src/web/Cosmos.Samples.Table.Quickstart.Web.csproj para validar se as Microsoft.Azure.Cosmos entradas e Azure.Identity existem.

Exemplos de código

• Autenticar o cliente
• Criar uma tabela
• Criar um item
• Obter um item
• Itens de consulta

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á 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 classe usando o construtor e Environment.GetEnvironmentVariable leia a cadeia de TableServiceClient 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 TableServiceClient classe. Use o TableClient.CreateIfNotExistsAsync método no para criar uma nova tabela, TableClient 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 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 TableEntity.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.

CLI do Azure

Use o az group delete comando para excluir o grupo de recursos.

az group delete --name $resourceGroupName

PowerShell

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

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

Portal

1. Navegue até o grupo de recursos que você criou anteriormente no portal do Azure.

   Gorjeta

   Neste guia de início rápido, recomendamos o nome msdocs-cosmos-quickstart-rg.

2. Selecione Eliminar grupo de recursos.

   

3. Na caixa de diálogo Tem certeza de que deseja excluir, digite o nome do grupo de recursos e selecione Excluir.

   

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.

Introdução ao Azure Cosmos DB para Tabela e .NET