Démarrage rapide : bibliothèque de client de l’API SQL Azure Cosmos DB pour .NET

S’APPLIQUE À : API SQL

Démarrez avec la bibliothèque cliente Azure Cosmos DB pour .NET pour créer des bases de données, des conteneurs et des éléments au sein de votre compte. Suivez les étapes suivantes pour installer le package et essayer un exemple de code pour les tâches de base.

Notes

Les exemples d’extraits de code sont disponibles sur GitHub en tant que projet .NET.

Documentation de référence sur l’API | Code source de la bibliothèque | Package (NuGet) | Exemples

Prérequis

Vérification du prérequis

  • Dans une fenêtre de terminal ou de commande, exécutez dotnet --version pour vérifier que le kit de développement logiciel (SDK) .NET a la version 6.0 ou une version ultérieure.
  • Exécutez az --version (Azure CLI) ou Get-Module -ListAvailable AzureRM (Azure PowerShell) pour vérifier que les outils de ligne de commande Azure appropriés sont installés.

Configuration

Cette section vous guide dans la création d’un compte Azure Cosmos et la configuration d’un projet qui utilise la bibliothèque de client de l’API SQL Azure Cosmos DB pour .NET afin de gérer les ressources.

Création d’un compte Azure Cosmos DB

Ce guide de démarrage rapide crée un seul compte Azure Cosmos DB à l’aide de l’API SQL.

  1. Créez des variables d’interpréteur de commandes pour accountName, resourceGroupName et location.

    # Variable for resource group name
    resourceGroupName="msdocs-cosmos-quickstart-rg"
    location="westus"
    
    # Variable for account name with a randomnly generated suffix
    let suffix=$RANDOM*$RANDOM
    accountName="msdocs-$suffix"
    
  2. Si vous ne l’avez pas déjà fait, connectez-vous à Azure CLI à l’aide de la commande az login.

  3. Utilisez la commande az group create pour créer un groupe de ressources dans votre abonnement.

    az group create \
        --name $resourceGroupName \
        --location $location
    
  4. Utilisez la commande az cosmosdb create pour créer un compte d’API Azure Cosmos DB SQL avec les paramètres par défaut.

    az cosmosdb create \
        --resource-group $resourceGroupName \
        --name $accountName \
        --locations regionName=$location
    
  5. Obtenez l’URI de point de terminaison d’API SQL pour le compte à l’aide de la commande az cosmosdb show.

    az cosmosdb show \
        --resource-group $resourceGroupName \
        --name $accountName \
        --query "documentEndpoint"
    
  6. 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"
    
  7. Enregistrez les valeurs URI et CLÉ PRIMAIRE. Vous aurez besoin de ces informations d’identification ultérieurement.

Créer une application .NET

Créez une application .NET dans un dossier vide à l’aide de votre terminal préféré. Utilisez la commande dotnet new spécifiant le modèle de console.

dotnet new console

Installer le package

Ajoutez le package NuGet Microsoft.Azure.Cosmos au projet .NET. Utilisez la commande dotnet add package spécifiant le nom du package NuGet.

dotnet add package Microsoft.Azure.Cosmos

Générez le projet avec la commande dotnet build.

dotnet build

Assurez-vous que le build a réussi sans erreur. La sortie attendue de la build doit ressembler à ceci :

  Determining projects to restore...
  All projects are up-to-date for restore.
  dslkajfjlksd -> C:\Users\sidandrews\Demos\dslkajfjlksd\bin\Debug\net6.0\dslkajfjlksd.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Configuration des variables d’environnement

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. Pour définir la variable d’environnement, utilisez votre terminal préféré pour exécuter les commandes suivantes :

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

Modèle objet

Avant de commencer à générer l’application, examinons la hiérarchie des ressources dans Azure Cosmos DB. Azure Cosmos DB a un modèle objet spécifique utilisé pour créer et accéder aux ressources. Azure Cosmos DB crée des ressources dans une hiérarchie qui se compose de comptes, de bases de données, de conteneurs et d’éléments.

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

Hierarchical diagram showing an Azure Cosmos D B account at the top. The account has two child database nodes. One of the database nodes includes two child container nodes. The other database node includes a single child container node. That single container node has three child item nodes.

Pour en savoir plus sur la hiérarchie des différentes entités, consultez Utilisation de bases de données, conteneurs et éléments dans Azure Cosmos DB.

Vous allez utiliser les classes .NET suivantes pour interagir avec ces ressources :

  • CosmosClient : cette classe fournit une représentation logique 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.
  • QueryDefinition : Cette classe représente une requête SQL et tous les paramètres de requête.
  • FeedIterator<> : Cette classe représente un itérateur capable de suivre la page actuelle des résultats et d’obtenir une nouvelle page de résultats.
  • FeedResponse<> : Cette classe représente une seule page de réponses de l’itérateur. Ce type peut être itéré à l’aide d’une boucle foreach.

Exemples de code

L’exemple de code décrit dans cet article crée une base de données nommée adventureworks avec un conteneur nommé products. La table products est conçue pour contenir des détails de produit comme le nom, la catégorie, la quantité et un indicateur de vente. Chaque produit contient également un identificateur unique.

Pour cet exemple de code, le conteneur utilise la catégorie comme clé de partition logique.

Authentifier le client

À partir du répertoire de projet, ouvrez le fichier Program.cs. Dans votre éditeur, ajoutez une directive d’utilisation pour Microsoft.Azure.Cosmos.

using Microsoft.Azure.Cosmos;

Définissez une nouvelle instance de la classe CosmosClient à l’aide du constructeur et Environment.GetEnvironmentVariable pour lire les deux variables d’environnement que vous avez créées précédemment.

