Zelfstudie: Een Node.js-web-app verbinden met Azure DocumentDB

In deze zelfstudie bouwt u een Node.js-webtoepassing die verbinding maakt met Azure DocumentDB. De MongoDB-, Express-, React.js- Node.js -stack (MERN) is een populaire verzameling technologieën die worden gebruikt om veel moderne webtoepassingen te bouwen. Met Azure DocumentDB kunt u een nieuwe webtoepassing bouwen of een bestaande toepassing migreren met mongoDB-stuurprogramma's waarmee u al bekend bent. In deze handleiding leert u:

• Uw omgeving instellen
• De MERN-toepassing testen met een lokale MongoDB-container
• De MERN-toepassing testen met een cluster
• De MERN-toepassing implementeren in Azure App Service

Vereiste voorwaarden

Voor het voltooien van deze zelfstudie hebt u de volgende resources nodig:

• Een Azure-abonnement

  • Als u geen Azure-abonnement hebt, maakt u een gratis account

• Een bestaand Azure DocumentDB-cluster

  • Als u geen cluster hebt, maakt u een nieuw cluster

• Een GitHub-account met rechten voor GitHub Codespaces

De ontwikkelomgeving configureren

Een ontwikkelcontaineromgeving is beschikbaar met alle afhankelijkheden die nodig zijn om elke oefening in dit project te voltooien. U kunt de ontwikkelcontainer uitvoeren in GitHub Codespaces of lokaal met behulp van Visual Studio Code.

GitHub Codespaces

GitHub Codespaces voert een ontwikkelcontainer uit die wordt beheerd door GitHub met Visual Studio Code voor het web als de gebruikersinterface. Voor de eenvoudigste ontwikkelomgeving gebruikt u GitHub Codespaces zodat u de juiste ontwikkelhulpprogramma's en afhankelijkheden vooraf hebt geïnstalleerd om deze trainingsmodule te voltooien.

Belangrijk

Alle GitHub-accounts kunnen Codespaces elke maand maximaal 60 uur gratis gebruiken met twee kernexemplaren.

1. Start het proces om een nieuwe GitHub Codespace te maken op de main vertakking van de azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app GitHub-opslagplaats.

   

2. Op de Codespace maken-pagina, controleer de configuratie-instellingen van de codespace en selecteer vervolgens Nieuwe codespace maken.

   Schermopname van het bevestigingsscherm voordat u een nieuwe coderuimte aanmaakt.

3. Wacht tot de codespace is gestart. Dit opstartproces kan enkele minuten duren.

4. Open een nieuwe terminal in de codespace.

   Aanbeveling

   U kunt het hoofdmenu gebruiken om naar de menuoptie Terminal te navigeren en vervolgens de optie Nieuwe terminal te selecteren.

   

5. Controleer de versies van de hulpprogramma's die u in deze zelfstudie gebruikt.

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

   Opmerking

   Voor deze zelfstudie zijn de volgende versies van elk hulpprogramma vereist, die vooraf zijn geïnstalleerd in uw omgeving:

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

6. Sluit de terminal.

7. De resterende stappen in deze zelfstudie vinden plaats in de context van deze ontwikkelingscontainer.

Visual Studio Code

De Dev Containers-extensie voor Visual Studio Code vereist dat Docker op uw lokale computer is geïnstalleerd. De extensie host de ontwikkelcontainer lokaal met behulp van de Docker-host met de juiste ontwikkelhulpprogramma's en afhankelijkheden die vooraf zijn geïnstalleerd om deze trainingsmodule te voltooien.

1. Open Visual Studio Code in de context van een lege map.

2. Zorg ervoor dat de Dev Containers-extensie is geïnstalleerd in Visual Studio Code.

3. Open een nieuwe terminal in de editor.

   Aanbeveling

   U kunt het hoofdmenu gebruiken om naar de menuoptie Terminal te navigeren en vervolgens de optie Nieuwe terminal te selecteren.

   Schermopname van de menuoptie om een nieuwe terminal te openen.

4. Kloon de azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app GitHub-opslagplaats naar de huidige map.

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

5. Open het opdrachtenpalet, zoek naar de Dev Containers-opdrachten en selecteer vervolgens Dev Containers: Opnieuw openen in container.

   

   Aanbeveling

   Visual Studio Code vraagt u mogelijk automatisch om de bestaande map in een ontwikkelingscontainer opnieuw te openen. Deze stap is functioneel gelijk aan het gebruik van het opdrachtenpalet om de huidige werkruimte in een container opnieuw te openen.

   

6. Controleer de versies van de hulpprogramma's die u in deze zelfstudie gebruikt.

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

   Opmerking

   Voor deze zelfstudie zijn de volgende versies van elk hulpprogramma vereist, die vooraf zijn geïnstalleerd in uw omgeving:

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

7. Sluit de terminal.

8. De resterende stappen in deze zelfstudie vinden plaats in de context van deze ontwikkelingscontainer.

