Tutorial: Conectar una aplicación web Node.js con Azure Cosmos DB for MongoDB (núcleo virtual)

SE APLICA A: núcleo virtual de MongoDB

En este tutorial, se crea una aplicación web Node.js que se conecta a Azure Cosmos DB for MongoDB en arquitectura núcleo virtual. La pila MongoDB, Express, React.js, Node.js (MERN) es una colección popular de tecnologías que se usan para crear muchas aplicaciones web modernas. Con Azure Cosmos DB for MongoDB (núcleo virtual), puede crear una nueva aplicación web o migrar una aplicación existente utilizando controladores MongoDB con los que ya esté familiarizado. En este tutorial, hizo lo siguiente:

• Configurar el entorno
• Prueba de la aplicación MERN con un contenedor local de MongoDB
• Probar la aplicación MERN con un clúster núcleo virtual
• Implementación de la aplicación MERN en Azure App Service

Prerrequisitos

Para completar este tutorial, necesitará los siguientes recursos:

• Un clúster núcleo virtual existente.
• Una cuenta de GitHub.
  • GitHub incluye horas gratuitas de Codespaces para todos los usuarios.

Configuración del entorno de desarrollo

Un entorno de contenedor de desarrollo está disponible con todas las dependencias necesarias para completar todos los ejercicios de este proyecto. Puede ejecutar el contenedor de desarrollo en GitHub Codespaces o localmente mediante Visual Studio Code.

GitHub Codespaces

GitHub Codespaces ejecuta un contenedor de desarrollo administrado por GitHub con Visual Studio Code para la web como interfaz de usuario. Para el entorno de desarrollo más sencillo, use GitHub Codespaces para tener las herramientas de desarrollo y las dependencias correctas instaladas previamente para completar este módulo de formación.

Importante

Todas las cuentas de GitHub pueden usar Codespaces durante un máximo de 60 horas gratis cada mes con 2 instancias principales.

1. Inicie el proceso para crear una nueva instancia de GitHub Codespace en la rama main del repositorio de GitHub azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app.

   

2. En la página Crear codespace, revise las opciones de configuración de codespace y, después, seleccione Crear nuevo codespace

   

3. Espere a que se inicie Codespace. Este proceso de startup puede tardar unos minutos.

4. Abra un nuevo terminal en el codespace.

   Sugerencia

   Puede usar el menú principal para ir a la opción de menú Terminal y, a continuación, seleccionar la opción Nuevo terminal.

   

5. Compruebe las versiones de las herramientas que usa en este tutorial.

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

   Nota:

   Este tutorial requiere las siguientes versiones de cada herramienta que están preinstaladas en su entorno:

   Herramienta	Versión
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   NPM	≥ 9.5.0
   Azure CLI	≥ 2.46.0

6. Cierre el terminal.

7. Los pasos restantes de este tutorial tienen lugar en el contexto de este contenedor de desarrollo.

Visual Studio Code

La extensión de contenedores de desarrollo para Visual Studio Code requiere que Docker esté instalado en el equipo local. La extensión hospeda el contenedor de desarrollo localmente mediante el host de Docker con las herramientas de desarrollo y las dependencias correctas instaladas previamente para completar este módulo de formación.

1. Abra Visual Studio Code en el contexto de un directorio vacío.

2. Asegúrese de que tiene la extensión contenedores de desarrollo instalada en Visual Studio Code.

3. Abra un nuevo terminal en el editor.

   Sugerencia

   Puede usar el menú principal para ir a la opción de menú Terminal y, a continuación, seleccionar la opción Nuevo terminal.

   

4. Clone el repositorio de GitHub azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app en el directorio actual.

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

5. Abra la Paleta de comandos, busque los comandos de contenedores de desarrollo y, a continuación, seleccione Contenedores de desarrollo: volver a abrir en el contenedor.

   

   Sugerencia

   Visual Studio Code puede solicitar automáticamente que vuelva a abrir la carpeta existente dentro de un contenedor de desarrollo. Esto es funcionalmente equivalente a usar la paleta de comandos para volver a abrir el área de trabajo actual en un contenedor.

   

6. Compruebe las versiones de las herramientas que usa en este tutorial.

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

   Nota:

   Este tutorial requiere las siguientes versiones de cada herramienta que están preinstaladas en su entorno:

   Herramienta	Versión
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   NPM	≥ 9.5.0
   Azure CLI	≥ 2.46.0

7. Cierre el terminal.

8. Los pasos restantes de este tutorial tienen lugar en el contexto de este contenedor de desarrollo.

Prueba de la API de la aplicación MERN con el contenedor de MongoDB

