Introdução ao Azure Cosmos DB for NoSQL usando .NET
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
- Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
- Conta do Azure Cosmos DB for NoSQL. Criar uma conta da API para o NoSQL.
- .NET 6.0 ou posterior
- CLI (interface de linha de comando) do Azure ou Azure PowerShell
Configurar o seu projeto
Crie o aplicativo de console do .NET
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. Há três maneiras principais de se conectar a uma conta da API de NoSQL usando a classe CosmosClient:
- Conectar-se com um ponto de extremidade da API para o NoSQL e chave de leitura/gravação
- Conectar-se com uma cadeia de conexão da API para o NoSQL
- Conectar-se com o Microsoft Entra ID
Conexão com um ponto de extremidade e uma chave
O construtor mais comum para CosmosClient tem dois parâmetros:
Parâmetro | Valor de exemplo | Descrição |
---|---|---|
accountEndpoint |
A variável de ambiente COSMOS_ENDPOINT |
Ponto de extremidade da API para o NoSQL a ser usado para todas as solicitações |
authKeyOrResourceToken |
A variável de ambiente COSMOS_KEY |
Chave de conta ou token de recurso a ser usado ao autenticar |
Recuperar o ponto de extremidade e a chave da conta
Crie uma variável de shell para resourceGroupName.
# Variable for resource group name resourceGroupName="msdocs-cosmos-dotnet-howto-rg"
Use o comando
az cosmosdb list
para recuperar o nome da primeira conta do Azure Cosmos DB em seu grupo de recursos e armazená-lo na variável de shell accountName.# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
Obtenha o URI do ponto de extremidade da API para o NoSQL para a conta usando o comando
az cosmosdb show
.az cosmosdb show \ --resource-group $resourceGroupName \ --name $accountName \ --query "documentEndpoint"
Localize a CHAVE PRIMÁRIA na lista de chaves da conta com o comando
az-cosmosdb-keys-list
.az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "keys" \ --query "primaryMasterKey"
Registre os valores do URI e da PRIMARY KEY. Você usará dessas credenciais depois.
Para usar os valores do URI e do PRIMARY KEY no código .NET, persista-os para novas variáveis de ambiente no computador local que executa o aplicativo.
$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"
Criar o CosmosClient com o ponto de extremidade e a chave da conta
Crie uma nova instância da classe CosmosClient com as variáveis de ambiente COSMOS_ENDPOINT
e COSMOS_KEY
como parâmetros.
// New instance of CosmosClient class using an endpoint and key string
using CosmosClient client = new(
accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
authKeyOrResourceToken: Environment.GetEnvironmentVariable("COSMOS_KEY")!
);
Conexão com uma cadeia de conexão
Outro construtor para CosmosClient contém apenas um único parâmetro:
Parâmetro | Valor de exemplo | Descrição |
---|---|---|
accountEndpoint |
A variável de ambiente COSMOS_ENDPOINT |
Ponto de extremidade da API para o NoSQL a ser usado para todas as solicitações |
connectionString |
A variável de ambiente COSMOS_CONNECTION_STRING |
Cadeia de conexão com a conta da API para o NoSQL |
Recuperar sua conta cadeia de conexão
Use o comando
az cosmosdb list
para recuperar o nome da primeira conta do Azure Cosmos DB em seu grupo de recursos e armazená-lo na variável de shell accountName.# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
Localize a CADEIA DE CONEXÃO PRIMÁRIA na lista de cadeias de conexão da conta com o comando
az-cosmosdb-keys-list
.az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "connection-strings" \ --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"
Para usar o valor de CADEIA DE CONEXÃO PRIMÁRIA no código .NET, persista-o em uma nova variável de ambiente no computador local que executa o aplicativo.
$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"
Criar o CosmosClient com cadeia de conexão
Crie uma nova instância da classe CosmosClient com as variáveis de ambiente COSMOS_CONNECTION_STRING
como o único parâmetro.
// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
connectionString: Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING")!
);
Conectar-se usando a plataforma de identidade da Microsoft
Para se conectar à sua conta da API para NoSQL usando a plataforma de identidade da Microsoft e o Microsoft Entra ID, 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
);
Criar o CosmosClient com implementação de credencial personalizada
Se você planeja implantar o aplicativo fora do Azure, você pode obter um token OAuth usando outras classes na biblioteca de clientes do Azure.Identity para .NET. Essas outras classes também derivam da classe TokenCredential
.
Para este exemplo, criamos uma instância ClientSecretCredential
usando identificadores de cliente e locatário, juntamente com um segredo do cliente.
// Custom credential class for servers and clients outside of Azure
TokenCredential credential = new ClientSecretCredential(
tenantId: Environment.GetEnvironmentVariable("AAD_TENANT_ID")!,
clientId: Environment.GetEnvironmentVariable("AAD_CLIENT_ID")!,
clientSecret: Environment.GetEnvironmentVariable("AAD_CLIENT_SECRET")!,
options: new TokenCredentialOptions()
);
Você pode obter a ID do cliente, a ID do locatário e o segredo do cliente ao registrar um aplicativo no Microsoft Entra ID. Para obter mais informações sobre como registrar aplicativos do Microsoft Entra, confira Registrar um aplicativo na plataforma de identidade da Microsoft.
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 hierárquico mostrando uma conta do Azure Cosmos DB na parte superior. A conta tem dois nós de banco de dados filho. Um dos nós de banco de dados inclui dois nós de contêiner filho. O outro inclui um único nó de contêiner filho. Esse nó de contêiner único tem três nós de item filho.
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
Agora que você se conectou a uma conta da API de NoSQL, use o próximo guia para criar e gerenciar bancos de dados.