// New instance of CosmosClient class
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    authKeyOrResourceToken: Environment.GetEnvironmentVariable("COSMOS_KEY")!
);

Pour plus d’informations sur les différentes façons de créer une instance CosmosClient, consultez Démarrer avec l’API SQL Azure Cosmos DB et .NET.

Création d'une base de données

Utilisez la méthode CosmosClient.CreateDatabaseIfNotExistsAsync pour créer uniquement une base de données si elle n’existe pas déjà. Cette méthode retourne une référence à la base de données existante ou nouvellement créée.

// Database reference with creation if it does not already exist
Database database = await client.CreateDatabaseIfNotExistsAsync(
    id: "adventureworks"
);

Console.WriteLine($"New database:\t{database.Id}");

Pour plus d’informations sur la création d’une base de données, consultez Créer une base de données dans l’API SQL Azure Cosmos DB à l’aide de .NET.

Créez un conteneur.

Database.CreateContainerIfNotExistsAsync crée uniquement un conteneur s’il n’existe pas déjà. Cette méthode renvoie également une référence au conteneur.

// Container reference with creation if it does not alredy exist
Container container = await database.CreateContainerIfNotExistsAsync(
    id: "products",
    partitionKeyPath: "/category",
    throughput: 400
);

Console.WriteLine($"New container:\t{container.Id}");

Pour plus d’informations sur la création d’un conteneur, consultez Créer un conteneur dans l’API SQL Azure Cosmos DB à l’aide de .NET.

Créer un élément

Le moyen le plus simple de créer un élément dans un conteneur consiste à créer d’abord une classe C# ou un type d’enregistrement avec tous les membres que vous souhaitez sérialiser dans JSON. Dans cet exemple, l’enregistrement C# a un identificateur unique, un champ catégorie pour la clé de partition et un nom supplémentaire, une quantité et des champs vente.

// C# record representing an item in the container
public record Product(
    string id,
    string category,
    string name,
    int quantity,
    bool sale
);

Créez un élément dans le conteneur en appelant Container.UpsertItemAsync. Dans cet exemple, nous avons choisi de faire un upsert au lieu de créer un élément au cas où vous exécutiez cet exemple de code plusieurs fois.

// Create new object and upsert (create or replace) to container
Product newItem = new(
    id: "68719518391",
    category: "gear-surf-surfboards",
    name: "Yamba Surfboard",
    quantity: 12,
    sale: false
);

Product createdItem = await container.UpsertItemAsync<Product>(
    item: newItem,
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Console.WriteLine($"Created item:\t{createdItem.id}\t[{createdItem.category}]");

Pour plus d’informations sur la création, l’upsert ou le remplacement d’éléments, consultez Créer un élément dans l’API SQL Azure Cosmos DB à l’aide de .NET.

Obtenir un élément

Dans Azure Cosmos DB, vous pouvez effectuer une opération de lecture de point à l’aide des champs d’identificateur unique (id) et de clé de partition. Dans le kit de développement logiciel (SDK), appelez Container.ReadItemAsync<> en passant dans les deux valeurs pour renvoyer une instance désérialisée de votre type C#.

// Point read item from container using the id and partitionKey
Product readItem = await container.ReadItemAsync<Product>(
    id: "68719518391",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Pour plus d’informations sur la lecture d’éléments et l’analyse de la réponse, consultez Lire un élément dans l’API SQL Azure Cosmos DB à l’aide de .NET.

Éléments de requête

Après avoir inséré un élément, vous pouvez exécuter une requête pour obtenir tous les éléments qui correspondent à un filtre spécifique. Cet exemple exécute la requête SQL : SELECT * FROM todo t WHERE t.partitionKey = 'gear-surf-surfboards'. Cet exemple utilise le type QueryDefinition et une expression de requête paramétrable pour le filtre de clé de partition. Une fois la requête définie, appelez Container.GetItemQueryIterator<> pour obtenir un itérateur de résultat qui gérera les pages des résultats. Ensuite, utilisez une combinaison de boucles while et foreach pour récupérer des pages de résultats, puis itérer sur les éléments individuels.

// Create query using a SQL string and parameters
var query = new QueryDefinition(
    query: "SELECT * FROM products p WHERE p.partitionKey = @key"
)
    .WithParameter("@key", "gear-surf-surfboards");

using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryDefinition: query
);

while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        Console.WriteLine($"Found item:\t{item.name}");
    }
}

Exécuter le code

Cette application crée une base de données et un conteneur d’API SQL Azure Cosmos DB. L’exemple crée ensuite un élément, puis lit exactement le même élément. Enfin, l’exemple émet une requête qui ne doit renvoyer que cet élément unique. Avec chaque étape, l’exemple génère des métadonnées dans la console sur les étapes qu’elle a effectuées.

Pour exécuter l’application, utilisez un terminal pour accéder au répertoire de l’application et exécuter l’application.

dotnet run

La sortie de l’application doit être similaire à l’exemple suivant :

New database:   adventureworks
New container:  products
Created item:   68719518391     [gear-surf-surfboards]

Nettoyer les ressources

Lorsque vous n’avez plus besoin du compte d’API SQL Azure Cosmos DB, vous pouvez supprimer le groupe de ressources correspondant.

Pour supprimer le groupe de ressources, utilisez la commande az group delete.

az group delete --name $resourceGroupName

Étapes suivantes

Dans ce guide de démarrage rapide, vous avez découvert comment créer un compte d’API SQML Azure Cosmos DB, créer une base de données et créer un conteneur en utilisant le kit de développement logiciel (SDK) .NET. Vous pouvez maintenant explorer plus en détail le kit de développement logiciel (SDK) pour importer davantage de données, effectuer des requêtes complexes et gérer vos ressources d’API SQL Azure Cosmos DB.