Introduzione ad Azure Cosmos DB per NoSQL con .NET

  • Articolo

SI APPLICA A: NoSQL

Questo articolo illustra come connettersi ad Azure Cosmos DB per NoSQL usando .NET SDK. Dopo la connessione, è possibile eseguire operazioni su database, contenitori ed elementi.

Package (NuGet) | Samples | API reference | Library source code | Give Feedback

Prerequisiti

Impostare il progetto

Creare l'applicazione console .NET

Creare una nuova applicazione .NET usando il dotnet new comando con il modello di console .

dotnet new console

Importare il pacchetto NuGet Microsoft.Azure.Cosmos usando il dotnet add package comando .

dotnet add package Microsoft.Azure.Cosmos

Compilare il progetto con il dotnet build comando .

dotnet build

Connessione ad Azure Cosmos DB per NoSQL

Per connettersi all'API per NoSQL di Azure Cosmos DB, creare un'istanza della CosmosClient classe . Questa classe è il punto di partenza per eseguire tutte le operazioni sui database. Esistono tre modi principali per connettersi a un account API per NoSQL usando la classe CosmosClient :

Connessione con un endpoint e una chiave

Il costruttore più comune per CosmosClient ha due parametri:

Parametro Valore di esempio Descrizione
accountEndpoint La variabile di ambiente COSMOS_ENDPOINT API per l'endpoint NoSQL da usare per tutte le richieste
authKeyOrResourceToken La variabile di ambiente COSMOS_KEY Chiave dell'account o token di risorsa da usare per l'autenticazione

Recuperare l'endpoint e la chiave dell'account

  1. Creare una variabile della shell per resourceGroupName.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-dotnet-howto-rg"

  2. Usare il az cosmosdb list comando per recuperare il nome del primo account Azure Cosmos DB nel gruppo di risorse e archiviarlo nella variabile della shell accountName .

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  3. Ottenere l'URI dell'endpoint Api per NoSQL per l'account usando il az cosmosdb show comando .

    az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "documentEndpoint"

  4. Trovare la CHIAVE PRIMARIA dall'elenco di chiavi per l'account con il az-cosmosdb-keys-list comando .

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

  5. Registrare i valori URI e PRIMARY KEY . Queste credenziali verranno usate in un secondo momento.

Per usare i valori URI e PRIMARY KEY all'interno del codice .NET, renderli persistenti in nuove variabili di ambiente nel computer locale che esegue l'applicazione.

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Creare CosmosClient con endpoint e chiave dell'account

Creare una nuova istanza della classe CosmosClient con le COSMOS_ENDPOINT variabili di ambiente e COSMOS_KEY come parametri.

// 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")!
);

Connessione con un stringa di connessione

Un altro costruttore per CosmosClient contiene solo un singolo parametro:

Parametro Valore di esempio Descrizione
accountEndpoint La variabile di ambiente COSMOS_ENDPOINT API per l'endpoint NoSQL da usare per tutte le richieste
connectionString La variabile di ambiente COSMOS_CONNECTION_STRING stringa Connessione ion all'account API per NoSQL

Recuperare il stringa di connessione dell'account

  1. Usare il az cosmosdb list comando per recuperare il nome del primo account Azure Cosmos DB nel gruppo di risorse e archiviarlo nella variabile della shell accountName .

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  2. Trovare LA STRINGA DI CONNESSIONE PRIMARIA dall'elenco di stringa di connessione per l'account con il az-cosmosdb-keys-list comando .

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "connection-strings" \
    --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"

Per usare il valore PRIMARY CONNECTION STRING all'interno del codice .NET, salvarlo in modo permanente in una nuova variabile di ambiente nel computer locale che esegue l'applicazione.

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Creare CosmosClient con stringa di connessione

Creare una nuova istanza della classe CosmosClient con la COSMOS_CONNECTION_STRING variabile di ambiente come unico parametro.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    connectionString: Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING")!
);

Connessione con Microsoft Identity Platform

Per connettersi all'account API per NoSQL usando Microsoft Identity Platform e Microsoft Entra ID, usare un'entità di sicurezza. Il tipo esatto di entità dipenderà dalla posizione in cui si ospita il codice dell'applicazione. La tabella seguente funge da guida di riferimento rapido.

