Partilhar via

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

  • Artigo

APLICA-SE A: NoSQL

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

Pacote (NuGet) | Exemplos | Referência | da API Código-fonte | da biblioteca Enviar comentários

Pré-requisitos

Configure o seu projeto

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

dotnet new console

Importe o pacote NuGet do Microsoft.Azure.Cosmos usando o dotnet add package comando.

dotnet add package Microsoft.Azure.Cosmos

Crie o projeto com o dotnet build comando.

dotnet build

Conectar-se ao Azure Cosmos DB para NoSQL

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

Para se conectar à sua API para conta NoSQL usando o Microsoft Entra, use uma entidade de segurança. O tipo exato de entidade 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 Principal de segurança
Máquina local (desenvolvimento e testes) Identidade do usuário ou entidade de serviço
Azure Identidade gerida
Servidores ou clientes fora do Azure Service principal (Principal de serviço)

Importar Azure.Identity

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

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

dotnet add package Azure.Identity

Reconstrua o projeto com o dotnet build comando.

dotnet build

No editor de códigos, adicione usando diretivas para Azure.Core e Azure.Identity namespaces.

using Azure.Core;
using Azure.Identity;

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

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

Neste exemplo, salvamos a instância em uma variável de tipo TokenCredential , pois é um tipo mais genérico que pode ser reutilizado 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 COSMOS_ENDPOINT variável de ambiente 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
);

Compilar a aplicação

À medida que você cria seu aplicativo, seu código interage principalmente com quatro tipos de recursos:

  • A API para conta NoSQL, que é o namespace de nível superior exclusivo para seus dados do Azure Cosmos DB.

  • Bases de dados, que organizam os contentores na 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 seguinte mostra a relação entre estes 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 Description
CosmosClient Essa classe fornece uma representação lógica do lado do cliente para o serviço Azure Cosmos DB. O objeto 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 executar uma operação em relação a ele.
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 criar seu aplicativo.

Guia Description
Criar uma base de dados Criar bases de dados
Criar um contêiner Criar contêineres
Ler um item Ponto de leitura de um item específico
Itens de consulta Consultar vários itens

Consulte também

Próximos passos

Criar um banco de dados no Azure Cosmos DB para NoSQL usando .NET