De API van de MERN-toepassing testen met de MongoDB-container

Begin met het uitvoeren van de API van de voorbeeldtoepassing met de lokale MongoDB-container om te controleren of de toepassing werkt.

1. Voer een MongoDB-container uit met behulp van Docker en publiceer de gebruikelijke MongoDB-poort (27017).

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

2. Selecteer in de zijbalk de MongoDB-extensie.

   

3. Voeg een nieuwe verbinding toe aan de MongoDB-extensie met behulp van de verbindingsreeks mongodb://localhost.

   

4. Zodra de verbinding tot stand is gebracht, opent u het bestand data/products.mongodb playground.

5. Selecteer het pictogram Alles uitvoeren om het script uit te voeren.

   

6. De playground-uitvoering moet resulteren in een lijst met documenten in de lokale MongoDB-collectie. Hier is een ingekort voorbeeld van de uitvoer.

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

   Opmerking

   De object-id's (_id) worden willekeurig gegenereerd en verschillen van deze afgekapte voorbeelduitvoer.

7. Maak in de server/ map een nieuw .env-bestand .

8. Voeg in het bestand server/.env een omgevingsvariabele toe voor deze waarde:

   Omgevingsvariabele	Waarde
   CONNECTION_STRING	De verbindingsreeks met het Azure DocumentDB-cluster. Gebruik voorlopig mongodb://localhost:27017?directConnection=true.

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

9. Wijzig de context van de terminal in de server/ map.

   cd server
   

10. Installeer de afhankelijkheden van Node Package Manager (npm).

    npm install
    

11. Start de Node.js & Express-applicatie.

    npm start
    

12. De API opent automatisch een browservenster om te controleren of er een matrix met productdocumenten wordt geretourneerd.

13. Sluit het extra browsertabblad/-venster.

14. Sluit de terminal.

De MERN-toepassing testen met het Azure DocumentDB-cluster

Laten we nu controleren of de toepassing naadloos werkt met Azure DocumentDB. Vul voor deze taak het vooraf bestaande cluster in met seed-gegevens met behulp van de MongoDB-shell en werk vervolgens de verbindingsreeks van de API bij.

