Créer un compte, une base de données et une collection avec Azure Cosmos DB for MongoDB

Effectué

Azure Cosmos DB est une plateforme en tant que service (Paas) entièrement gérée. Pour utiliser ce service, nous devons d’abord créer un compte Azure Cosmos DB sous notre abonnement. Une fois notre compte créé, nous pouvons y ajouter une base de données, des collections et des documents.

Nous examinons plusieurs façons de créer les différents éléments du modèle Azure Cosmos DB for MongoDB.

Créer un compte, une base de données et un conteneur pour Azure Cosmos DB for MongoDB à l’aide du Portail Azure

Une façon de créer notre compte Azure Cosmos DB et ses éléments consiste à utiliser le portail Azure. Dans cet exemple, nous utilisons le Portail Azure pour créer un compte Azure Cosmos DB avec Azure Cosmos DB for MongoDB. Nous ajoutons ensuite une base de données et une collection. Pour le moment, ne vous souciez pas des paramètres plus avancés. Nous les traiterons plus en détail dans les modules ultérieurs. Pour cet exemple, passons simplement en revue l’onglet Informations de base. Créons à présent notre compte et ses éléments.

Créer un compte pour Azure Cosmos DB for MongoDB

1. Dans le Portail Azure, sélectionnez + Créer une ressource, Azure Cosmos DB, puis Créer.

2. Sélectionnez Azure Cosmos DB for MongoDB.

3. Fournissez les paramètres suivants.

   • Abonnement - Votre abonnement Azure actuel.
   • Groupe de ressources - Groupe de ressources Azure nouveau ou existant pour y créer le compte Azure Cosmos DB.
   • Nom du compte - Nom unique de votre compte Azure Cosmos DB. Ce nom doit être unique dans Azure. Pour former l’URI de votre compte, mongo.cosmos.azure.com est ajouté à votre nom de compte.
   • Emplacement : emplacement géographique qui héberge votre compte Azure Cosmos DB. Vous devez généralement sélectionner un emplacement proche de vos utilisateurs ou applications.
   • Mode de capacité - Comme nous l’avons vu dans une unité précédente, vous pouvez sélectionner pour votre compte Débit provisionné ou Serverless. Sélectionnez Débit provisionné pour cet exemple.
   • Appliquer la remise de niveau gratuit - Sélectionnez Ne pas appliquer pour cet exemple.
   • Limiter le débit total du compte - Laissez décoché pour cet exemple.
   • Version - Sélectionnez 4.0.

   Notes

   Pour tirer meilleur parti des fonctionnalités prises en charge, nous vous recommandons d’utiliser les versions 3.6+ dans la mesure du possible.

4. Sélectionnez Vérifier + Créer, puis si la validation réussit, sélectionnez Créer.

Notes

La création de votre compte Azure Cosmos DB peut prendre plusieurs minutes.

Créer une base de données et un conteneur pour l’API Azure Cosmos DB for MongoDB

La création d’une base de données et d’un conteneur dans le portail Azure est simple. Commençons par créer une base de données.

1. Dans le menu de gauche Compte Azure Cosmos DB for MongoDB, sélectionnez Explorateur de données.

2. Sélectionnez la liste déroulante à droite de l’icône Nouvelle collection, puis sélectionnez Nouvelle base de données.

   

3. Donnez un nouveau nom à votre base de données sous la zone de texte ID de base de données.

4. Même s’il est possible de définir Provisionner le débit dans la boîte de dialogue Nouvelle base de données, vous sélectionnez le plus souvent votre débit provisionné au niveau du conteneur. Décochons la case Provisionner le débit et sélectionnons OK pour cet exemple.

   

   Nous devrions maintenant voir notre nouvelle base de données sous la section API MONGO. Il est temps de créer notre nouvelle collection.

5. Sélectionnez l’icône Nouvelle collection.