Posizione in cui viene eseguita l'applicazione Entità di sicurezza principale
Computer locale (sviluppo e test) Identità utente o entità servizio
Azure Identità gestita
Server o client esterni ad Azure Entità servizio

Importare Azure.Identity

Il pacchetto NuGet Azure.Identity contiene le funzionalità di autenticazione di base condivise tra tutte le librerie di Azure SDK.

Importare il pacchetto NuGet Azure.Identity usando il dotnet add package comando .

dotnet add package Azure.Identity

Ricompilare il progetto con il dotnet build comando .

dotnet build

Nell'editor di codice aggiungere direttive using per Azure.Core gli spazi dei nomi e Azure.Identity .

using Azure.Core;
using Azure.Identity;

Creare CosmosClient con l'implementazione predefinita delle credenziali

Se si esegue il test in un computer locale o l'applicazione verrà eseguita nei servizi di Azure con supporto diretto per le identità gestite, ottenere un token OAuth creando un'istanza DefaultAzureCredential di .

Per questo esempio, l'istanza è stata salvata in una variabile di tipo TokenCredential perché si tratta di un tipo più generico riutilizzabile tra gli SDK.

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

Creare una nuova istanza della classe CosmosClient con la COSMOS_ENDPOINT variabile di ambiente e l'oggetto TokenCredential come parametri.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    tokenCredential: credential
);

Creare CosmosClient con un'implementazione di credenziali personalizzata

Se si prevede di distribuire l'applicazione da Azure, è possibile ottenere un token OAuth usando altre classi nella libreria client Azure.Identity per .NET. Queste altre classi derivano anche dalla TokenCredential classe .

Per questo esempio viene creata un'istanza ClientSecretCredential usando identificatori client e tenant, insieme a un segreto client.

// 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()
);

È possibile ottenere l'ID client, l'ID tenant e il segreto client quando si registra un'applicazione in Microsoft Entra ID. Per altre informazioni sulla registrazione di applicazioni Microsoft Entra, vedere Registrare un'applicazione con Microsoft Identity Platform.

Creare una nuova istanza della classe CosmosClient con la COSMOS_ENDPOINT variabile di ambiente e l'oggetto TokenCredential come parametri.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    tokenCredential: credential
);

Compilare l'applicazione

Durante la compilazione dell'applicazione, il codice interagirà principalmente con quattro tipi di risorse:

  • L'account API per NoSQL, ovvero lo spazio dei nomi principale univoco per i dati di Azure Cosmos DB.

  • Database, che organizzano i contenitori nell'account.

  • Contenitori che contengono un set di singoli elementi nel database.

  • Elementi che rappresentano un documento JSON nel contenitore.

Il diagramma seguente mostra la relazione tra queste risorse.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, containers, and items.

Ogni tipo di risorsa è rappresentato da una o più classi .NET associate. Ecco un elenco delle classi più comuni:

Classe Descrizione
CosmosClient Questa classe fornisce una rappresentazione logica lato client per il servizio Azure Cosmos DB. L'oggetto client viene usato per configurare ed eseguire richieste nel servizio.
Database Questa classe è un riferimento a un database che potrebbe, o non, esistere ancora nel servizio. Il database viene convalidato sul lato server quando si tenta di accedervi o di eseguire un'operazione su di esso.
Container Questa classe è un riferimento a un contenitore che potrebbe non esistere ancora nel servizio. Il contenitore viene convalidato sul lato server quando si tenta di usarlo.

Le guide seguenti illustrano come usare ognuna di queste classi per compilare l'applicazione.

Guida Descrizione
Creare un database Creare database
Creare un contenitore Creare contenitori
Leggere un elemento Punto letto un elemento specifico
Eseguire query sugli elementi Eseguire query su più elementi

Vedi anche

Passaggi successivi

Dopo aver eseguito la connessione a un account API per NoSQL, usare la guida successiva per creare e gestire i database.

Creare un database in Azure Cosmos DB for NoSQL con .NET