Bien démarrer avec Azure Cosmos DB for NoSQL à l’aide de .NET
S’APPLIQUE À : NoSQL
Cet article vous montre comment vous connecter à Azure Cosmos DB for NoSQL à l’aide du SDK .NET. Une fois connecté, vous pouvez effectuer des opérations sur des bases de données, des conteneurs et des éléments.
Package (NuGet) | Exemples | Référence API | Code source de la bibliothèque | Envoyer des commentaires
Prérequis
- Compte Azure avec un abonnement actif. Créez un compte gratuitement.
- Compte Azure Cosmos DB for NoSQL. Créer une API pour un compte NoSQL.
- .NET 6.0 ou version ultérieure
- Interface de ligne de commande Azure (CLI) ou Azure PowerShell
Configuration de votre projet
Créez une application console .NET
Créez une application .NET à l’aide de la commande dotnet new
avec le modèle de console.
dotnet new console
Importez le package NuGet Microsoft.Azure.Cosmos à l’aide de la commande dotnet add package
.
dotnet add package Microsoft.Azure.Cosmos
Générez le projet avec la commande dotnet build
.
dotnet build
Se connecter à Azure Cosmos DB for NoSQL
Pour vous connecter à l’API pour NoSQL de Azure Cosmos DB, créez une instance de la classe CosmosClient
. Cette classe est le point de départ pour effectuer toutes les opérations sur des bases de données. Il existe trois façons principales de se connecter à un compte d’API pour NoSQL à l’aide de la classe CosmosClient :
- Se connecter avec un point de terminaison d’API for NoSQL et une clé de lecture/écriture
- Se connecter avec une chaîne de connexion d’API for NoSQL
- Se connecter avec Microsoft Entra ID
Se connecter avec un point de terminaison et une clé
Le constructeur le plus courant pour CosmosClient a deux paramètres :
Paramètre | Valeur d'exemple | Description |
---|---|---|
accountEndpoint |
COSMOS_ENDPOINT variable d’environnement |
Point de terminaison d’API for NoSQL à utiliser pour toutes les requêtes |
authKeyOrResourceToken |
COSMOS_KEY variable d’environnement |
Clé de compte ou jeton de ressource à utiliser lors de l’authentification |
Récupérer le point de terminaison et la clé de votre compte
Créez une variable d’interpréteur de commandes pour resourceGroupName.
# Variable for resource group name resourceGroupName="msdocs-cosmos-dotnet-howto-rg"
Utilisez la commande
az cosmosdb list
pour récupérer le nom du premier compte Azure Cosmos DB dans votre groupe de ressources et le stocker dans la variable d’interpréteur de commandes accountName.# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
Obtenez l’URI de point de terminaison d’API for NoSQL pour le compte à l’aide de la commande
az cosmosdb show
.az cosmosdb show \ --resource-group $resourceGroupName \ --name $accountName \ --query "documentEndpoint"
Recherchez la CLÉ PRIMAIRE dans la liste des clés du compte avec la commande
az-cosmosdb-keys-list
.az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "keys" \ --query "primaryMasterKey"
Enregistrez les valeurs URI et CLÉ PRIMAIRE. Vous aurez besoin de ces informations d’identification ultérieurement.
Pour utiliser les valeurs URI et CLÉ PRIMAIRE dans votre code .NET, conservez-les dans de nouvelles variables d’environnement sur l’ordinateur local exécutant l’application.
$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"
Créer CosmosClient avec un point de terminaison de compte et une clé
Créez une instance de la classe CosmosClient avec les variables d’environnement COSMOS_ENDPOINT
et COSMOS_KEY
en tant que paramètres.
// 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")!
);
Se connecter avec une chaîne de connexion
Un autre constructeur pour CosmosClient ne contient qu’un seul paramètre :
Paramètre | Valeur d'exemple | Description |
---|---|---|
accountEndpoint |
COSMOS_ENDPOINT variable d’environnement |
Point de terminaison d’API for NoSQL à utiliser pour toutes les requêtes |
connectionString |
COSMOS_CONNECTION_STRING variable d’environnement |
Chaîne de connexion au compte d’API for NoSQL |
Récupérer votre chaîne de connexion de compte
Utilisez la commande
az cosmosdb list
pour récupérer le nom du premier compte Azure Cosmos DB dans votre groupe de ressources et le stocker dans la variable d’interpréteur de commandes accountName.# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
Recherchez la CHAÎNE DE CONNEXION PRIMAIRE dans la liste des chaînes de connexion pour le compte avec la commande
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"
Pour utiliser la valeur CHAÎNE DE CONNEXION PRIMAIRE dans votre code .NET, conservez-la dans une nouvelle variable d’environnement sur l’ordinateur local exécutant l’application.
$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"
Créer CosmosClient avec une chaîne de connexion
Créez une instance de la classe CosmosClient avec les variables d’environnement COSMOS_CONNECTION_STRING
en tant que seul paramètre.
// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
connectionString: Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING")!
);
Se connecter à l’aide de la plateforme d’identités Microsoft
Pour vous connecter à votre compte d’API for NoSQL à l’aide de la plateforme d’identités Microsoft et de Microsoft Entra ID, utilisez un principal de sécurité. Le type exact de principal dépend de l’emplacement où vous hébergez votre code d’application. Le tableau ci-dessous sert de guide de référence rapide.
Emplacement d’exécution de l’application | Principal de sécurité |
---|---|
Ordinateur local (développement et test) | Identité de l’utilisateur ou principal du service |
Azure | Identité managée |
Serveurs ou clients en dehors d’Azure | Principal du service |
Importer Azure.Identity
Le package NuGet Azure.Identity contient les fonctionnalités d’authentification principales partagées entre toutes les bibliothèques du kit de développement logiciel (SDK) Azure.
Importez le package NuGet Azure.Identity à l’aide de la commande dotnet add package
.
dotnet add package Azure.Identity
Régénérez le projet avec la commande dotnet build
.
dotnet build
Dans votre éditeur de code, ajoutez des directives d’utilisation pour des espaces de noms Azure.Core
et Azure.Identity
.
using Azure.Core;
using Azure.Identity;
Créer CosmosClient avec l’implémentation des informations d’identification par défaut
Si vous testez sur une machine locale ou que votre application s’exécute sur des services Azure avec prise en charge directe des identités managées, obtenez un jeton OAuth en créant une instance DefaultAzureCredential
.
Pour cet exemple, nous avons enregistré l’instance dans une variable de type TokenCredential
, car c’est un type plus générique réutilisable dans les kits SDK.
// Credential class for testing on a local machine or Azure services
TokenCredential credential = new DefaultAzureCredential();
Créez une instance de la classe CosmosClient avec la variable d’environnement COSMOS_ENDPOINT
et l’objet TokenCredential en tant que paramètres.
// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
tokenCredential: credential
);
Créer CosmosClient avec l’implémentation des informations d’identification par défaut
Si vous prévoyez de déployer l’application en dehors d’Azure, vous pouvez obtenir un jeton OAuth en utilisant d’autres classes de la bibliothèque de client Azure.Identity pour .NET. Ces autres classes dérivent également de la classe TokenCredential
.
Pour cet exemple, nous créons une instance ClientSecretCredential
à l’aide d’identificateurs client et de locataire, ainsi qu’une clé secrète 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()
);
Vous pouvez obtenir l’ID client, l’ID locataire et la clé secrète client lorsque vous inscrivez une application dans Microsoft Entra ID. Pour plus d’informations concernant l’inscription d’applications Microsoft Entra, consultez Inscrire une application auprès de la plateforme d’identités Microsoft.
Créez une instance de la classe CosmosClient avec la variable d’environnement COSMOS_ENDPOINT
et l’objet TokenCredential en tant que paramètres.
// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
tokenCredential: credential
);
Générer votre application
À mesure que vous générez votre application, votre code interagit principalement avec quatre types de ressources :
Le compte d’API for NoSQL qui est l’unique espace de noms de niveau supérieur pour vos données Azure Cosmos DB.
Bases de données, qui organisent les conteneurs dans votre compte.
Conteneurs, qui contiennent un ensemble d’éléments individuels dans votre base de données.
Éléments, qui représentent un document JSON dans votre conteneur.
Le diagramme suivant montre la relation entre ces ressources.
Diagramme hiérarchique montrant un compte Azure Cosmos DB au sommet. Le compte présente deux nœuds de base de données enfants. L’un des nœuds de base de données comprend deux nœuds de conteneur enfants. L’autre nœud de base de données inclut un nœud de conteneur enfant unique. Ce nœud de conteneur unique a trois nœuds d’éléments enfants.
Chaque type de ressource est représenté par une ou plusieurs classes .NET associées. Voici une liste des classes les plus courantes :
Classe | Description |
---|---|
CosmosClient |
Cette classe fournit une représentation logique du côté client pour le service Azure Cosmos DB. Ce client est utilisé pour configurer et exécuter des requêtes sur le service. |
Database |
Cette classe est une référence à une base de données qui peut, ou non, exister dans le service. La base de données est validée côté serveur lorsque vous tentez d’y accéder ou d’effectuer une opération sur celle-ci. |
Container |
Cette classe est une référence à un conteneur qui n’existe pas encore dans le service. Le conteneur est validé côté serveur lorsque vous tentez de l’utiliser. |
Les guides suivants vous montrent comment utiliser chacune de ces classes pour générer votre application.
Guide | Description |
---|---|
Créer une base de données | Créer des bases de données |
Créer un conteneur | Créer des conteneurs |
Lire un élément | Pointer et lire un élément spécifique |
Éléments de requête | Interroger plusieurs éléments |
Voir aussi
- Package (NuGet)
- Exemples
- Informations de référence sur les API
- Code source de la bibliothèque
- Envoyer des commentaires
Étapes suivantes
Une fois que vous êtes connecté à un compte d’API pour NoSQL, utilisez le guide suivant pour créer et gérer des bases de données.