6. Entrez les paramètres suivants sous la boîte de dialogue Nouvelle collection.

   • Nom de la base de données : notez que vous avez deux options ici, Créer ou Utiliser existant. Cette option vous permet de créer une base de données au moment où vous créez la nouvelle collection. Étant donné que nous avons déjà créé une base de données dans nos étapes précédentes, sélectionnez Utiliser l’existante et choisissez le nom de la base de données dans les options de la liste déroulante.
   • ID de collection : ce paramètre est le nom que vous donnez à votre collection.
   • Partitionnement - Nous voulons généralement sélectionner Partitionné. Cette option permet à Azure Cosmos DB de créer des conteneurs partitionnés sur plusieurs locataires en fonction de la Clé de partition. Avec les grands conteneurs, Azure Cosmos DB répartit vos locataires sur plusieurs nœuds physiques pour atteindre un niveau élevé d’échelle. Nous abordons le partitionnement plus en détail dans le module Conception. Sélectionnez Partitionné.
     • Clé de partition : si vous sélectionnez Partitionné, vous devez ajouter une Clé de partition. Il s’agit de la clé de partition qui définit votre stratégie de partitionnement. Par exemple, dans une collection IoT (Internet des objets), cette clé peut être /deviceid ou éventuellement /region en fonction de la stratégie de partitionnement que vous choisissez. Nous abordons la stratégie de partitionnement plus en détail dans le module Conception.
     • Case à cocher Provisionner un débit dédié pour cette collection : en règle générale, vous voulez provisionner le débit de votre collection en mode Mise à l’échelle automatique ou Manuel. Ce paramètre vous permet de mieux maîtriser le coût de votre collection individuelle. Nous abordons le débit plus en détail dans le module Conception. Pour l’instant, cochez la case et sélectionnez Mise à l’échelle automatique.
     • Débit de collection ou Nombre maximal de RU/s de collection : selon que vous avez sélectionné Manuel ou Mise à l’échelle automatique, vous devez entrer respectivement le Débit de collection ou le Nombre maximal de RU/s de collection (en d’autres termes, le mode de débit). La principale différence est que le mode Manuel vous facture le nombre de RU/s choisi, que vous les utilisiez ou non. Le mode Mise à l’échelle automatique facture uniquement ce que vous utilisez jusqu’au nombre maximal de RU/s que vous avez sélectionné. Dans les deux cas, votre collection commence à être limitée une fois que son débit atteint la valeur sélectionnée. Laissez la valeur prédéfinie pour cet exemple.
     • Magasin analytique - Le magasin analytique Azure Cosmos DB n’entre pas dans le cadre de ces leçons. Pour plus d’informations à ce sujet, consultez l’article Qu’est-ce que le magasin analytique Azure Cosmos DB.
     • Avancé/Indexation : nous abordons les index plus en détail dans le module Conception. Laissez la case cochée.

Maintenant, nous devrions avoir une base de données et une collection auxquelles se connecter. Dans l’unité suivante, nous examinerons plus en détail la connexion à un compte Azure Cosmos DB for MongoDB. Mais avant, examinons une autre façon de créer nos bases de données et collections Azure Cosmos DB for MongoDB.

Créer ou se connecter à une base de données et une collection pour l’API Azure Cosmos DB for MongoDB

Vous devriez pouvoir créer votre compte Azure Cosmos DB for MongoDB ou vous y connecter en utilisant Java, Python, Node.js, .NET ou un autre langage de programmation avec un pilote MongoDB. Introduisons certaines fonctions que vous utiliseriez pour créer ces éléments à l’aide de certains des différents langages. Au début de ce module, nous avons indiqué que les développeurs peuvent continuer à utiliser les pilotes, kits SDK et outils MongoDB qu’ils connaissent pour se connecter à Azure Cosmos DB et créer des applications. Nous utilisons ces pilotes et leurs propriétés et méthodes pour programmer notre accès et nos opérations sur notre compte Azure Cosmos DB for MongoDB.

Créer ou se connecter à une base de données pour l’API Azure Cosmos DB for MongoDB

Vous pouvez utiliser votre outil de développement favori pour créer votre application Azure Cosmos DB for MongoDB. Nous utilisons le pilote MongoDB pour chaque langage de programmation afin de créer nos bases de données et nos collections. Examinons le code qui permet de se connecter aux comptes Azure Cosmos DB for MongoDB et de se connecter à la base de données products.

Node.js

import { DefaultAzureCredential, ClientSecretCredential } from "@azure/identity";
const { MongoClient, ObjectId } = require('mongodb');
import axios from "axios";

