Esercitazione: Connettere un'app Web Node.js con Azure DocumentDB

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

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

Prerequisiti

Per completare questa esercitazione, sono necessarie le risorse seguenti:

• Una sottoscrizione di Azure

  • Se non hai un abbonamento Azure, crea un account gratuito

• Un cluster Di Azure DocumentDB esistente

  • Se non si ha un cluster, creare un nuovo cluster

• Un account GitHub con accesso a GitHub Codespaces

Configurare l'ambiente di sviluppo

Un ambiente contenitore di sviluppo è disponibile 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 in modo che siano preinstallati gli strumenti di sviluppo e le dipendenze corretti per completare questo modulo di training.

Importante

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

1. Avvia il processo per creare un nuovo Codespace di GitHub sul ramo main del repository GitHub azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app.

   

2. Nella pagina Crea spazio codici esaminare le impostazioni di configurazione dello spazio di codice e quindi selezionare Crea nuovo spazio di codice

   Screenshot della schermata di conferma prima di creare un nuovo codespace.

3. Attendere l'avvio dello spazio di codice. Questo processo di avvio può richiedere alcuni minuti.

4. Aprire un nuovo terminale nello spazio di codice.

   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
   

   Annotazioni

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

   Tool	Versione
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   npm	≥ 9.5.0
   Azure CLI	≥ 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 corretti preinstallati per completare questo modulo di training.

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

2. Assicurarsi di avere installato l'estensione Dev Containers 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 .

   Screenshot dell'opzione di menu per aprire un nuovo terminale.

4. Clonare il azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app repository GitHub 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 selezionare Dev Containers: riapri in contenitori.

   

   Suggerimento

   Visual Studio Code potrebbe richiedere automaticamente di riaprire la cartella esistente all'interno di un contenitore di sviluppo. Questo passaggio 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
   

   Annotazioni

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

   Tool	Versione
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   npm	≥ 9.5.0
   Azure CLI	≥ 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 mongodb://localhostdi connessione .

   

4. Una volta stabilita la connessione con successo, aprire il file data/products.mongodb playground.

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
     },
     ...
   ]
   

   Annotazioni

   Gli identificatori di 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	Value
   CONNECTION_STRING	Stringa di connessione al cluster Azure DocumentDB. Per il momento, usare mongodb://localhost:27017?directConnection=true.

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

9. Modificare il contesto del terminale alla 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 DocumentDB

A questo punto, è possibile verificare che l'applicazione funzioni perfettamente con Azure DocumentDB. 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 DocumentDB esistente.

3. Selezionare l'opzione Stringhe di connessione dal menu di navigazione nella pagina del cluster di Azure DocumentDB.

   

4. Registrare il valore dal campo Stringa di connessione .

   

   Importante

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

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

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

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

   Annotazioni

   Potrebbe essere necessario codificare valori specifici per la stringa di connessione. In questo esempio il nome del cluster è msdocs-azure-documentdb-tutorial, il nome utente è clusteradmine la password è P@ssw.rd. Nella password il @ carattere deve 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-azure-documentdb-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
     },
     ...
   ]
   

   Annotazioni

   Gli identificatori di 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 .env.

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

    Variabile di ambiente	Value
    CONNECTION_STRING	Stringa di connessione al cluster Azure DocumentDB. 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/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

Dimostrare che l'applicazione funziona end-to-end distribuendo il servizio e il client nel servizio app di Azure. 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 della 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 l'hai già fatto, accedi alla CLI di Azure usando il comando az login --use-device-code.

5. Modificare la directory di lavoro corrente nel percorso server/.

   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 open-cli e il comando da NuGet con npx per aprire una finestra del browser usando l'URI per l'applicazione web del server. Verificate che l'app server stia restituendo i dati dell'array JSON dal cluster.

   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 nel proprio abbonamento, alla fine di un progetto è opportuno rimuovere le risorse che non sono più necessarie. Le risorse lasciate in funzione possono costarti denaro. È 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 garantisce di massimizzare le ore gratuite per singolo core a cui si ha diritto per l'account.

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

2. Individuare il contenitore di sviluppo attualmente in esecuzione originato dal azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app repository GitHub.

   

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

   Screenshot del menu contestuale per un singolo codespace con l'opzione di eliminazione evidenziata.

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 la tavolozza dei comandi , cercare i comandi dei contenitori di sviluppo e quindi selezionare Contenitori di sviluppo: Riaprire la cartella localmente.

   

Suggerimento

Visual Studio Code arresta il contenitore di sviluppo in esecuzione, ma il contenitore esiste ancora 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.

Passo successivo

Eseguire la migrazione dei dati