1. Meld u aan bij Azure Portal (https://portal.azure.com).

2. Navigeer naar de bestaande Azure DocumentDB-clusterpagina.

3. Kies in het navigatiemenu op de pagina van de Azure DocumentDB-cluster de optie verbindingsreeksen.

   

4. Noteer de waarde uit het veld Verbindingsreeks .

   

   Belangrijk

   De verbindingsreeks in de portal bevat geen gebruikersnaam- en wachtwoordwaarden. U moet de <user> en <password> plaatsaanduidingen vervangen door de referenties die u hebt gebruikt toen u het cluster oorspronkelijk aanmaakte.

5. Open een nieuwe terminal in uw IDE (Integrated Development Environment).

6. Start de MongoDB-shell met behulp van de mongosh opdracht en de verbindingsreeks die u eerder hebt vastgelegd. Zorg ervoor dat u de <user> en <password> plaatsaanduidingen vervangt door de referenties die u hebt gebruikt toen u het cluster oorspronkelijk maakte.

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

   Opmerking

   Mogelijk moet u specifieke waarden voor de verbindingsreeks coderen. In dit voorbeeld is msdocs-azure-documentdb-tutorialde naam van het cluster, de gebruikersnaam en clusteradminhet wachtwoord P@ssw.rd. In het wachtwoord moet het @ teken worden gecodeerd met behulp van %40. Hier ziet u een voorbeeld van een verbindingsreeks met de juiste codering van het wachtwoord.

   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. Voer in de shell de volgende opdrachten uit om uw database te maken, uw verzameling te maken en te seeden met startergegevens.

   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. De opdrachten moeten resulteren in een lijst met documenten in de lokale MongoDB-verzameling. Hier is een verkort voorbeeld van de uitvoer.

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

   Opmerking

   De object-id's (_id) worden willekeurig gegenereerd en verschillen van deze afgekapte voorbeelduitvoer.

9. Sluit de MongoDB-shell af.

   exit
   

10. Maak in de client/ map een nieuw .env-bestand .

11. Voeg in het bestand client/.env een omgevingsvariabele toe voor deze waarde:

    Omgevingsvariabele	Waarde
    CONNECTION_STRING	De verbindingsreeks met het Azure DocumentDB-cluster. Gebruik dezelfde verbindingsreeks die u met de mongo-shell hebt gebruikt.

    CONNECTION_STRING=<your-connection-string>
    

12. Controleer of de toepassing de databaseservice gebruikt door de context van de terminal te wijzigen in de server/ map, afhankelijkheden van Node Package Manager (npm) te installeren en vervolgens de toepassing te starten.

    cd server
    
    npm install
    
    npm start
    

13. De API opent automatisch een browservenster om te controleren of er een matrix met productdocumenten wordt geretourneerd.

14. Sluit het extra browsertabblad/-venster. Sluit vervolgens de terminal.

De MERN-toepassing implementeren in Azure App Service

Bewijzen dat de toepassing end-to-end werkt door de service en client te implementeren in Azure App Service. Gebruik geheimen in de web-apps om omgevingsvariabelen op te slaan met referenties en API-eindpunten.

1. Open in uw IDE (Integrated Development Environment) een nieuwe terminal.

2. Maak een shellvariabele voor de naam van de bestaande resourcegroep met de naam resourceGroupName.

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

3. Maak shellvariabelen voor de twee web-app serverAppName en 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. Als u dat nog niet hebt gedaan, meldt u zich aan bij de Azure CLI met behulp van de az login --use-device-code opdracht.

5. Verander de huidige werkmap naar het server/ pad.

   cd server
   

6. Maak een nieuwe web-app voor het serveronderdeel van de MERN-toepassing met az webapp up.

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

7. Maak een nieuwe verbindingsreeksinstelling voor de serverweb-app die de naam CONNECTION_STRING met az webapp config connection-string set heeft. Gebruik dezelfde waarde voor de verbindingsreeks die u eerder in deze zelfstudie hebt gebruikt met de MongoDB-shell en het .env-bestand .

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

8. Verkrijg de URI van de serverwebapplicatie met az webapp show en sla deze op in een shellvariabele met de naam d serverUri.

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

9. Gebruik het open-cli pakket en de opdracht van NuGet in combinatie met npx om een browservenster te openen met behulp van de URI voor de server-webapplicatie. Controleer of de server-app uw JSON-matrixgegevens uit het cluster retourneert.

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

   Aanbeveling

   Soms kunnen implementaties asynchroon worden voltooid. Als u niet ziet wat u verwacht, wacht u nog een minuut en vernieuwt u het browservenster.

10. Wijzig de werkmap naar het pad client/.

    cd ../client
    

11. Maak een nieuwe web-app voor het clientonderdeel van de MERN-toepassing met az webapp up.

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

12. Maak een nieuwe app-instelling voor de client-webapp genaamd REACT_APP_API_ENDPOINT met az webapp config appsettings set. Gebruik het server-API-eindpunt dat is opgeslagen in de serverUri-shellvariabele .

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

13. Gebruik az webapp show om de URI voor de clientwebapp op te halen en sla deze op in een shell-variabele met de naam clientUri.

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

14. Gebruik het open-cli pakket en de NuGet-opdracht om npx een browservenster te openen met behulp van de URI voor de clientweb-app. Controleer of de client-app gegevens uit de API van de server-app rendert.

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

    Aanbeveling

    Soms kunnen implementaties asynchroon worden voltooid. Als u niet ziet wat u verwacht, wacht u nog een minuut en vernieuwt u het browservenster.

15. Sluit de terminal.

De hulpbronnen opschonen

Wanneer je in je eigen abonnement werkt, is het aan het einde van een project een goed idee om de resources die je niet meer nodig hebt te verwijderen. Ressources die actief blijven draaien, kunnen geld kosten. U kunt resources afzonderlijk verwijderen, maar u kunt ook de resourcegroep verwijderen als u de volledige resourceset wilt verwijderen.

1. Als u de hele resourcegroep wilt verwijderen, gebruikt u az group delete.

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

2. Controleer of de resourcegroep is verwijderd met behulp van az group list.

   az group list
   

Ontwikkelomgeving opschonen

Mogelijk wilt u uw ontwikkelomgeving ook opschonen of teruggaan naar de typische status.

GitHub Codespaces

Als u de GitHub Codespaces-omgeving verwijdert, zorgt u ervoor dat u de hoeveelheid gratis rechten per kernuren kunt maximaliseren die u voor uw account krijgt.

1. Meld u aan bij het GitHub Codespaces-dashboard (https://github.com/codespaces).

2. Zoek uw huidige ontwikkelingscontainer afkomstig uit de azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app GitHub-repository.

   

3. Open het contextmenu voor de coderuimte en selecteer Verwijderen.

   Schermopname van het contextmenu voor één coderuimte met de optie Verwijderen gemarkeerd.

Visual Studio Code

U hoeft niet per se uw lokale omgeving op te schonen, maar u kunt de actieve ontwikkelcontainer stoppen en terugkeren naar het uitvoeren van Visual Studio Code in de context van een lokale werkruimte.

1. Open de Command Palette, zoek naar de Dev Containers-opdrachten en selecteer vervolgens Dev Containers: Folder lokaal opnieuw openen.

   

Aanbeveling

Visual Studio Code stopt de actieve ontwikkelingscontainer, maar de container bestaat nog steeds in Docker met de status Gestopt. U kunt de containerinstance, containerbeelden en volumes altijd verwijderen uit Docker om meer ruimte vrij te maken op uw lokale computer.

Volgende stap

Uw gegevens migreren