Para empezar, ejecute la API de la aplicación de ejemplo con el contenedor local de MongoDB para validar que la aplicación funcione.

1. Ejecute un contenedor de MongoDB mediante Docker y publique el puerto típico de MongoDB (27017).

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

2. En la barra lateral, seleccione la extensión de MongoDB.

   

3. Agregue una nueva conexión a la extensión de MongoDB mediante la cadena de conexión mongodb://localhost.

   

4. Una vez que la conexión se haya realizado correctamente, abra el archivo de área de juegos data/products.mongodb.

5. Seleccione el icono Ejecutar todo para ejecutar el script.

   

6. La ejecución del área de juegos debe dar lugar a una lista de documentos de la colección local de MongoDB. Este es un ejemplo truncado de la salida.

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

   Nota:

   Los identificadores de objeto (_id) se generan aleatoriamente y serán diferentes de esta salida de ejemplo truncada.

7. En el directorio server/, crea un nuevo archivo .env.

8. En el archivo server/.env, agrega una variable de entorno para este valor:

   Variable de entorno	Valor
   CONNECTION_STRING	La cadena de conexión al clúster Azure Cosmos DB for MongoDB (núcleo virtual). De momento, utilice mongodb://localhost:27017?directConnection=true.

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

9. Cambie el contexto del terminal a la carpeta server/.

   cd server
   

10. Instale las dependencias del administrador de paquetes de Node (npm).

    npm install
    

11. Inicie la aplicación Node.js y Express.

    npm start
    

12. La API abre automáticamente una ventana del explorador para comprobar que devuelve una matriz de documentos de producto.

13. Cierre la pestaña o ventana del explorador adicional.

14. Cierre el terminal.

Pruebe la aplicación MERN con el clúster Azure Cosmos DB for MongoDB (núcleo virtual).

Ahora, vamos a validar que la aplicación funciona sin problemas con Azure Cosmos DB for MongoDB (núcleo virtual). Para esta tarea, rellene el clúster preexistente con datos de inicialización mediante el shell de MongoDB y, a continuación, actualice la cadena de conexión de la API.

