Démarrage rapide : Pilote Azure Cosmos DB for MongoDB pour Node.js

S’APPLIQUE À : MongoDB

Bien démarrer avec le package npm MongoDB pour créer des bases de données, des collections et des documents dans votre ressource Azure Cosmos DB. 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 sous la forme d’un projet JavaScript.

Documentation de référence sur l’API pour MongoDB | Package MongoDB (NuGet)

Prérequis

Vérification du prérequis

  • Dans une fenêtre de terminal ou de commande, exécutez node --version pour vérifier que Node.js fait bien partie des versions LTS.
  • 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 DB et dans la configuration d’un projet qui utilise le package npm MongoDB.

Créer un compte Azure Cosmos DB

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

  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 Azure Cosmos DB for MongoDB avec les paramètres par défaut.

    az cosmosdb create \
        --resource-group $resourceGroupName \
        --name $accountName \
        --locations regionName=$location
        --kind MongoDB
    

Obtenir la chaîne de connexion MongoDB

  1. Recherchez la chaîne de connexion de l’API MongoDB dans la liste des chaînes de connexion du compte à l’aide de la commande az cosmosdb keys list.

    az cosmosdb keys list --type connection-strings \
        --resource-group $resourceGroupName \
        --name $accountName 
    
  2. Enregistrez les valeurs de CLÉ PRIMAIRE. Vous aurez besoin de ces informations d’identification ultérieurement.

Créer une application JavaScript

Créez une application JavaScript dans un dossier vide à l’aide du terminal de votre choix. Utilisez la commande npm init pour commencer les invites afin de créer le fichier package.json. Acceptez les valeurs par défaut pour les invites.

npm init

Installer le package

Ajoutez le package npm MongoDB npm au projet JavaScript. Utilisez la commande npm install package en spécifiant le nom du package npm. Le package dotenv est utilisé pour lire les variables d’environnement à partir d’un fichier .env pendant le développement local.

npm install mongodb dotenv

Configuration des variables d’environnement

Pour utiliser les valeurs de CHAÎNE DE CONNEXION dans votre code, définissez cette valeur dans l’environnement 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_CONNECTION_STRING = "<cosmos-connection-string>"

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 collections et de documents.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, collections, and docs.

Diagramme hiérarchique montrant un compte Azure Cosmos DB au sommet. Le compte présente deux partitionnements de base de données enfants. L’un des partitionnements de base de données comprend deux partitions de collection enfants. L'autre partitionnement de base de données comprend un seul nœud de collecte enfant. Cette partition de collection unique comporte trois partitions de documents enfants.

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

  • MongoClient - Cette classe fournit une représentation logique côté client pour la couche d’API for MongoDB dans Cosmos DB. Ce client est utilisé pour configurer et exécuter des requêtes sur le service.
  • Db : 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.
  • Collection : Cette classe est une référence à une collection qui n’existe pas encore dans le service. La collection est validée côté serveur lorsque vous tentez de l’utiliser.

Exemples de code

L’exemple de code décrit dans cet article crée une base de données nommée adventureworks avec une collection nommée products. La collection 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 cette procédure, la base de données n’utilise pas de partitionnement.

Authentifier le client

  1. À partir du répertoire du projet, créez un fichier index.js. Dans votre éditeur, ajoutez les instructions nécessaires pour référencer les packages npm MongoDB et DotEnv.

    // Read .env file and set environment variables
    require('dotenv').config();
    const random = Math.floor(Math.random() * 100);
    
    // Use official mongodb driver to connect to the server
    const { MongoClient, ObjectId } = require('mongodb');
    
  2. Définissez une nouvelle instance de la classe MongoClient, à l’aide du constructeur, ainsi que process.env. pour lire la variable d’environnement que vous avez créée précédemment.

    // New instance of MongoClient with connection string
    // for Cosmos DB
    const url = process.env.COSMOS_CONNECTION_STRING;
    const client = new MongoClient(url);
    

Pour plus d’informations sur les différentes façons de créer une instance MongoClient, consultez Guide de démarrage rapide sur le pilote NodeJS MongoDB.

Configurer les opérations asynchrones

Dans le fichier index.js, ajoutez le code suivant pour prendre en charge les opérations asynchrones :

async function main(){

// The remaining operations are added here
// in the main function

}

main()
  .then(console.log)
  .catch(console.error)
  .finally(() => client.close());

Les extraits de code suivants doivent être ajoutés à la fonction main pour gérer la syntaxe async/await.

Se connecter à la base de données

Utilisez la méthode MongoClient.connect afin de vous connecter à votre ressource Azure Cosmos DB for MongoDB. Cette méthode de connexion retourne une référence à la base de données.

// Use connect method to connect to the server
await client.connect();

Obtenir une instance de base de données

Utiliser MongoClient.db obtient une référence à une base de données.

// Database reference with creation if it does not already exist
const db = client.db(`adventureworks`);
console.log(`New database:\t${db.databaseName}\n`);

Obtenir une instance de collection

MongoClient.Db.collection obtient une référence à une collection.

