Esercitazione: Connettere un'app Web Node.js con Azure Cosmos DB per MongoDB (vCore)

SI APPLICA A: MongoDB vCore

In questa esercitazione viene creata un'applicazione Web Node.js che si connette ad Azure Cosmos DB per MongoDB nell'architettura vCore. Lo stack MongoDB, Express, React.js, Node.js (MERN) è una raccolta diffusa di tecnologie usate per creare molte applicazioni Web moderne. Con Azure Cosmos DB per MongoDB (vCore), è possibile creare una nuova applicazione Web o eseguire la migrazione di un'applicazione esistente usando driver MongoDB già noti. In questa esercitazione:

• Configurazione dell'ambiente
• Testare l'applicazione MERN con un contenitore MongoDB locale
• Testare l'applicazione MERN con un cluster vCore
• Distribuire l'applicazione MERN nel servizio app di Azure

Prerequisiti

Per completare l'esercitazione, sono necessarie le risorse seguenti:

• Un cluster vCore esistente.
• Un account GitHub.
  • GitHub include ore di Codespaces gratuite per tutti gli utenti.

Configurare l'ambiente di sviluppo

È disponibile un ambiente contenitore di sviluppo con tutte le dipendenze necessarie per completare ogni esercizio in questo progetto. È possibile eseguire il contenitore di sviluppo in GitHub Codespaces o in locale usando Visual Studio Code.

GitHub Codespaces

GitHub Codespaces esegue un contenitore di sviluppo gestito da GitHub con Visual Studio Code per il Web come interfaccia utente. Per l'ambiente di sviluppo più semplice, usare GitHub Codespaces per disporre degli strumenti di sviluppo e delle dipendenze preinstallati corretti per completare questo modulo di formazione.

Importante

Tutti gli account GitHub possono usare Codespaces per un massimo di 60 ore gratuite ogni mese con 2 istanze di core.

1. Avviare il processo per creare un nuovo codespace GitHub nel ramo main del repository GitHub azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app.

   

2. Nella pagina Crea codespace esaminare le impostazioni di configurazione del codespace e quindi selezionare Crea nuovo codespace

   

3. Attendere l'avvio del codespace. Questo processo di avvio può richiedere alcuni minuti.

4. Aprire un nuovo terminale nel codespace.

   Suggerimento

   È possibile usare il menu principale per passare all'opzione di menu Terminale e quindi selezionare l'opzione Nuovo terminale.

   

5. Controllare le versioni degli strumenti usati in questa esercitazione.

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

   Nota

   Questa esercitazione richiede le versioni seguenti di ogni strumento preinstallato nell'ambiente:

   Tool	Versione
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   NPM	≥ 9.5.0
   Interfaccia della riga di comando di Azure	≥ 2.46.0

6. Chiudere il terminale.

7. I passaggi rimanenti di questa esercitazione si svolgono nel contesto di questo contenitore di sviluppo.

Visual Studio Code

L'estensione Dev Containers per Visual Studio Code richiede l'installazione di Docker nel computer locale. L'estensione ospita il contenitore di sviluppo in locale usando l'host Docker con gli strumenti di sviluppo e le dipendenze preinstallati corretti per completare questo modulo di formazione.

1. Aprire Visual Studio Code nel contesto di una directory vuota.

2. Assicurarsi che l'estensione Dev Containers sia installata in Visual Studio Code.

3. Aprire un nuovo terminale nell'editor.

   Suggerimento

   È possibile usare il menu principale per passare all'opzione di menu Terminale e quindi selezionare l'opzione Nuovo terminale.

   

4. Clonare il repository GitHub azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app nella directory corrente.

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

5. Aprire il riquadro comandi, cercare i comandi Dev Containers e quindi selezionare Dev Containers: Reopen in Container (Dev Containers: Riapri nel contenitore).

   

   Suggerimento

   Visual Studio Code potrebbe richiedere automaticamente di riaprire la cartella esistente all'interno di un contenitore di sviluppo. Questa funzionalità equivale a usare il riquadro comandi per riaprire l'area di lavoro corrente in un contenitore.

   

6. Controllare le versioni degli strumenti usati in questa esercitazione.

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

   Nota

   Questa esercitazione richiede le versioni seguenti di ogni strumento preinstallato nell'ambiente:

   Tool	Versione
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   NPM	≥ 9.5.0
   Interfaccia della riga di comando di Azure	≥ 2.46.0

7. Chiudere il terminale.

8. I passaggi rimanenti di questa esercitazione si svolgono nel contesto di questo contenitore di sviluppo.

Testare l'API dell'applicazione MERN con il contenitore MongoDB

