Tutoriel : Connecter une application web Node.js avec Azure DocumentDB

Dans ce tutoriel, vous créez une application web Node.js qui se connecte à Azure DocumentDB. La pile MongoDB, Express, React.js, Node.js (MERN) est une collection populaire de technologies utilisées pour créer de nombreuses applications web modernes. Avec Azure DocumentDB, vous pouvez créer une nouvelle application web ou migrer une application existante à l’aide de pilotes MongoDB que vous connaissez déjà. Dans ce tutoriel, vous allez :

• Configurer votre environnement
• Tester l’application MERN avec un conteneur MongoDB local
• Tester l’application MERN avec un cluster
• Déployer l’application MERN sur Azure App Service

Prerequisites

Pour effectuer ce didacticiel, vous avez besoin des ressources suivantes :

• Un abonnement Azure

  • Si vous n’avez pas d’abonnement Azure, créez un compte gratuit

• Un cluster Azure DocumentDB existant

  • Si vous n’avez pas de cluster, créez un cluster

• Un compte GitHub avec l'accès GitHub Codespaces

Configurer l’environnement de développement

Un environnement de conteneur de développement est disponible avec toutes les dépendances requises pour effectuer chaque exercice de ce projet. Vous pouvez exécuter le conteneur de développement dans GitHub Codespaces ou localement à l’aide de Visual Studio Code.

GitHub Codespaces

GitHub Codespaces exécute un conteneur de développement géré par GitHub avec Visual Studio Code pour le web comme interface utilisateur. Pour l’environnement de développement le plus simple, utilisez GitHub Codespaces afin que vous disposiez des outils de développement et des dépendances appropriés préinstallés pour terminer ce module d’apprentissage.

Important

Tous les comptes GitHub peuvent utiliser des espaces de code pour jusqu’à 60 heures gratuites chaque mois avec deux instances principales.

1. Démarrez le processus pour créez un environnement GitHub Codespace sur la branche main du référentiel GitHub azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app.

   

2. Dans la page Créer un espace de code , passez en revue les paramètres de configuration de l’espace de code, puis sélectionnez Créer un espace de code

   

3. Attendez que le codespace démarre. Ce processus de démarrage peut prendre quelques minutes.

4. Ouvrez un nouveau terminal dans l’espace de code.

   Conseil / Astuce

   Vous pouvez utiliser le menu principal pour accéder à l’option de menu Terminal , puis sélectionner l’option Nouveau terminal .

   

5. Consultez les versions des outils que vous utilisez dans ce tutoriel.

   docker --version
   
   node --version
   
   npm --version
   
   az --version
   

   Note

   Ce tutoriel nécessite les versions suivantes de chaque outil, qui sont préinstallées dans votre environnement :

   Tool	Version
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   npm	≥ 9.5.0
   Azure CLI	≥ 2.46.0

6. Fermez le terminal.

7. Les étapes restantes de ce didacticiel ont lieu dans le contexte de ce conteneur de développement.

Visual Studio Code

L’extension Dev Containers pour Visual Studio Code nécessite l’installation de Docker sur votre ordinateur local. L’extension héberge le conteneur de développement localement à l’aide de l’hôte Docker avec les outils de développement et les dépendances appropriés préinstallés pour terminer ce module d’apprentissage.

1. Ouvrez Visual Studio Code dans le contexte d’un répertoire vide.

2. Vérifiez que l’extension Dev Containers est installée dans Visual Studio Code.

3. Ouvrez un nouveau terminal dans l’éditeur.

   Conseil / Astuce

   Vous pouvez utiliser le menu principal pour accéder à l’option de menu Terminal , puis sélectionner l’option Nouveau terminal .

   Capture d’écran de l’option de menu permettant d’ouvrir un nouveau terminal.

4. Clonez le azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app référentiel GitHub dans le répertoire actif.

   git clone https://github.com/azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app.git .
   

5. Ouvrez la palette de commandes, recherchez les commandes Conteneurs de développement, puis sélectionnez Conteneurs de développement : rouvrir dans conteneur.

   

   Conseil / Astuce

   Visual Studio Code peut vous inviter automatiquement à rouvrir le dossier existant dans un conteneur de développement. Cette étape est fonctionnellement équivalente à l’utilisation de la palette de commandes pour rouvrir l’espace de travail actuel dans un conteneur.

   

6. Consultez les versions des outils que vous utilisez dans ce tutoriel.

   docker --version
   
   node --version
   
   npm --version
   
   az --version
   

   Note

   Ce tutoriel nécessite les versions suivantes de chaque outil, qui sont préinstallées dans votre environnement :

   Tool	Version
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   npm	≥ 9.5.0
   Azure CLI	≥ 2.46.0

