Lernprogramm: Verbinden einer Node.js Web-App mit Azure DocumentDB

In diesem Lernprogramm erstellen Sie eine Node.js Webanwendung, die eine Verbindung mit Azure DocumentDB herstellt. Der MongoDB-, Express-, React.js-, Node.js (MERN)-Stapel ist eine beliebte Sammlung von Technologien, mit denen viele moderne Webanwendungen erstellt werden. Mit Azure DocumentDB können Sie eine neue Webanwendung erstellen oder eine vorhandene Anwendung mithilfe von MongoDB-Treibern migrieren, mit denen Sie bereits vertraut sind. In diesem Tutorial erfahren Sie:

• Richten Sie Ihre Umgebung ein
• Testen der MERN-Anwendung mit einem lokalen MongoDB-Container
• Testen der MERN-Anwendung mit einem Cluster
• Bereitstellen der MERN-Anwendung für Azure App Service

Voraussetzungen

Für dieses Tutorial benötigen Sie die folgenden Ressourcen:

• Ein Azure-Abonnement

  • Wenn Sie nicht über ein Azure-Abonnement verfügen, erstellen Sie ein kostenloses Konto

• Ein vorhandener Azure DocumentDB-Cluster

  • Wenn Sie keinen Cluster haben, erstellen Sie einen neuen Cluster.

• Ein GitHub-Konto mit GitHub Codespaces-Berechtigungen

Konfigurieren der Entwicklungsumgebung

Eine Entwicklungscontainerumgebung ist mit allen Abhängigkeiten verfügbar, die erforderlich sind, um jede Übung in diesem Projekt abzuschließen. Sie können den Entwicklungscontainer in GitHub Codespaces oder lokal mit Visual Studio Code ausführen.

GitHub-Codespaces

GitHub Codespaces führt einen Entwicklungscontainer aus, der von GitHub mit Visual Studio Code für das Web als Benutzeroberfläche verwaltet wird. Verwenden Sie für die einfachste Entwicklungsumgebung GitHub Codespaces, damit Sie die richtigen Entwicklertools und Abhängigkeiten vorinstalliert haben, um dieses Schulungsmodul abzuschließen.

Von Bedeutung

Alle GitHub-Konten können Codespaces für bis zu 60 Stunden kostenlos jeden Monat mit zwei Kerninstanzen verwenden.

1. Starten Sie den Prozess, um einen neuen GitHub Codespace im Branch main des GitHub-Repositorys azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app zu erstellen.

   

2. Überprüfen Sie auf der Seite Erstellen von Codespace- die Codespace-Konfigurationseinstellungen, und wählen Sie dann Neuen Codespace erstellen

   

3. Warten Sie, bis der Codespace gestartet wird. Dieser Startvorgang kann einige Minuten dauern.

4. Öffnen Sie ein neues Terminal im Codespace.

   Tipp

   Sie können das Hauptmenü verwenden, um zur Menüoption " Terminal " zu navigieren und dann die Option "Neues Terminal " auszuwählen.

   

5. Überprüfen Sie die Versionen der Tools, die Sie in diesem Lernprogramm verwenden.

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

   Hinweis

   Dieses Lernprogramm erfordert die folgenden Versionen jedes Tools, die in Ihrer Umgebung vorinstalliert sind:

   Tool	Version
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   npm	≥ 9.5.0
   Azure-Befehlszeilenschnittstelle (Azure CLI)	≥ 2.46.0

6. Schließen Sie das Terminal.

7. Die verbleibenden Schritte in diesem Lernprogramm finden im Kontext dieses Entwicklungscontainers statt.

Visual Studio Code

Die Dev Containers-Erweiterung für Visual Studio Code erfordert, dass Docker auf Ihrem lokalen Computer installiert ist. Die Erweiterung hostet den Entwicklungscontainer lokal mithilfe des Docker-Hosts mit den richtigen Entwicklertools und Abhängigkeiten, die vorinstalliert sind, um dieses Schulungsmodul abzuschließen.

1. Öffnen Sie Visual Studio Code im Kontext eines leeren Verzeichnisses.

2. Stellen Sie sicher, dass Sie die Erweiterung Dev Containers in Visual Studio Code installiert haben.

3. Öffnen Sie ein neues Terminal im Editor.

   Tipp

   Sie können das Hauptmenü verwenden, um zur Menüoption " Terminal " zu navigieren und dann die Option "Neues Terminal " auszuwählen.

   