Per iniziare, eseguire l'API dell'applicazione di esempio con il contenitore MongoDB locale per verificare il funzionamento dell'applicazione.

1. Eseguire un contenitore MongoDB usando Docker e pubblicare la porta MongoDB tipica (27017).

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

2. Nella barra laterale selezionare l'estensione MongoDB.

   

3. Aggiungere una nuova connessione all'estensione MongoDB usando la stringa di connessione mongodb://localhost.

   

4. Al termine della connessione, aprire il file playground data/products.mongodb.

5. Selezionare l'icona Esegui tutto per eseguire lo script.

   

6. L'esecuzione del playground dovrebbe generare un elenco di documenti nella raccolta MongoDB locale. Ecco un esempio troncato dell'output.

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

   Nota

   Gli ID oggetto (_id) vengono generati in modo casuale e differiscono da questo output di esempio troncato.

7. Nella directory server/ creare un nuovo file con estensione env.

8. Nel file server/.env aggiungere una variabile di ambiente per questo valore:

   Variabile di ambiente	Valore
   CONNECTION_STRING	Il stringa di connessione al cluster Azure Cosmos DB per MongoDB (vCore). Per il momento, usare mongodb://localhost:27017?directConnection=true.

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

9. Modificare il contesto del terminale impostandolo sulla cartella server/.

   cd server
   

10. Installare le dipendenze da Node Package Manager (npm).

    npm install
    

11. Avviare l'applicazione Node.js & Express.

    npm start
    

12. L'API apre automaticamente una finestra del browser per verificare che restituisca una matrice di documenti di prodotto.

13. Chiudere la scheda/finestra del browser aggiuntiva.

14. Chiudere il terminale.

Testare l'applicazione MERN con il cluster Azure Cosmos DB per MongoDB (vCore)

A questo punto, verificare che l'applicazione funzioni perfettamente con Azure Cosmos DB per MongoDB (vCore). Per questa attività, popolare il cluster preesistente con i dati di inizializzazione usando la shell MongoDB e quindi aggiornare la stringa di connessione dell'API.