async function main() {
  // Environment variables
  const endpoint = process.env.AZURE_COSMOS_RESOURCEENDPOINT;
  const listConnectionStringUrl = process.env.AZURE_COSMOS_LISTCONNECTIONSTRINGURL;
  const scope = process.env.AZURE_COSMOS_SCOPE;

  // Uncomment the corresponding lines for the authentication type you want to use.
  // For system-assigned managed identity.
  // const credential = new DefaultAzureCredential();

  // For user-assigned managed identity.
  // const clientId = process.env.AZURE_COSMOS_CLIENTID;
  // const credential = new DefaultAzureCredential({
  //     managedIdentityClientId: clientId
  // });

  // For service principal.
  // const tenantId = process.env.AZURE_COSMOS_TENANTID;
  // const clientId = process.env.AZURE_COSMOS_CLIENTID;
  // const clientSecret = process.env.AZURE_COSMOS_CLIENTSECRET;
  // const credential = new ClientSecretCredential(tenantId, clientId, clientSecret);

  // Acquire the access token
  const accessToken = await credential.getToken(scope);

  // Get the connection string
  const config = {
    method: 'post',
    url: listConnectionStringUrl,
    headers: {
        'Authorization': 'Bearer ${accessToken.token}'
    }
  };
  const response = await axios(config);
  const keysDict = response.data;
  const connectionString = keysDict['connectionStrings'][0]['connectionString'];

  // Connect to Azure Cosmos DB for MongoDB
  const client = new MongoClient(connectionString);

  try {
    // Open the connection
    await client.connect();

    // Connect to the database "products"
    const ProductDatabase = client.db('products');

    // Add code to connect to a collection and add an entry here
  } catch (err) {
    console.error("An error occurred:", err);
  } finally {
    // Close the connection
    await client.close();
  }
}

main().catch((err) => console.error("Unhandled error:", err));

Java

package com.fabrikam;

import com.mongodb.MongoClient;
import com.mongodb.MongoClientURI;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoDatabase;
import com.mongodb.client.model.Filters;
import javax.net.ssl.*;
import java.net.InetSocketAddress;
import com.azure.identity.*;
import com.azure.core.credential.*;
import java.net.http.*;
import java.net.URI;

public class App {
  public static void main(String[] args) {
    // Environment variables
    String endpoint = System.getenv("AZURE_COSMOS_RESOURCEENDPOINT");
    String listConnectionStringUrl = System.getenv("AZURE_COSMOS_LISTCONNECTIONSTRINGURL");
    String scope = System.getenv("AZURE_COSMOS_SCOPE");

    // Uncomment the corresponding lines for the authentication type you want to use.
    // For system-assigned managed identity.
    // DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build();

    // For user-assigned managed identity.
    // DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder()
    //     .managedIdentityClientId(System.getenv("AZURE_COSMOS_CLIENTID"))
    //     .build();

    // For service principal.
    // ClientSecretCredential defaultCredential = new ClientSecretCredentialBuilder()
    //     .clientId(System.getenv("AZURE_COSMOS_CLIENTID"))
    //     .clientSecret(System.getenv("AZURE_COSMOS_CLIENTSECRET"))
    //     .tenantId(System.getenv("AZURE_COSMOS_TENANTID"))
    //     .build();

    MongoClient mongoClient = null;

    try {
      // Acquire the access token
      AccessToken accessToken = defaultCredential
          .getToken(new TokenRequestContext().addScopes(scope))
          .block();
      String token = accessToken.getToken();

      // Retrieve the connection string
      HttpClient client = HttpClient.newBuilder().build();
      HttpRequest request = HttpRequest.newBuilder()
          .uri(new URI(listConnectionStringUrl))
          .header("Authorization", "Bearer " + token)
          .POST(HttpRequest.BodyPublishers.noBody())
          .build();
      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

      JSONParser parser = new JSONParser();
      JSONObject responseBody = parser.parse(response.body());
      List<Map<String, String>> connectionStrings = responseBody.get("connectionStrings");
      String connectionString = connectionStrings.get(0).get("connectionString");

      // Connect to Azure Cosmos DB for MongoDB
      MongoClientURI uri = new MongoClientURI(connectionString);
      mongoClient = new MongoClient(uri);

      // Connect to the database
      MongoDatabase ProductDatabase = mongoClient.getDatabase("products");

      // Add code to connect to a collection and add an entry here

    } catch (Exception e) {
      e.printStackTrace();
    } finally {
      if (mongoClient != null) {
        mongoClient.close();
      }
    }
  }
}

Python

import os
import pymongo
import requests
from azure.identity import ManagedIdentityCredential, ClientSecretCredential