4. Klonen Sie das azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app GitHub-Repository in das aktuelle Verzeichnis.

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

5. Öffnen Sie die Befehlspalette, suchen Sie nach den Dev Containers-Befehlen, und wählen Sie dann Dev Containers: In Container erneut öffnen aus.

   

   Tipp

   Visual Studio Code fordert Sie möglicherweise automatisch auf, den vorhandenen Ordner in einem Entwicklungscontainer erneut zu öffnen. Dieser Schritt entspricht funktional der Verwendung der Befehlspalette, um den aktuellen Arbeitsbereich in einem Container erneut zu öffnen.

   Screenshot einer Toast-Benachrichtigung, die zum erneuten Öffnen des aktuellen Ordners im Kontext eines Entwicklungscontainers auffordert.

6. Überprüfen Sie die Versionen der Tools, die Sie in diesem Lernprogramm verwenden.

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

   Hinweis

   Dieses Lernprogramm erfordert die folgenden Versionen jedes Tools, die in Ihrer Umgebung vorinstalliert sind:

   Tool	Version
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   npm	≥ 9.5.0
   Azure-Befehlszeilenschnittstelle (Azure CLI)	≥ 2.46.0

7. Schließen Sie das Terminal.

8. Die verbleibenden Schritte in diesem Lernprogramm finden im Kontext dieses Entwicklungscontainers statt.

Testen der MERN-Anwendungs-API mit dem MongoDB-Container

Führen Sie zunächst die API der Beispielanwendung mit dem lokalen MongoDB-Container aus, um zu überprüfen, ob die Anwendung funktioniert.

1. Führen Sie einen MongoDB-Container mit Docker aus, und veröffentlichen Sie den typischen MongoDB-Port (27017).

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

2. Wählen Sie in der Seitenleiste die MongoDB-Erweiterung aus.

   

3. Fügen Sie eine neue Verbindung zur MongoDB-Erweiterung mithilfe der Verbindungszeichenfolge mongodb://localhosthinzu.

   

4. Sobald die Verbindung erfolgreich ist, öffnen Sie die Datei data/products.mongodb playground.

5. Wählen Sie das Symbol "Alle ausführen" aus, um das Skript auszuführen.

   

6. Der Testlauf sollte zu einer Liste von Dokumenten in der lokalen MongoDB-Collection führen. Hier ist ein gekürztes Beispiel für das Ergebnis.

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

   Hinweis

   Die Objektbezeichner (_id) werden zufällig generiert und unterscheiden sich von dieser abgeschnittenen Beispielausgabe.

7. Erstellen Sie im Server/ Verzeichnis eine neue env-Datei .

8. Fügen Sie in der Datei "server/.env " eine Umgebungsvariable für diesen Wert hinzu:

   Umgebungsvariable	Wert
   CONNECTION_STRING	Die Verbindungszeichenfolge mit dem Azure DocumentDB-Cluster. Verwenden Sie vorerst mongodb://localhost:27017?directConnection=true.

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

9. Ändern Sie den Kontext des Terminals in den Server/ Ordner.

   cd server
   

10. Installieren Sie die Abhängigkeiten vom Node Package Manager (npm).

    npm install
    

11. Starten Sie die Node.js & Express-Anwendung.

    npm start
    

12. Die API öffnet automatisch ein Browserfenster, um zu überprüfen, ob ein Array von Produktdokumenten zurückgegeben wird.

13. Schließen Sie die zusätzliche Browserregisterkarte/das zusätzliche Fenster.

14. Schließen Sie das Terminal.

Testen der MERN-Anwendung mit dem Azure DocumentDB-Cluster

Überprüfen wir nun, ob die Anwendung nahtlos mit Azure DocumentDB funktioniert. Füllen Sie für diese Aufgabe den bereits vorhandenen Cluster mit Seeddaten mithilfe der MongoDB-Shell auf, und aktualisieren Sie dann die Verbindungszeichenfolge der API.

