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

Artigo
10/03/2024

APLICA-SE AO: Table

Este artigo mostra como se conectar ao Azure Cosmos DB for Table usando o SDK do .NET. Depois de conectado, você pode executar operações em tabelas e itens.

Pré-requisitos

Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
Conta do Azure Cosmos DB for Table. Criar uma conta da API para Tabela.
.NET 6.0 ou posterior
CLI (interface de linha de comando) do Azure ou Azure PowerShell

Configurar o seu projeto

Crie um novo aplicativo .NET usando o comando dotnet new com o modelo de console .

dotnet new console

Importe o pacote do NuGet Azure.Data.Tables usando comando dotnet add package.

dotnet add package Azure.Data.Tables

Compile o projeto com o dotnet buildcomando.

dotnet build

Conectar-se ao Azure Cosmos DB for Table

Para se conectar à API para Tabela do Azure Cosmos DB, crie uma instância da classe TableServiceClient. Essa classe é o ponto de partida para executar todas as operações em tabelas.

Para se conectar à sua conta da API para NoSQL usando o Microsoft Entra, use uma entidade de segurança. O tipo exato de entidade de segurança dependerá de onde você hospeda o código do aplicativo. A tabela abaixo serve como um guia de referência rápida.

Onde o aplicativo é executado	Entidade de segurança
Computador local (desenvolvimento e teste)	Identidade do usuário ou entidade de serviço
Azure	Identidade gerenciada
Servidores ou clientes fora do Azure	Entidade de serviço

Importar Azure.Identity

O pacote de NuGet do Azure.Identity contém a funcionalidade de autenticação principal que é compartilhada entre todas as bibliotecas do SDK do Azure.

Importe o pacote de NuGet Azure.Identity usando comando dotnet add package.

dotnet add package Azure.Identity

Recompile o projeto com o comando dotnet build.

dotnet build

No editor de código, adicione o uso de diretivas para Azure.Core e namespaces Azure.Identity.

using Azure.Core;
using Azure.Identity;

Criar o CosmosClient com implementação de credencial padrão

Se você estiver testando em um computador local ou seu aplicativo será executado nos serviços do Azure com suporte direto para identidades gerenciadas, obtenha um token OAuth criando uma instância DefaultAzureCredential.

Para este exemplo, salvamos a instância em uma variável de tipo TokenCredential, pois esse é um tipo mais genérico que pode ser reutilizável em SDKs.

// Credential class for testing on a local machine or Azure services
TokenCredential credential = new DefaultAzureCredential();

Crie uma nova instância da classe CosmosClient com a variável de ambiente COSMOS_ENDPOINT e o objeto TokenCredential como parâmetros.

// New instance of TableServiceClient class using Microsoft Entra
TableServiceClient client = new(
    endpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    tokenCredential: credential
);

Crie seu aplicativo

Conforme você compila seu aplicativo, seu código interagirá principalmente com quatro tipos de recursos:

A conta da API para Tabela, que é o namespace exclusivo de nível superior dos dados do Azure Cosmos DB.
Tabelas, que contêm um conjunto de itens individuais em sua conta.
Itens, que representam um item individual em sua tabela.

O diagrama a seguir mostra a relação entre esses recursos.

Diagrama da hierarquia do Azure Cosmos DB, incluindo contas, tabelas e itens.

Cada tipo de recurso é representado por uma ou mais interfaces ou classes .NET associadas. Veja uma lista dos tipos mais comuns:

Classe	Descrição
`TableServiceClient`	Esta classe de cliente fornece uma representação lógica do lado do cliente para o serviço do Azure Cosmos DB. Esse objeto do cliente é usado para configurar e executar solicitações no serviço.
`TableClient`	Esta classe de cliente é uma referência a uma tabela que pode ou não existir no serviço. A tabela é validada no lado do servidor quando você tenta acessá-la ou executa uma operação nela.
`ITableEntity`	Essa é a interface base para todos os itens criados na tabela ou consultados utilizando-a. Essa interface inclui todas as propriedades necessárias para itens na API para Tabela.
`TableEntity`	Essa classe é uma implementação genérica da interface `ITableEntity` como um dicionário de pares chave-valor.

Os guias a seguir mostram como usar cada uma dessas classes para compilar seu aplicativo.

Guia	Descrição
Criar uma tabela	Criar tabelas
Criar um item	Criar itens
Ler um item	Ler itens

Confira também

Próximas etapas

Agora que você se conectou a uma conta da API para Tabela, use o próximo guia para criar e gerenciar tabelas.

Criar uma tabela no Azure Cosmos DB for Table usando .NET

Compartilhar via