# Environment variables
endpoint = os.getenv('AZURE_COSMOS_RESOURCEENDPOINT')
listConnectionStringUrl = os.getenv('AZURE_COSMOS_LISTCONNECTIONSTRINGURL')
scope = os.getenv('AZURE_COSMOS_SCOPE')

# Uncomment the following lines corresponding to the authentication type you want to use.
# For system-assigned managed identity
# cred = ManagedIdentityCredential()

# For user-assigned managed identity
# managed_identity_client_id = os.getenv('AZURE_COSMOS_CLIENTID')
# cred = ManagedIdentityCredential(client_id=managed_identity_client_id)

# For service principal
# tenant_id = os.getenv('AZURE_COSMOS_TENANTID')
# client_id = os.getenv('AZURE_COSMOS_CLIENTID')
# client_secret = os.getenv('AZURE_COSMOS_CLIENTSECRET')
# cred = ClientSecretCredential(tenant_id=tenant_id, client_id=client_id, client_secret=client_secret)

# Get the connection string
session = requests.Session()
token = cred.get_token(scope)
response = session.post(listConnectionStringUrl, headers={"Authorization": "Bearer {}".format(token.token)})
keys_dict = response.json()
conn_str = keys_dict["connectionStrings"][0]["connectionString"]

# Connect to Azure Cosmos DB for MongoDB
client = pymongo.MongoClient(conn_str)

# To connect to the database, use the connection variable ("client" in this case), and the database name
ProductDatabase = client["products"]

# Add code to connect to a collection and add an entry here

C#

using MongoDB.Driver;
using Azure.Identity;
using Azure.Core;
using System;
using System.Net.Http;
using System.Text.Json;
using System.Collections.Generic;
using System.Threading.Tasks;

public class Products
{
  public int ProductId { get; set; }
  public string name { get; set; }
}

class test
{
  public static async Task Main(string[] args)
  {
      // Environment variables
      var endpoint = Environment.GetEnvironmentVariable("AZURE_COSMOS_RESOURCEENDPOINT");
      var listConnectionStringUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTCONNECTIONSTRINGURL");
      var scope = Environment.GetEnvironmentVariable("AZURE_COSMOS_SCOPE");

      // Uncomment the corresponding lines for the authentication type you want to use.
      // For system-assigned identity.
      // var tokenProvider = new DefaultAzureCredential();

      // For user-assigned identity.
      // var tokenProvider = new DefaultAzureCredential(
      //     new DefaultAzureCredentialOptions
      //     {
      //         ManagedIdentityClientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID")
      //     });

      // For service principal.
      // var tenantId = Environment.GetEnvironmentVariable("AZURE_COSMOS_TENANTID");
      // var clientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
      // var clientSecret = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTSECRET");
      // var tokenProvider = new ClientSecretCredential(tenantId, clientId, clientSecret);

      // Acquire the access token.
      AccessToken accessToken = await tokenProvider.GetTokenAsync(
          new TokenRequestContext(scopes: new[] { scope }));

      // Get the connection string.
      using var httpClient = new HttpClient();
      httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
      var response = await httpClient.PostAsync(listConnectionStringUrl, null);
      response.EnsureSuccessStatusCode();
      var responseBody = await response.Content.ReadAsStringAsync();

      // Parse the connection string.
      var connectionStrings = JsonSerializer.Deserialize<Dictionary<string, List<Dictionary<string, string>>>>(responseBody);
      string connectionString = connectionStrings["connectionStrings"][0]["connectionString"];

      // Initialize the MongoClient with the connection string.
      var mongoClient = new MongoClient(connectionString);

      // Connect to the "products" database.
      var ProductDatabase = mongoClient.GetDatabase("products");

      // Add code to connect to a collection and add an entry here.
  }
}

C’est aussi simple que cela : une fois que nous sommes connectés à l’aide du pilote, nous créons une base de données ou pointons vers une base de données existante avec GetDatabase ou des méthodes similaires selon le langage. Notre application peut maintenant utiliser la variable ProductDatabase pour faire référence à la base de données souhaitée. Créer une collection ou s’y connecter est aussi simple que de créer une base de données.

Créer une collection pour l’API Azure Cosmos DB for MongoDB

Pour créer une collection ou accéder à une collection existante, nous utilisons une référence ou une méthode d’obtention de collection selon le langage de programmation. Ajoutons du code à l’exemple précédent pour créer une collection/se connecter à une collection et ajouter une entrée à cette collection.

