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.

Documentation de référence sur l’API pour MongoDB | Package MongoDB (NuGet) packages/Microsoft.Azure.Cosmos) | Azure Developer CLI

Prérequis

Configuration

Déployez le conteneur de développement de ce projet sur votre environnement. Utilisez ensuite l’interface Azure Developer CLI (azd) pour créer un compte Azure Cosmos DB for MongoDB et déployer un exemple d’application conteneurisée. L’exemple d’application utilise la bibliothèque de client pour gérer, créer, lire et interroger des exemples de données.

1. Ouvrez un terminal dans le répertoire racine du projet.

2. Authentifiez-vous auprès de l’interface Azure Developer CLI en utilisant azd auth login. Suivez les étapes spécifiées par l’outil pour vous authentifier auprès de l’interface CLI à l’aide de vos informations d’identification Azure préférées.

   azd auth login
   

3. Utilisez azd init pour initialiser le projet.

   azd init --template cosmos-db-mongodb-nodejs-quickstart
   

   Remarque

   Ce guide de démarrage rapide utilise le référentiel GitHub du modèle azure-samples/cosmos-db-mongodb-nodejs-quickstart. Azure Developer CLI clone automatiquement ce projet sur votre machine s’il ne s’y trouve pas déjà.

4. Lors de l’initialisation, configurez un nom d’environnement unique.

   Conseil

   Le nom de l’environnement sera également utilisé comme nom du groupe de ressources cible. Pour ce guide de démarrage rapide, utilisez msdocs-cosmos-db.

5. Déployez le compte Azure Cosmos DB en utilisant azd up. Les modèles Bicep déploient également un exemple d’application web.

   azd up
   

6. Pendant le processus d’approvisionnement, sélectionnez votre abonnement et l’emplacement souhaité. Attendez la fin du processus de provisionnement. Le processus peut prendre environ cinq minutes.

7. Une fois le provisionnement de vos ressources Azure effectué, une URL vers l’application web en cours d’exécution est incluse dans la sortie.

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. Utilisez l’URL dans la console pour accéder à votre application web dans le navigateur. Observez la sortie de l’application en cours d’exécution.

   

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

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.

Utilisez 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 exister ou non 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 peut-être pas encore dans le service. La collection est validée côté serveur lorsque vous tentez de l’utiliser.

Exemples de code

• Authentifier le client
• Obtenir une instance de base de données
• Obtenir une instance de collection
• Utiliser des méthodes chaînées
• Création d'un index
• Créer un document
• Obtenir un document
• Exécuter des requêtes

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 unique. Avec chaque étape, l’exemple génère des informations dans la console sur les étapes 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.

az group delete --name $resourceGroupName

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

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