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 la version précédente du SDK .NET vous êtes familière, vous connaissez peut-être les termes de collection et le 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. La recommandation est 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

La méthode CosmosClient.CreateDatabaseAsync lève une exception si une base de données portant le même nom existe déjà.

// New instance of Database class referencing the server-side database
Database database1 = await client.CreateDatabaseAsync(
    id: "adventureworks-1"
);

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à.

// New instance of Database class referencing the server-side database
Database database2 = await client.CreateDatabaseIfNotExistsAsync(
    id: "adventureworks-2"
);

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