Node.js

          // Add code to connect to a collection and add and find an entry here 
          var collection = ProductDatabase.collection('documents');
          var insertResult = await collection.insertOne({ ProductId: 1, name: "bread" });

          // return data where ProductId = 1
          const findProduct = await collection.find({ProductId: 1});
          await findProduct.forEach(console.log);

Java

          // Add code to connect to a collection and add and find an entry here 
          MongoCollection collection = ProductDatabase.getCollection("products");

          collection.insertOne(new Document()
                      .append("ProductId", 1)
                      .append("name", "bread"));

          // return data where ProductId = 1
          Document findProduct = (Document) collection.find(eq("ProductId", 1)).first();
          System.out.println(findProduct.toJson());

Python

# Add code to connect to a collection and add an entry here 
collection = ProductDatabase["products"]
collection.insert_one({ "ProductId": 1, "name": "bread" })

C#

    // Add code to connect to a collection and add an entry here 
    var ProductCollection = ProductDatabase.GetCollection<Products>("products");

    Products Product = new Products {ProductId=1,name="bread"};
    ProductCollection.InsertOne (Product);

Dans l’unité suivante, nous verrons comment exactement nous avons créé notre chaîne de connexion.

Utiliser les commandes d’extension MongoDB pour gérer les données stockées dans les API d’Azure Cosmos DB pour MongoDB

Comme nous l’avons vu précédemment, Azure Cosmos DB for MongoDB nous donne la possibilité d’utiliser les mêmes pilotes et le même code que ceux que nous avons utilisés pour créer nos objets dans un serveur MongoDB pour notre compte Azure Cosmos DB. Toutefois, l’utilisation de ce code pour créer nos bases de données et collections se sert des paramètres de création Azure Cosmos DB par défaut. Pour tirer parti des fonctionnalités d’Azure Cosmos DB, nous devons pouvoir contrôler nos paramètres de création de base de données et de collection tels que le débit, la mise à l’échelle automatique, l’attribution de clés de partition et la définition d’index. Azure Cosmos DB for MongoDB nous offre cette possibilité en utilisant des commandes étendues pour définir ces paramètres. Ces commandes nous permettent de coder des instructions plus précises sur la création ou la modification de nos bases de données et de nos collections spécifiquement pour Azure Cosmos DB.

Azure Cosmos DB for MongoDB fournit des commandes d’extension pour les types de requêtes suivants :

• Créer une base de données
• Mettre à jour la base de données
• Obtenir une base de données
• Créer une collection
• Mettre à jour la collection
• Obtenir une collection

Les pilotes MongoDB fournissent une fonction pour exécuter une commande sur une base de données. Nous utilisons cette fonction pour envoyer nos commandes étendues à Azure Cosmos DB. Examinons le code permettant de créer une collection d’appareils IoT avec un débit de 2 000 RU (unités de requête) et la clé de partition DeviceId.

Node.js

    // create the Devices collection with a throughput of 2000 RUs and with DeviceId as the sharding key
    var result = IOTDatabase.command({customAction: "CreateCollection", collection: "Devices", offerThroughput: 2000, shardKey: "DeviceId"});

Java

      // create the Devices collection with a throughput of 2000 RUs and with DeviceId as the sharding key
      Document DevCollectionDef = new Document();
      DevCollectionDef.append("customAction", "CreateCollection");
      DevCollectionDef.append("collection", "Devices");
      DevCollectionDef.append("offerThroughput", 2000);
      DevCollectionDef.append("shardKey", "DeviceId");

      Document result = IOTDatabase.runCommand(DevCollectionDef);

Python

      # create the Devices collection with a throughput of 2000 RUs and with DeviceId as the sharding key
      IOTDatabase.command({'customAction': "CreateCollection", 'collection': "Devices", 'offerThroughput': 2000, 'shardKey': "DeviceId"})

C#

      // create the Devices collection with a throughput of 1000 RUs and with EmployeeId as the sharding key
      var result = IOTDatabase.RunCommand<BsonDocument>(@"{customAction: ""CreateCollection"", collection: ""Devices"", offerThroughput: 2000, shardKey: ""DeviceId""}");

De la même façon, nous pouvons modifier une collection ou créer/modifier une base de données. Pour plus d’informations, consultez l’article Utiliser les commandes d’extension MongoDB pour gérer les données stockées dans l’API Azure Cosmos DB pour MongoDB.