// Collection reference with creation if it does not already exist
const collection = db.collection('products');
console.log(`New collection:\t${collection.collectionName}\n`);

Instances chaînées

Vous pouvez chaîner le client, la base de données et la collection ensemble. Le chaînage est plus pratique si vous devez accéder à plusieurs bases de données ou collections.

const db = await client.db(`adventureworks`).collection('products').updateOne(query, update, options)

Création d'un index

Utilisez l’index Collection.createIndex pour créer un index sur les propriétés du document que vous envisagez d’utiliser pour le tri avec la méthode MongoDB FindCursor.sort.

// create index to sort by name
const indexResult = await collection.createIndex({ name: 1 });
console.log(`indexResult: ${JSON.stringify(indexResult)}\n`);

Créer un document

Créez un document avec les propriétés product pour la base de données adventureworks :

  • Propriété _id de l’identificateur unique du produit.
  • Propriété category. Cette propriété peut être utilisée comme clé de partition logique.
  • Propriété name.
  • Propriété quantity de l’inventaire.
  • Propriété sale, indiquant si le produit est en vente.
// Create new doc and upsert (create or replace) to collection
const product = {
    category: "gear-surf-surfboards",
    name: `Yamba Surfboard-${random}`,
    quantity: 12,
    sale: false
};
const query = { name: product.name};
const update = { $set: product };
const options = {upsert: true, new: true};

// Insert via upsert (create or replace) doc to collection directly
const upsertResult1 = await collection.updateOne(query, update, options);
console.log(`upsertResult1: ${JSON.stringify(upsertResult1)}\n`);

// Update via upsert on chained instance
const query2 = { _id: ObjectId(upsertResult1.upsertedId) };
const update2 = { $set: { quantity: 20 } };
const upsertResult2 = await client.db(`adventureworks`).collection('products').updateOne(query2, update2, options);
console.log(`upsertResult2: ${JSON.stringify(upsertResult2)}\n`);

Créez un document dans la collecte en appelant Collection.UpdateOne. Dans cet exemple, nous avons choisi de faire un upsert au lieu de créer (create) un document au cas où vous deviez exécuter cet exemple de code plusieurs fois.

Obtenir un document

Dans Azure Cosmos DB, vous pouvez effectuer une opération de lecture de point moins coûteuse à l’aide de l’identificateur unique (_id) et de la clé de partition (category).

// Point read doc from collection:
// - without sharding, should use {_id}
// - with sharding,    should use {_id, partitionKey }, ex: {_id, category}
const foundProduct = await collection.findOne({
    _id: ObjectId(upsertResult1.upsertedId), 
    category: "gear-surf-surfboards"
});
console.log(`foundProduct: ${JSON.stringify(foundProduct)}\n`);

Interroger des documents

Après avoir inséré un document, vous pouvez exécuter une requête pour obtenir tous les documents qui correspondent à un filtre spécifique. Cet exemple recherche tous les documents qui correspondent à une catégorie spécifique : gear-surf-surfboards. Une fois la requête définie, appelez Collection.find pour obtenir un résultat FindCursor. Convertissez le curseur en tableau pour utiliser des méthodes de tableau JavaScript.

// select all from product category
const allProductsQuery = { 
    category: "gear-surf-surfboards" 
};

// get all documents, sorted by name, convert cursor into array
const products = await collection.find(allProductsQuery).sort({name:1}).toArray();
products.map((product, i ) => console.log(`${++i} ${JSON.stringify(product)}`));

Résolution des problèmes :

  • Si vous obtenez une erreur telle que The index path corresponding to the specified order-by item is excluded., vérifiez que vous avez créé l’index.

Exécuter le code

Cette application crée une base de données et une collection d’API pour MongoDB et crée un document, puis lit exactement le même document. Enfin, l’exemple émet une requête qui ne doit retourner que ce document. À chaque étape, l’exemple génère des informations dans la console à propos des étapes qu’il 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.

node index.js

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

New database:   adventureworks

New collection: products

upsertResult1: {"acknowledged":true,"modifiedCount":0,"upsertedId":"62b1f492ff69395b30a03169","upsertedCount":1,"matchedCount":0}

upsertResult2: {"acknowledged":true,"modifiedCount":1,"upsertedId":null,"upsertedCount":0,"matchedCount":1}

foundProduct: {"_id":"62b1f492ff69395b30a03169","name":"Yamba Surfboard-93","category":"gear-surf-surfboards","quantity":20,"sale":false}

indexResult: "name_1"

1 {"_id":"62b1f47dacbf04e86c8abf25","name":"Yamba Surfboard-11","category":"gear-surf-surfboards","quantity":20,"sale":false}
done

Nettoyer les ressources

Une fois que vous n’avez plus besoin du compte Azure Cosmos DB for MongoDB, 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 vu comment créer un compte Azure Cosmos DB for MongoDB, créer une base de données et créer une collection à l’aide du pilote MongoDB. Vous pouvez maintenant explorer plus en détail Azure Cosmos DB for MongoDB pour importer davantage de données, effectuer des requêtes complexes et gérer vos ressources MongoDB Azure Cosmos DB.