1. Inicie sesión en Azure Portal (https://portal.azure.com).

2. Vaya a la página del clúster Azure Cosmos DB for MongoDB (núcleo virtual) existente.

3. En la página del clúster Azure Cosmos DB for MongoDB (núcleo virtual), seleccione la opción de menú de navegación Cadenas de conexión.

   

4. Registre el valor del campo Cadena de conexión.

   

   Importante

   La cadena de conexión del portal no incluye los valores de nombre de usuario y contraseña. Debe reemplazar los marcadores de posición <user> y <password> por las credenciales que usó al crear originalmente el clúster.

5. En el entorno de desarrollo integrado (IDE), abra un nuevo terminal.

6. Inicie el shell de MongoDB con el comando mongosh y la cadena de conexión que registró anteriormente. Asegúrese de reemplazar los marcadores de posición <user> y <password> por las credenciales que usó al crear originalmente el clúster.

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

   Nota:

   Es posible que tenga que codificar valores específicos para la cadena de conexión. En este ejemplo, el nombre del clúster es msdocs-cosmos-tutorial, el nombre de usuario es clusteradmin y la contraseña es P@ssw.rd. En la contraseña, el carácter @ tendrá que codificarse mediante %40. Aquí se proporciona una cadena de conexión de ejemplo con la codificación correcta de la contraseña.

   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. En el shell, ejecute los siguientes comandos para crear la base de datos, crear la colección y inicializar con datos de inicio.

   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. Los comandos deben dar lugar a una lista de documentos de la colección local de MongoDB. Este es un ejemplo truncado de la salida.

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

   Nota:

   Los identificadores de objeto (_id) se generan aleatoriamente y serán diferentes de esta salida de ejemplo truncada.

9. Salga del shell de MongoDB.

   exit
   

10. En el directorio client/, cree un nuevo archivo .env.

11. En el archivo client/.env, agregue una variable de entorno para este valor:

    Variable de entorno	Valor
    CONNECTION_STRING	La cadena de conexión al clúster Azure Cosmos DB for MongoDB (núcleo virtual). Use la misma cadena de conexión que usó con el shell de mongo.

    CONNECTION_STRING=<your-connection-string>
    

12. Compruebe que la aplicación use el servicio de base de datos cambiando el contexto del terminal a la carpeta server/, instalando dependencias del administrador de paquetes de Node (npm) e iniciando la aplicación.

    cd server
    
    npm install
    
    npm start
    

13. La API abre automáticamente una ventana del explorador para comprobar que devuelve una matriz de documentos de producto.

14. Cierre la pestaña o ventana del explorador adicional. A continuación, cierre el terminal.

Implementación de la aplicación MERN en Azure App Service

Implemente el servicio y el cliente en Azure App Service para demostrar que la aplicación funciona de un extremo a otro. Use secretos en las aplicaciones web para almacenar variables de entorno con credenciales y puntos de conexión de API.

1. En el entorno de desarrollo integrado (IDE), abra un nuevo terminal.

2. Cree una variable de shell para el nombre del grupo de recursos existente denominado resourceGroupName.

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

3. Cree variables de shell para las dos aplicaciones web denominadas serverAppName y 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 aún no lo ha hecho, inicie sesión en la CLI de Azure con el comando az login --use-device-code.

5. Cambie el directorio de trabajo actual a la ruta de acceso server/.

   cd server
   

6. Cree una nueva aplicación web para el componente de servidor de la aplicación MERN con az webapp up.

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

7. Cree una nueva configuración de cadena de conexión para la aplicación web de servidor denominada CONNECTION_STRING con az webapp config connection-string set. Use el mismo valor para la cadena de conexión que usó con el shell de MongoDB y el archivo .env anteriormente en este tutorial.

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

8. Obtenga el URI de la aplicación web de servidor con az webapp show y almacénelo en un nombre de variable de shell denominado serverUri.

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

9. Use el paquete open-cli y el comando de NuGet con npx para abrir una ventana del explorador mediante el URI de la aplicación web de servidor. Valide que la aplicación de servidor está devolviendo sus datos de matriz JSON desde el clúster MongoDB (núcleo virtual).

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

   Sugerencia

   A veces, las implementaciones pueden finalizar de forma asincrónica. Si no ve lo que esperaba, espere otro minuto y actualice la ventana del explorador.

10. Cambie el directorio de trabajo a la ruta de acceso client/.

    cd ../client
    

11. Cree una nueva aplicación web para el componente cliente de la aplicación MERN con az webapp up.

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

12. Cree una nueva configuración de aplicación para la aplicación web cliente denominada REACT_APP_API_ENDPOINT con az webapp config appsettings set. Use el punto de conexión de la API de servidor almacenado en la variable de shell serverUri.

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

13. Obtenga el URI de la aplicación web de cliente con az webapp show y almacénelo en un nombre de variable de shell denominado clientUri.

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

14. Use el paquete open-cli y el comando de NuGet con npx para abrir una ventana del explorador mediante el URI de la aplicación web de cliente. Compruebe que la aplicación cliente represente los datos de la API de la aplicación de servidor.

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

    Sugerencia

    A veces, las implementaciones pueden finalizar de forma asincrónica. Si no ve lo que esperaba, espere otro minuto y actualice la ventana del explorador.

15. Cierre el terminal.

Limpieza de recursos

Cuando trabaje con su propia suscripción, al final de un proyecto, es recomendable eliminar los recursos que ya no necesite. Los recursos que se dejan en ejecución pueden costarle mucho dinero. Puede eliminar los recursos de forma individual o eliminar el grupo de recursos para eliminar todo el conjunto de recursos.

1. Para eliminar un grupo de recursos entero, use az group delete.

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

2. Compruebe que el grupo de recursos se haya eliminado mediante az group list.

   az group list
   

Limpieza del entorno de desarrollo

También es posible que desee limpiar el entorno de desarrollo o devolverlo a su estado típico.

GitHub Codespaces

La eliminación del entorno de GitHub Codespaces garantiza que pueda maximizar la cantidad de derechos de horas gratuitas por núcleo que obtiene para su cuenta.

1. Inicie sesión en el panel de GitHub Codespaces (https://github.com/codespaces).

2. Busque los codespaces en ejecución actualmente procedentes del repositorio de GitHub azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app.

   

3. Abra el menú contextual del codespace y, a continuación, seleccione Eliminar.

   

Visual Studio Code

No es necesario limpiar el entorno local, pero puede detener el contenedor de desarrollo en ejecución y volver a ejecutar Visual Studio Code en el contexto de un área de trabajo local.

1. Abra la Paleta de comandos, busque los comandos de contenedores de desarrollo y, a continuación, seleccione Contenedores de desarrollo: volver a abrir la carpeta localmente.

   

Sugerencia

Visual Studio Code detendrá el contenedor de desarrollo en ejecución, pero el contenedor todavía existe en Docker en un estado detenido. Siempre tiene la opción de eliminar la instancia de contenedor, la imagen de contenedor y los volúmenes de Docker para liberar más espacio en la máquina local.

Paso siguiente

Ahora que ha creado su primera aplicación para el clúster MongoDB (núcleo virtual), aprenda cómo migrar sus datos a Azure Cosmos DB.

Migración de los datos