Explorer le kit SDK Microsoft .NET v3 pour Azure Cosmos DB

  • 3 minutes

Cette unité se concentre sur le Kit de développement logiciel (SDK) .NET Azure Cosmos DB v3 pour l’API pour NoSQL. (Package NuGet Microsoft.Azure.Cosmos.) Si vous connaissez la version précédente du kit SDK .NET, vous êtes peut-être habitué aux termes collection et document.

Le référentiel de GitHub azure-cosmos-dotnet-v3 comprend les exemples de solutions .NET les plus récents. Ces solutions vous permettent d’effectuer des opérations CRUD (créer, lire, mettre à jour et supprimer) et d’autres opérations courantes sur les ressources Azure Cosmos DB.

Comme Azure Cosmos DB prend en charge plusieurs modèles d’API, la version 3 du kit SDK .NET utilise les termes génériques « conteneur » et « élément ». Un conteneur peut être une collection, un graphe ou une table. Un élément peut être un document, une arête/un sommet ou une ligne, et correspond au contenu d’un conteneur.

Vous trouverez ci-dessous des exemples illustrant certaines des opérations clés que vous devez connaître. Pour plus d’exemples, consultez le lien GitHub présenté plus haut. Les exemples ci-dessous utilisent tous la version asynchrone des méthodes.

CosmosClient

Crée un nouveau CosmosClient avec une chaîne de connexion. CosmosClient est thread-safe. Il est recommandé de conserver une seule instance de CosmosClient par durée de vie de l’application pour avoir une gestion et des performances de connexion efficaces.

CosmosClient client = new CosmosClient(endpoint, key);

Exemples de base de données

Création d'une base de données

CosmosClient.CreateDatabaseIfNotExistsAsync vérifie si une base de données existe et, si elle n’existe pas, la crée. Seule la base de données id est utilisée pour vérifier si une base de données existe déjà.

// An object containing relevant information about the response
DatabaseResponse databaseResponse = await client.CreateDatabaseIfNotExistsAsync(databaseId, 10000);

Lire une base de données par identifiant

Lit une base de données à partir du service Azure Cosmos DB en tant qu’opération asynchrone.

DatabaseResponse readResponse = await database.ReadAsync();

Supprimer une base de données

Supprime une base de données en tant qu’opération asynchrone.

await database.DeleteAsync();

Exemples de conteneur

Créez un conteneur.

La méthode Database.CreateContainerIfNotExistsAsync vérifie si un conteneur existe et, s’il n’existe pas, le crée. Seul le conteneur id est utilisé pour vérifier si un conteneur existe déjà.

// Set throughput to the minimum value of 400 RU/s
ContainerResponse simpleContainer = await database.CreateContainerIfNotExistsAsync(
    id: containerId,
    partitionKeyPath: partitionKey,
    throughput: 400);

Obtenir un conteneur par ID

Container container = database.GetContainer(containerId);
ContainerProperties containerProperties = await container.ReadContainerAsync();

Supprimer un conteneur

Supprime un conteneur en tant qu’opération asynchrone.

await database.GetContainer(containerId).DeleteContainerAsync();

Exemples d’éléments

Créer un élément

Utilisez la méthode Container.CreateItemAsync pour créer un élément. La méthode nécessite un objet sérialisable JSON qui doit contenir une propriété id et une partitionKey.

ItemResponse<SalesOrder> response = await container.CreateItemAsync(salesOrder, new PartitionKey(salesOrder.AccountNumber));

Lire un élément

Utilisez la méthode Container.ReadItemAsync pour lire un élément. La méthode nécessite un type pour y sérialiser l’élément, ainsi qu’une propriété id et une partitionKey.

string id = "[id]";
string accountNumber = "[partition-key]";
ItemResponse<SalesOrder> response = await container.ReadItemAsync(id, new PartitionKey(accountNumber));

Interroger un élément

La méthode Container.GetItemQueryIterator crée une requête pour les éléments d’un conteneur dans une base de données Azure Cosmos en utilisant une instruction SQL avec des valeurs paramétrisées. Cette méthode retourne un FeedIterator.

QueryDefinition query = new QueryDefinition(
    "select * from sales s where s.AccountNumber = @AccountInput ")
    .WithParameter("@AccountInput", "Account1");

FeedIterator<SalesOrder> resultSet = container.GetItemQueryIterator<SalesOrder>(
    query,
    requestOptions: new QueryRequestOptions()
    {
        PartitionKey = new PartitionKey("Account1"),
        MaxItemCount = 1
    });

Autres ressources