1. Accedere al portale di Azure (https://portal.azure.com).

2. Passare alla pagina del cluster Azure Cosmos DB per MongoDB (vCore) esistente.

3. Nella pagina del cluster Azure Cosmos DB per MongoDB (vCore) selezionare l'opzione di menu di spostamento Stringhe di connessione.

   

4. Registrare il valore del campo Stringa di connessione.

   

   Importante

   La stringa di connessione nel portale non include i valori nome utente e password. È necessario sostituire i segnaposto <user> e <password> con le credenziali usate durante la creazione del cluster.

5. Tornare all'interno dell'ambiente di sviluppo integrato (IDE), aprire un nuovo terminale.

6. Avviare la shell MongoDB usando il comando mongosh e la stringa di connessione registrata in precedenza. Assicurarsi di sostituire i segnaposto <user> e <password> con le credenziali usate durante la creazione del cluster.

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

   Nota

   Potrebbe essere necessario codificare valori specifici per la stringa di connessione. In questo esempio il nome del cluster è msdocs-cosmos-tutorial, il nome utente è clusteradmine la password è P@ssw.rd. Nella password il carattere @ dovrà essere codificato usando %40. Di seguito viene fornita una stringa di connessione di esempio con la codifica corretta della password.

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

7. Nella shell eseguire i comandi seguenti per creare il database, creare la raccolta e eseguire il seeding con i dati di avvio.

   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. I comandi devono generare un elenco di documenti nella raccolta MongoDB locale. Ecco un esempio troncato dell'output.

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

   Nota

   Gli ID oggetto (_id) vengono generati in modo casuale e differiscono da questo output di esempio troncato.

9. Uscire dalla shell MongoDB.

   exit
   

10. Nella directory client/ creare un nuovo file con estensione env .

11. Nel file client/.env aggiungere una variabile di ambiente per questo valore:

    Variabile di ambiente	Valore
    CONNECTION_STRING	Il stringa di connessione al cluster Azure Cosmos DB per MongoDB (vCore). Usare la stessa stringa di connessione usata con la shell mongo.

    CONNECTION_STRING=<your-connection-string>
    

12. Verificare che l'applicazione usi il servizio di database modificando il contesto del terminale nella cartella server/, installando le dipendenze da Gestione pacchetti node (npm) e quindi avviando l'applicazione.

    cd server
    
    npm install
    
    npm start
    

13. L'API apre automaticamente una finestra del browser per verificare che restituisca una matrice di documenti di prodotto.

14. Chiudere la scheda/finestra del browser aggiuntiva. Chiudere quindi il terminale.

Distribuire l'applicazione MERN nel servizio app di Azure

Distribuire il servizio e il client nel servizio app di Azure per dimostrare che l'applicazione funziona end-to-end. Usare i segreti nelle app Web per archiviare le variabili di ambiente con credenziali ed endpoint API.

1. All'interno dell'ambiente di sviluppo integrato aprire un nuovo terminale.

2. Creare una variabile shell per il nome del gruppo di risorse preesistente denominato resourceGroupName.

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

3. Creare variabili della shell per le due app Web denominate serverAppName e 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. Se non è già stato fatto, accedere all'interfaccia della riga di comando di Azure usando il comando az login --use-device-code.

5. Impostare il percorso server/ come directory di lavoro corrente.

   cd server
   

6. Creare una nuova app Web per il componente server dell'applicazione MERN con az webapp up.

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

7. Creare una nuova impostazione della stringa di connessione per l'app Web server denominata CONNECTION_STRING con az webapp config connection-string set. Usare lo stesso valore per la stringa di connessione usata con la shell MongoDB e il file con estensione env più indietro in questa esercitazione.

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

8. Ottenere l'URI per l'app Web server con az webapp show e archiviarlo in un nome di variabile shell d serverUri.

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

9. Usare il pacchetto e il comando open-cli da NuGet con npx per aprire una finestra del browser usando l'URI per l'app Web server. Verificare che l'app server restituisca i dati della matrice JSON dal cluster MongoDB (vCore).

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

   Suggerimento

   A volte le distribuzioni possono terminare in modo asincrono. Se non viene visualizzato quello previsto, attendere un altro minuto e aggiornare la finestra del browser.

10. Modificare la directory di lavoro impostando il percorso client/.

    cd ../client
    

11. Creare una nuova app Web per il componente client dell'applicazione MERN con az webapp up.

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

12. Creare una nuova impostazione dell'app per l'app Web client denominata REACT_APP_API_ENDPOINT con az webapp config appsettings set. Usare l'endpoint API server archiviato nella variabile della shell serverUri.

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

13. Ottenere l'URI per l'app Web client con az webapp show e archiviarlo in un nome di variabile shell d clientUri.

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

14. Usare il pacchetto e il comando open-cli da NuGet con npx per aprire una finestra del browser usando l'URI per l'app Web client. Verificare che l'app client stia visualizzando i dati dall'API dell'app server.

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

    Suggerimento

    A volte le distribuzioni possono terminare in modo asincrono. Se non viene visualizzato quello previsto, attendere un altro minuto e aggiornare la finestra del browser.

15. Chiudere il terminale.

Pulire le risorse

Quando si lavora nella propria sottoscrizione, alla fine di un progetto è opportuno rimuovere le risorse che non sono più necessarie. Le risorse che rimangono in esecuzione hanno un costo. È possibile eliminare risorse singole oppure gruppi di risorse per eliminare l'intero set di risorse.

1. Per eliminare l'intero gruppo di risorse, usare az group delete.

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

2. Verificare che il gruppo di risorse venga eliminato usando az group list.

   az group list
   

Pulire l'ambiente di sviluppo

È anche possibile pulire l'ambiente di sviluppo o restituirlo allo stato tipico.

GitHub Codespaces

L'eliminazione dell'ambiente GitHub Codespaces offre la possibilità di aumentare le ore gratuite per core a cui si ha diritto per l'account.

1. Accedere al dashboard di GitHub Codespaces (https://github.com/codespaces).

2. Individuare i codespace attualmente in esecuzione provenienti dal repository GitHub azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app.

   

3. Aprire il menu di scelta rapida per il codespace e selezionare Elimina.

   

Visual Studio Code

Non si è tenuti necessariamente a pulire l'ambiente locale, ma è possibile arrestare il contenitore di sviluppo in esecuzione e tornare a eseguire Visual Studio Code nel contesto di un'area di lavoro locale.

1. Aprire il riquadro comandi, cercare i comandi Dev Containers e quindi selezionare Dev Containers: Reopen Folder Locally.

   

Suggerimento

Il contenitore di sviluppo in esecuzione verrà arrestato da Visual Studio Code, ma continuerà a esistere in Docker in uno stato arrestato. È sempre possibile eliminare l'istanza del contenitore, l'immagine del contenitore e i volumi da Docker per liberare più spazio nel computer locale.

Passaggio successivo

Dopo aver creato la prima applicazione per il cluster MongoDB (vCore), vedere come eseguire la migrazione dei dati ad Azure Cosmos DB.

Eseguire la migrazione dei dati