1. Melden Sie sich beim Azure-Portal (https://portal.azure.com) an.

2. Navigieren Sie zur vorhandenen Azure DocumentDB-Clusterseite.

3. Wählen Sie auf der Azure DocumentDB-Clusterseite die Navigationsmenüoption "Verbindungszeichenfolgen " aus.

   

4. Notieren Sie den Wert aus dem Feld "Verbindungszeichenfolge ".

   

   Von Bedeutung

   Die Verbindungszeichenfolge im Portal enthält nicht die Benutzernamen- und Kennwortwerte. Sie müssen die Platzhalter <user> und <password> durch die Anmeldeinformationen ersetzen, die Sie bei der ursprünglichen Erstellung des Clusters verwendet haben.

5. Öffnen Sie ein neues Terminal in Ihrer integrierten Entwicklungsumgebung (IDE).

6. Starten Sie die MongoDB-Shell mit dem mongosh Befehl und der Verbindungszeichenfolge, die Sie zuvor aufgezeichnet haben. Stellen Sie sicher, dass Sie die Platzhalter <user> und <password> durch die Anmeldeinformationen ersetzen, die Sie beim ursprünglichen Erstellen des Clusters verwendet haben.

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

   Hinweis

   Möglicherweise müssen Sie bestimmte Werte für die Verbindungszeichenfolge codieren. In diesem Beispiel lautet msdocs-azure-documentdb-tutorialder Name des Clusters , der Benutzername lautet clusteradmin, und das Kennwort lautet P@ssw.rd. Im Kennwort muss das @ Zeichen mit %40codiert werden. Hier wird eine Beispielverbindungszeichenfolge mit der richtigen Codierung des Kennworts bereitgestellt.

   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. Führen Sie in der Shell die folgenden Befehle aus, um Ihre Datenbank zu erstellen, Ihre Sammlung zu erstellen und mit Startdaten zu seeden.

   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. Die Befehle sollten zu einer Liste von Dokumenten in der lokalen MongoDB-Auflistung führen. Hier sehen Sie ein gekürztes Beispiel für die Ausgabe.

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

   Hinweis

   Die Objektbezeichner (_id) werden zufällig generiert und unterscheiden sich von dieser abgeschnittenen Beispielausgabe.

9. Beenden Sie die MongoDB-Shell.

   exit
   

10. Erstellen Sie im Client/ Verzeichnis eine neue env-Datei .

11. Fügen Sie in der Datei "client/.env " eine Umgebungsvariable für diesen Wert hinzu:

    Umgebungsvariable	Wert
    CONNECTION_STRING	Die Verbindungszeichenfolge mit dem Azure DocumentDB-Cluster. Verwenden Sie dieselbe Verbindungszeichenfolge, die Sie mit der Mongo-Shell verwendet haben.

    CONNECTION_STRING=<your-connection-string>
    

12. Überprüfen Sie, ob die Anwendung den Datenbankdienst verwendet, indem Sie den Kontext des Terminals in den Server/ Ordner ändern, Abhängigkeiten vom Node Package Manager (npm) installieren und dann die Anwendung starten.

    cd server
    
    npm install
    
    npm start
    

13. Die API öffnet automatisch ein Browserfenster, um zu überprüfen, ob ein Array von Produktdokumenten zurückgegeben wird.

14. Schließen Sie die zusätzliche Browserregisterkarte bzw. das zusätzliche Browserfenster. Schließen Sie dann das Terminal.

Bereitstellen der MERN-Anwendung für Azure App Service

Beweisen Sie, dass die Anwendung end-to-End funktioniert, indem Sie den Dienst und den Client für Azure App Service bereitstellen. Verwenden Sie geheime Schlüssel in den Web-Apps, um Umgebungsvariablen mit Anmeldeinformationen und API-Endpunkten zu speichern.

1. Öffnen Sie in Ihrer integrierten Entwicklungsumgebung (IDE) ein neues Terminal.

2. Erstellen Sie eine Shellvariable für den Namen der bereits vorhandenen Ressourcengruppe mit dem Namen "resourceGroupName".

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

3. Erstellen Sie Shellvariablen für die beiden Web-App mit dem Namen "serverAppName " und "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. Falls noch nicht geschehen, melden Sie sich mit dem az login --use-device-code Befehl bei der Azure CLI an.

5. Ändern Sie das aktuelle Arbeitsverzeichnis auf den Server/ Pfad.

   cd server
   

6. Erstellen Sie eine neue Web-App für die Serverkomponente der MERN-Anwendung mit az webapp up.

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

7. Erstellen Sie eine neue Verbindungszeichenfolgen-Einstellung für die Server-Web-App namens CONNECTION_STRING mit az webapp config connection-string set. Verwenden Sie denselben Wert für die Verbindungszeichenfolge, die Sie mit der MongoDB-Shell und der env-Datei weiter oben in diesem Lernprogramm verwendet haben.

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

8. Rufen Sie den URI für die Server-Webanwendung ab az webapp show und speichern Sie ihn in der Shell-Variablen mit dem Namen d serverUri.

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

9. Verwenden Sie das Paket open-cli und den Befehl aus NuGet mit npx, um mithilfe des URI für die Server-Web-App ein Browserfenster zu öffnen. Überprüfen Sie, ob die Server-App Ihre JSON-Arraydaten aus dem Cluster zurückgibt.

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

   Tipp

   Manchmal können Bereitstellungen asynchron abgeschlossen werden. Wenn Sie nicht sehen, was Sie erwarten, warten Sie eine weitere Minute, und aktualisieren Sie das Browserfenster.

10. Ändern Sie das Arbeitsverzeichnis in den Client/ Pfad.

    cd ../client
    

11. Erstellen Sie eine neue Web-App für die Clientkomponente der MERN-Anwendung mit az webapp up.

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

12. Erstellen Sie eine neue App-Einstellung für die Clientweb-App namens REACT_APP_API_ENDPOINT mit az webapp config appsettings set. Verwenden Sie den Server-API-Endpunkt, der in der ServerUri-Shellvariable gespeichert ist.

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

13. Rufen Sie die URI für die Client-Web-App mit az webapp show ab und speichern Sie sie in der Shellvariablen mit dem Namen d clientUri.

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

14. Verwenden Sie das open-cli-Paket und den Befehl von NuGet mit npx, um ein Browserfenster mit dem URI für die Client-Web-App zu öffnen. Überprüfen Sie, ob die Client-App Daten aus der API der Server-App rendert.

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

    Tipp

    Manchmal können Bereitstellungen asynchron abgeschlossen werden. Wenn Sie nicht sehen, was Sie erwarten, warten Sie eine weitere Minute, und aktualisieren Sie das Browserfenster.

15. Schließen Sie das Terminal.

Bereinigen von Ressourcen

Wenn Sie in Ihrem eigenen Abonnement arbeiten, ist es ratsam, nach Abschluss eines Projekts die nicht mehr benötigten Ressourcen zu entfernen. Ressourcen, die weiterhin ausgeführt werden, können Sie Geld kosten. Sie können Ressourcen einzeln löschen oder die Ressourcengruppe löschen, um den gesamten Satz von Ressourcen zu löschen.

1. Um die gesamte Ressourcengruppe zu löschen, verwenden Sie az group delete.

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

2. Bestätigen Sie, dass die Ressourcengruppe mithilfe von az group list gelöscht wurde.

   az group list
   

Bereinigen der Entwicklungsumgebung

Sie können auch Ihre Entwicklungsumgebung bereinigen oder sie in ihren typischen Zustand zurückversetzen.

GitHub-Codespaces

Durch das Löschen der GitHub Codespaces-Umgebung wird sichergestellt, dass Sie die Anzahl der kostenlosen Berechtigungsstunden pro Kern maximieren können, die Sie für Ihr Konto erhalten.

1. Melden Sie sich beim GitHub Codespaces-Dashboard (https://github.com/codespaces) an.

2. Suchen Sie Ihren derzeit ausgeführten Entwicklungscontainer, der aus dem azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app GitHub-Repository stammt.

   

3. Öffnen Sie das Kontextmenü für den Codespace, und wählen Sie dann Löschen aus.

   

Visual Studio Code

Sie müssen ihre lokale Umgebung nicht unbedingt bereinigen, aber Sie können den ausgeführten Entwicklungscontainer beenden und zur Ausführung von Visual Studio Code im Kontext eines lokalen Arbeitsbereichs zurückkehren.

1. Öffnen Sie die Befehlspalette, suchen Sie nach den befehlen Dev Containers, und wählen Sie dann Dev Containers aus: Ordner lokalerneut öffnen.

   

Tipp

Visual Studio Code beendet den ausgeführten Entwicklungscontainer, aber der Container ist weiterhin in Docker in einem angehaltenen Zustand vorhanden. Sie können die Containerinstanz, das Containerimage und Volumes von Docker jederzeit löschen, um mehr Speicherplatz auf Ihrem lokalen Computer freizugeben.

Nächster Schritt

Migrieren Ihrer Daten