Introdução ao Azure Cosmos DB for NoSQL usando .NET

  • Artigo

APLICA-SE A: NoSQL

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

Pacote (NuGet) | Amostras | Referência de API | Código-fonte da biblioteca | Fazer comentários

Pré-requisitos

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 de NuGet do microsoft.Azure.Cosmos usando o comando dotnet add package.

dotnet add package Microsoft.Azure.Cosmos

Compile o projeto om o comando dotnet build.

dotnet build

Conectar-se ao Azure Cosmos DB for NoSQL

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

Para se conectar à 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 CosmosClient class using a connection string
using CosmosClient client = new(
    accountEndpoint: 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 o NoSQL, que é o namespace exclusivo de nível superior dos dados do Azure Cosmos DB.

  • Bancos de dados, que organizam os contêineres em sua conta.

  • Contêineres, que contêm um conjunto de itens individuais em seu banco de dados.

  • Itens, que representam um documento JSON em seu contêiner.

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

Diagrama da hierarquia do Azure Cosmos DB, incluindo contas, bancos de dados, contêineres e itens.

Cada tipo de recurso é representado por uma ou mais classes .NET associadas. Aqui está uma lista das classes mais comuns:

Classe Descrição
CosmosClient Esta classe fornece a 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.
Database Essa classe é uma referência a um banco de dados que pode, ou não, existir no serviço ainda. O banco de dados é validado no lado do servidor quando você tenta acessá-lo ou executa uma operação nele.
Container Essa classe é uma referência a um contêiner que também pode não existir no serviço ainda. O contêiner é validado no lado do servidor quando você tenta trabalhar com ele.

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

Guia Descrição
Criar um banco de dados Criar bancos de dados
Criar um contêiner Crie contêineres
Ler um item Leitura pontual de um item específico
Itens de consulta Consultar vários itens

Confira também

Próximas etapas

Criar um banco de dados do Azure Cosmos DB for NoSQL usando .NET