7. Fermez le terminal.

8. Les étapes restantes de ce didacticiel ont lieu dans le contexte de ce conteneur de développement.

Tester l’API de l’application MERN avec le conteneur MongoDB

Commencez par exécuter l’API de l’exemple d’application avec le conteneur MongoDB local pour vérifier que l’application fonctionne.

1. Exécutez un conteneur MongoDB à l’aide de Docker et publiez le port MongoDB standard (27017).

   docker pull mongo:6.0
   
   docker run --detach --publish 27017:27017 mongo:6.0
   

2. Dans la barre latérale, sélectionnez l’extension MongoDB.

   

3. Ajoutez une nouvelle connexion à l’extension MongoDB à l’aide de la chaîne mongodb://localhostde connexion.

   

4. Une fois la connexion établie, ouvrez le fichier de playground data/products.mongodb.

5. Sélectionnez l’icône Exécuter tout pour exécuter le script.

   

6. L'exécution du code dans un environnement de test devrait aboutir à une liste de documents dans la collection MongoDB locale. Voici un exemple tronqué de la sortie.

   [
     {
       "_id": { "$oid": "640a146e89286b79b6628eef" },
       "name": "Confira Watch",
       "category": "watches",
       "price": 105
     },
     {
       "_id": { "$oid": "640a146e89286b79b6628ef0" },
       "name": "Diannis Watch",
       "category": "watches",
       "price": 98,
       "sale": true
     },
     ...
   ]
   

   Note

   Les identificateurs d’objet (_id) sont générés de façon aléatoire et diffèrent de cet exemple de sortie tronqué.

7. Dans le serveur/ répertoire, créez un fichier .env .

8. Dans le fichier server/.env , ajoutez une variable d’environnement pour cette valeur :

   Variable d’environnement	Valeur
   CONNECTION_STRING	Chaîne de connexion au cluster Azure DocumentDB. Pour l’instant, utilisez mongodb://localhost:27017?directConnection=true.

   CONNECTION_STRING=mongodb://localhost:27017?directConnection=true
   

9. Remplacez le contexte du terminal par le serveur/ dossier.

   cd server
   

10. Installez les dépendances à partir du Gestionnaire de package node (npm).

    npm install
    

11. Démarrez l’application Node.js &Express.

    npm start
    

12. L’API ouvre automatiquement une fenêtre de navigateur pour vérifier qu’elle retourne un tableau de documents produits.

13. Fermez l’onglet/la fenêtre du navigateur supplémentaire.

14. Fermez le terminal.

Tester l’application MERN avec le cluster Azure DocumentDB

À présent, nous allons vérifier que l’application fonctionne en toute transparence avec Azure DocumentDB. Pour cette tâche, renseignez le cluster préexistant avec des données initiales à l’aide de l’interpréteur de commandes MongoDB, puis mettez à jour la chaîne de connexion de l’API.

