Tutorial: Conexión de una aplicación web de Node.js con Azure DocumentDB

En este tutorial, creará una aplicación web Node.js que se conecta a Azure DocumentDB. El conjunto de tecnologías MongoDB, Express, React.js, Node.js (MERN) es ampliamente utilizado para desarrollar muchas aplicaciones web modernas. Con Azure DocumentDB, puede compilar una nueva aplicación web o migrar una aplicación existente mediante controladores de MongoDB con los que ya está familiarizado. En este tutorial, usted hará lo siguiente:

• Configuración del entorno
• Prueba de la aplicación MERN con un contenedor local de MongoDB
• Prueba de la aplicación MERN con un clúster
• Implementación de la aplicación MERN en Azure App Service

Prerrequisitos

Para completar este tutorial, necesitará los siguientes recursos:

• Una suscripción de Azure

  • Si no tiene ninguna suscripción a Azure, cree una cuenta gratuita

• Un clúster de Azure DocumentDB existente

  • Si no tiene un clúster, cree un nuevo clúster.

• Una cuenta de GitHub con derechos de GitHub Codespaces

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 que tenga las herramientas de desarrollo y las dependencias correctas preinstaladas para completar este módulo de entrenamiento.

Importante

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

1. Inicie el proceso para crear un nuevo GitHub Codespace en la rama main del repositorio 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, a continuación, seleccione Crear nuevo codespace

   Captura de pantalla de la pantalla de confirmación antes de crear un nuevo codespace.

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

4. Abra un nuevo terminal en el espacio de código.

   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:

   Tool	Versión
   Docker	≥ 20.10.0
   Node.js.	≥ 18.0150
   npm	≥ 9.5.0
   CLI de Azure	≥ 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 preinstaladas para completar este módulo de entrenamiento.

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 .

   Captura de pantalla de la opción de menú para abrir un nuevo terminal.

4. Clona 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 pedir automáticamente que vuelva a abrir la carpeta existente dentro de un contenedor de desarrollo. Este paso 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:

   Tool	Versión
   Docker	≥ 20.10.0
   Node.js.	≥ 18.0150
   npm	≥ 9.5.0
   CLI de Azure	≥ 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 funciona.

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 MongoDB.

   

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

   

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 en el entorno de pruebas debería resultar en una lista de documentos de la colección local de MongoDB. Este es un ejemplo abreviado del resultado.

   [
     {
       "_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 difieren de esta salida de ejemplo truncada.

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

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

   Variable de entorno	Importancia
   CONNECTION_STRING	Cadena de conexión al clúster de Azure DocumentDB. Por ahora, use 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 desde el Administrador de paquetes de Node (npm).

    npm install
    

11. Inicie la aplicación Node.js & 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.

Prueba de la aplicación MERN con el clúster de Azure DocumentDB

Ahora, vamos a validar que la aplicación funciona sin problemas con Azure DocumentDB. 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 de clúster de Azure DocumentDB existente.

3. En la página del clúster de Azure DocumentDB, 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. Abra un nuevo terminal en el entorno de desarrollo integrado (IDE).

6. Inicie el shell de MongoDB con el mongosh comando 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:

   Podría necesitar codificar valores específicos para la cadena de conexión. En este ejemplo, el nombre del clúster es msdocs-azure-documentdb-tutorial, el nombre de usuario es clusteradminy la contraseña es P@ssw.rd. En la contraseña, el @ carácter debe 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-azure-documentdb-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 su base de datos, crear su colección e introducir datos iniciales.

   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 difieren 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	Importancia
    CONNECTION_STRING	Cadena de conexión al clúster de Azure DocumentDB. Utilice la misma cadena de conexión que utilizó con el shell de Mongo.

    CONNECTION_STRING=<your-connection-string>
    

12. Compruebe que la aplicación usa 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

Demuestre que la aplicación funciona de un extremo a otro mediante la implementación del servicio y el cliente en Azure App Service. 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 preexistente 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 mediante el az login --use-device-code comando .

5. Cambie el directorio de trabajo actual a la ruta 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 d serverUri.

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

9. Usa el paquete open-cli y el comando de NuGet con npx para abrir una ventana del navegador mediante el URI de la aplicación web de servidor. Compruebe que la aplicación de servidor devuelve los datos de la matriz JSON del clúster.

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

   Sugerencia

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

10. Cambie el directorio de trabajo al directorio 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 cliente con az webapp show y almacénelo en un nombre de variable de shell d 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 usando el URI de la aplicación web del cliente. Compruebe que la aplicación cliente representa 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 espera, espere otro minuto y actualice la ventana del explorador.

15. Cierre el terminal.

Limpieza de recursos

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

1. Para eliminar todo el grupo de recursos, use az group delete.

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

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

   az group list
   

Limpieza del entorno de desarrollo

También puede 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 el contenedor de desarrollo que se está ejecutando actualmente, procedente del repositorio de GitHub azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app.

   

3. Abra el menú contextual del espacio de códigos y, a continuación, seleccione Eliminar.

   Captura de pantalla del menú contextual de un solo codespace con la opción de eliminar resaltada.

Visual Studio Code

No es necesariamente 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.

   Captura de pantalla de la opción de la paleta de comandos para volver a abrir la carpeta actual en el entorno local.

Sugerencia

Visual Studio Code detiene el contenedor de desarrollo en ejecución, pero el contenedor todavía existe en Docker en un estado detenido. Siempre puede 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

Migración de los datos