1. Connectez-vous au portail Azure (https://portal.azure.com).

2. Accédez à la page de cluster Azure DocumentDB existante.

3. Dans la page du cluster Azure DocumentDB, sélectionnez l’option de menu de navigation Chaînes de connexion.

   

4. Enregistrez la valeur du champ chaîne de connexion .

   

   Important

   La chaîne de connexion dans le portail n’inclut pas les valeurs de nom d’utilisateur et de mot de passe. Vous devez remplacer les espaces réservés <user> et <password> par les informations d’identification que vous avez utilisées lors de la création initiale du cluster.

5. Ouvrez un nouveau terminal dans votre environnement de développement intégré (IDE).

6. Démarrez l’interpréteur de commandes MongoDB à l’aide de la commande mongosh et de la chaîne de connexion que vous avez enregistrée précédemment. Assurez-vous de remplacer les espaces réservés <user> et <password> par les informations d’identification que vous avez utilisées lors de la création initiale du cluster.

   mongosh "<mongodb-cluster-connection-string>"
   

   Note

   Vous devrez peut-être encoder des valeurs spécifiques pour la chaîne de connexion. Dans cet exemple, le nom du cluster est msdocs-azure-documentdb-tutorial, le nom d’utilisateur est clusteradminet le mot de passe est P@ssw.rd. Dans le mot de passe, le caractère @ doit être encodé à l’aide de %40. Un exemple de chaîne de connexion est fourni ici avec l’encodage correct du mot de passe.

   CONNECTION_STRING=mongodb+srv://clusteradmin:P%40ssw.rd@msdocs-azure-documentdb-tutorial.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000
   

7. Dans le terminal, exécutez les commandes suivantes pour créer votre base de données, votre collection et pour initialiser avec des données de démarrage.

   use('cosmicworks');
   
   db.products.drop();
   
   db.products.insertMany([
     { name: "Confira Watch", category: "watches", price: 105.00 },
     { name: "Diannis Watch", category: "watches", price: 98.00, sale: true },
     { name: "Sterse Gloves", category: "gloves", price: 42.00 },
     { name: "Peache Sunglasses", category: "eyewear", price: 32.00, sale: false, sizes: [ "S", "M", "L" ] },
     { name: "Icento Pack", category: "bags", price: 58.00 },
     { name: "Iroowl Bracelet", category: "watches", price: 66.00 },
     { name: "Glaark Bag", category: "bags", price: 56.00, sale: true },
     { name: "Windry Mittens", category: "gloves", price: 35.00 },
     { name: "Tuvila Hat", category: "hats", price: 120.00 },
     { name: "Klinto Hat", category: "hats", subcategory: "hats-beanies", price: 65.00 }
   ]);
   
   db.products.find({});
   

8. Les commandes doivent générer une liste de documents dans la collection MongoDB locale. Voici un exemple tronqué de la sortie.

   [
     {
       "_id": { "$oid": "640a146e89286b79b6628eef" },
       "name": "Confira Watch",
       "category": "watches",
       "price": 105
     },
     {
       "_id": { "$oid": "640a146e89286b79b6628ef0" },
       "name": "Diannis Watch",
       "category": "watches",
       "price": 98,
       "sale": true
     },
     ...
   ]
   

   Note

   Les identificateurs d’objet (_id) sont générés de façon aléatoire et diffèrent de cet exemple de sortie tronqué.

9. Quittez l’interpréteur de commandes MongoDB.

   exit
   

10. Dans le répertoire client/, créez un fichier .env .

11. Dans le fichier client/.env , ajoutez une variable d’environnement pour cette valeur :

    Variable d’environnement	Valeur
    CONNECTION_STRING	Chaîne de connexion au cluster Azure DocumentDB. Utilisez la même chaîne de connexion que celle utilisée avec l’interpréteur de commandes mongo.

    CONNECTION_STRING=<your-connection-string>
    

12. Vérifiez que l’application utilise le service de base de données en modifiant le contexte du terminal vers le serveur/ dossier, en installant les dépendances à partir du Gestionnaire de package node (npm), puis en démarrant l’application.

    cd server
    
    npm install
    
    npm start
    

13. L’API ouvre automatiquement une fenêtre de navigateur pour vérifier qu’elle retourne un tableau de documents produits.

14. Fermez l’onglet/la fenêtre du navigateur supplémentaire. Ensuite, fermez le terminal.

Déployer l’application MERN sur Azure App Service

Prouvez que l’application fonctionne de bout en bout en déployant le service et le client sur Azure App Service. Utilisez des secrets dans les applications web pour stocker des variables d’environnement avec des informations d’identification et des points de terminaison d’API.

1. Dans votre environnement de développement intégré (IDE), ouvrez un nouveau terminal.

2. Créez une variable shell pour le nom du groupe de ressources préexistant nommé resourceGroupName.

   # Variable for resource group name
   resourceGroupName="<existing-resource-group>"
   

3. Créez des variables d’interpréteur de commandes pour les deux applications web nommées serverAppName et clientAppName.

   # Variable for randomnly generated suffix
   let suffix=$RANDOM*$RANDOM
   
   # Variable for web app names with a randomnly generated suffix
   serverAppName="server-app-$suffix"
   clientAppName="client-app-$suffix"
   

4. Si ce n’est déjà fait, connectez-vous à Azure CLI à l’aide de la az login --use-device-code commande.

5. Remplacez le répertoire de travail actuel par le serveur/ chemin d’accès.

   cd server
   

6. Créez une application web pour le composant serveur de l’application MERN avec az webapp up.

   az webapp up \
       --resource-group $resourceGroupName \
       --name $serverAppName \
       --sku F1 \
       --runtime "NODE|18-lts"
   

7. Créez un paramètre de chaîne de connexion pour l’application web serveur nommée CONNECTION_STRING avec az webapp config connection-string set. Utilisez la même valeur pour la chaîne de connexion que vous avez utilisée avec l’interpréteur de commandes MongoDB et le fichier .env précédemment dans ce tutoriel.

   az webapp config connection-string set \
       --resource-group $resourceGroupName \
       --name $serverAppName \
       --connection-string-type custom \
       --settings "CONNECTION_STRING=<mongodb-connection-string>"
   

8. Obtenez l’URI de l’application web du serveur avec az webapp show, et stockez-la dans une variable shell nommée d serverUri.

   serverUri=$(az webapp show \
       --resource-group $resourceGroupName \
       --name $serverAppName \
       --query hostNames[0] \
       --output tsv)
   

9. Utilisez le package open-cli et la commande de NuGet avec npx pour ouvrir une fenêtre de navigateur en utilisant l’URI de l'application web du serveur. Vérifiez que l’application serveur retourne vos données de tableau JSON à partir du cluster.

   npx open-cli "https://$serverUri/products" --yes
   

   Conseil / Astuce

   Parfois, les déploiements peuvent se terminer de façon asynchrone. Si vous ne voyez pas ce que vous attendez, attendez une minute et actualisez votre fenêtre de navigateur.

10. Changez le répertoire de travail vers le chemin client/.

    cd ../client
    

11. Créez une application web pour le composant client de l’application MERN avec az webapp up.

    az webapp up \
        --resource-group $resourceGroupName \
        --name $clientAppName \
        --sku F1 \
        --runtime "NODE|18-lts"
    

12. Créez un paramètre d’application pour l’application web cliente nommée REACT_APP_API_ENDPOINT avec az webapp config appsettings set. Utilisez le point de terminaison de l’API du serveur stocké dans la variable shell serverUri .

    az webapp config appsettings set \
        --resource-group $resourceGroupName \
        --name $clientAppName \
        --settings "REACT_APP_API_ENDPOINT=https://$serverUri"
    

13. Obtenez l'URI de l'application web cliente avec az webapp show et stockez-la dans une variable shell nommée clientUri.

    clientUri=$(az webapp show \
        --resource-group $resourceGroupName \
        --name $clientAppName \
        --query hostNames[0] \
        --output tsv)
    

14. Utilisez le package NuGet et la commande open-cli avec npx pour ouvrir une fenêtre de navigateur avec l’URI de l’application web cliente. Vérifiez que l’application cliente affiche des données à partir de l’API de l’application serveur.

    npx open-cli "https://$clientUri" --yes
    

    Conseil / Astuce

    Parfois, les déploiements peuvent se terminer de façon asynchrone. Si vous ne voyez pas ce que vous attendez, attendez une minute et actualisez votre fenêtre de navigateur.

15. Fermez le terminal.

Nettoyer les ressources

Lorsque vous travaillez dans votre propre abonnement, il est judicieux à la fin d’un projet de supprimer les ressources dont vous n’avez plus besoin. Les ressources qui restent actives peuvent vous coûter de l’argent. Vous pouvez supprimer des ressources individuellement ou supprimer le groupe de ressources pour supprimer l’ensemble des ressources.

1. Pour supprimer l’ensemble du groupe de ressources, utilisez az group delete.

   az group delete \
       --name $resourceGroupName \
       --yes
   

2. Vérifiez que le groupe de ressources est supprimé à l’aide de az group list.

   az group list
   

Nettoyer l’environnement de développement

Vous pouvez également souhaiter nettoyer votre environnement de développement ou le retourner à son état typique.

GitHub Codespaces

La suppression de l’environnement GitHub Codespaces vous permet d’optimiser le nombre d’heures gratuites par cœur que vous obtenez pour votre compte.

1. Connectez-vous au tableau de bord GitHub Codespaces (https://github.com/codespaces).

2. Localisez votre conteneur de développement actuellement en cours d’exécution, provenant du dépôt GitHub azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app.

   

3. Ouvrez le menu contextuel de l’espace de code, puis sélectionnez Supprimer.

   

Visual Studio Code

Vous n’êtes pas nécessairement obligé de nettoyer votre environnement local, mais vous pouvez arrêter le conteneur de développement en cours d’exécution et revenir à l’exécution de Visual Studio Code dans le contexte d’un espace de travail local.

1. Ouvrez la palette de commandes, recherchez les commandes Conteneurs de développement, puis sélectionnez Conteneurs de développement : rouvrir le dossier localement.

   Capture d’écran de l’option de palette de commandes pour rouvrir le dossier actuel dans votre environnement local.

Conseil / Astuce

Visual Studio Code arrête le conteneur de développement en cours d’exécution, mais le conteneur existe toujours dans Docker dans un état arrêté. Vous pouvez toujours supprimer l’instance de conteneur, l’image conteneur et les volumes de Docker pour libérer davantage d’espace sur votre ordinateur local.

Étape suivante

Migrer vos données