Conexión de una aplicación Mongoose de Node.js a Azure Cosmos DB

2024-08-16

SE APLICA A: MongoDB

En este tutorial se muestra cómo usar el marco Mongoose al almacenar datos en Azure Cosmos DB. En este tutorial usaremos la API de Azure Cosmos DB para MongoDB. Si no le resulta familiar, Mongoose es un marco de modelado de objetos de MongoDB en Node.js que proporciona una solución sencilla y basada en esquemas para dar forma a los datos de la aplicación.

Azure Cosmos DB es un servicio de base de datos con varios modelos y de distribución global de Microsoft. Puede crear rápidamente bases de datos de documentos, clave-valor y grafos, y realizar consultas en ellas. Todas las bases de datos se beneficiarán de las funcionalidades de distribución global y escala horizontal en Azure Cosmos DB.

Prerrequisitos

Si no tiene una suscripción a Azure, cree una cuenta gratuita de Azure antes de empezar.

Puede probar gratis Azure Cosmos DB sin una suscripción de Azure, de forma gratuita y sin compromiso. Como alternativa, puede crear una cuenta de nivel gratis de Azure Cosmos DB, con las primeras 1000 RU/s y 25 GB de almacenamiento de forma gratuita. También puede usar el emulador de Azure Cosmos DB con un identificador URI https://localhost:8081. Para obtener la clave que se va a usar con el emulador, consulte Autenticación de solicitudes.

Node.js versión v0.10.29 o superior

Creación de una cuenta de Azure Cosmos DB

Vamos a crear una cuenta de Azure Cosmos DB. Si ya tiene una cuenta que desea usar, puede ir directamente a Configuración de la aplicación de Node.js. Si usa el emulador de Azure Cosmos DB, siga los pasos que se indican en Emulador de Azure Cosmos DB para configurar el emulador y vaya directamente a Configuración de la aplicación de Node.js.

En una nueva ventana del explorador, inicie sesión en Azure Portal.
En el menú de la izquierda, seleccione Crear un recurso.
En la página Nuevo, seleccione Bases de datos>Azure Cosmos DB.
En la página Seleccionar opción de API, seleccione Azure Cosmos DB for MongoDB>Crear.

La API determina el tipo de cuenta que se va a crear. Seleccione Azure Cosmos DB for MongoDB, ya que va a crear una colección que funciona con MongoDB en este inicio rápido. Para más información, consulte Introducción a Azure Cosmos DB for MongoDB.

En la página Crear una cuenta de Azure Cosmos DB, especifique la configuración de la nueva cuenta de Azure Cosmos DB.

Configuración	valor	Descripción
Subscription	Nombre de suscripción	Seleccione la suscripción de Azure que quiere usar para esta cuenta de Azure Cosmos DB.
Grupo de recursos	Definición de un nombre de grupo de recursos	Seleccione un grupo de recursos o seleccione Crear nuevo y escriba un nombre único para el grupo de recursos nuevo.
Nombre de cuenta	Escriba un nombre único.	Escriba un nombre único para identificar la cuenta de Azure Cosmos DB. El URI de la cuenta será mongo.cosmos.azure.com y se anexará al nombre único de la cuenta. El nombre de la cuenta solo puede utilizar letras minúsculas, números y guiones (-), y debe tener entre 3 y 44 caracteres de longitud.
Location	Región más cercana a los usuarios	Seleccione una ubicación geográfica para hospedar la cuenta de Azure Cosmos DB. Use la ubicación más cercana a los usuarios para que puedan acceder de la forma más rápida posible a los datos.
Capacity mode (Modo de capacidad)	Rendimiento aprovisionado o sin servidor	Seleccione Provisioned throughput (Rendimiento aprovisionado) para crear una cuenta en modo de rendimiento aprovisionado. Seleccione Serverless (Sin servidor) para crear una cuenta en modo sin servidor. Nota: solo se admiten la versiones 4.2, 4.0 y 3.6 de la API para MongoDB en las cuentas sin servidor. Si elige la versión 3.2, se forzará la cuenta al modo de rendimiento aprovisionado.
Aplicar el descuento del nivel Gratis de Azure Cosmos DB	Aplicar o No aplicar	Con el nivel Gratis de Azure Cosmos DB, recibirá los primeros 1000 RU/s y 25 GB de almacenamiento gratis en una cuenta. Más información acerca del nivel Gratis.
Versión	Elección de la versión de servidor necesaria	Azure Cosmos DB for MongoDB es compatible con la versión 4.2, 4.0, 3.6 y 3.2 del servidor. Puede actualizar o degradar una cuenta después de crearla.

Nota

Puede tener una cuenta de Azure Cosmos DB de nivel Gratis por cada suscripción de Azure y debe optar por tenerla al crear la cuenta. Si no ve la opción para aplicar el descuento por nivel Gratis, significará que en otra cuenta de la suscripción ya se ha habilitado el nivel Gratis.

Captura de pantalla de la página de nueva cuenta de Azure Cosmos DB.

En la pestaña Distribución global, configure los detalles siguientes. Puede dejar los valores predeterminados para este inicio rápido:

Configuración	valor	Descripción
Redundancia geográfica	Deshabilitar	Habilite o deshabilite la distribución global en su cuenta. Para ello, debe emparejar su región con una región de par. Puede agregar más regiones a su cuenta más adelante.
Escrituras en varias regiones	Deshabilitar	La funcionalidad de escrituras en varias regiones le permite aprovechar el rendimiento aprovisionado para sus bases de datos y contenedores de todo el mundo.

Nota

Las siguientes opciones no están disponibles si selecciona Serverless (Sin servidor) en Capacity mode (Modo de capacidad):

Aplicación de descuento por nivel Gratis
Redundancia geográfica
Escrituras en varias regiones

Opcionalmente, puede configurar detalles adicionales en las pestañas siguientes:
- Redes: configure el acceso desde una red virtual.
- Directiva de copia de seguridad: configure una directiva de copia de seguridad periódica o continua.
- Cifrado: use una clave administrada por el servicio o una clave administrada por el cliente.
- Etiquetas: son pares nombre-valor que permiten categorizar los recursos y ver una facturación consolidada mediante la aplicación de la misma etiqueta en varios recursos y grupos de recursos.
Seleccione Revisar + crear.
La cuenta tarda unos minutos en crearse. Espere a que el portal muestre la página ¡Enhorabuena! La cuenta de Azure Cosmos DB for MongoDB está lista.

Crear una base de datos

En esta aplicación se tratarán dos maneras de crear colecciones en Azure Cosmos DB:

Almacenar cada modelo de objetos en una colección independiente: Se recomienda crear una base de datos con rendimiento dedicado. El uso de este modelo de capacidad le proporcionará una mayor rentabilidad.
Almacenar todos los modelos de objetos en una sola colección de Azure Cosmos DB: si prefiere almacenar todos los modelos en una sola colección, solo tiene que crear una base de datos sin seleccionar la opción Aprovisionar rendimiento. El uso de este modelo de capacidad creará una colección con su propia capacidad de rendimiento para cada modelo de objetos.

Después de crear la base de datos, deberá usar el nombre en la variable de entorno COSMOSDB_DBNAME a continuación.

Configurar la aplicación de Node.js

Nota:

Si quiere usar el código de ejemplo en lugar de configurar la propia aplicación, clone el ejemplo que se usa en este tutorial y compile su propia aplicación Node.js de Mongoose en Azure Cosmos DB.

Para crear una aplicación Node.js en una carpeta de su elección, ejecute el comando siguiente en un símbolo del sistema de nodo.

npm init

Responda a las preguntas y su proyecto estará listo.
Agregue un nuevo archivo a la carpeta y asígnele el nombre index.js.
Instale los paquetes necesarios mediante una de las opciones npm install:
- Mongoose: npm install mongoose --save
Nota:

Para más información sobre qué versión de mongoose es compatible con la API para la versión del servidor de MongoDB, consulte Compatibilidad de Mongoose.
- Dotenv (si quiere cargar los secretos desde un archivo .env): npm install dotenv --save
  
  Nota:
  
  La marca --save agrega la dependencia al archivo package.json.

Importe las dependencias en el archivo index.js.

var mongoose = require('mongoose');
var env = require('dotenv').config();   //Use the .env file to load the variables

Agregue la cadena de conexión y el nombre de Azure Cosmos DB al archivo .env. Reemplace los marcadores de posición {cosmos-account-name} y {dbname} por el nombre de la cuenta y de la base de datos de Azure Cosmos DB, sin los símbolos de llave.

// You can get the following connection details from the Azure portal. You can find the details on the Connection string pane of your Azure Cosmos DB account.

COSMOSDB_USER = "<Azure Cosmos DB account's user name, usually the database account name>"
COSMOSDB_PASSWORD = "<Azure Cosmos DB account password, this is one of the keys specified in your account>"
COSMOSDB_DBNAME = "<Azure Cosmos DB database name>"
COSMOSDB_HOST= "<Azure Cosmos DB Host name>"
COSMOSDB_PORT=10255

Conéctese a Azure Cosmos DB mediante el marco Mongoose; para ello, debe agregar el siguiente código al final del archivo index.js.

mongoose.connect("mongodb://"+process.env.COSMOSDB_HOST+":"+process.env.COSMOSDB_PORT+"/"+process.env.COSMOSDB_DBNAME+"?ssl=true& replicaSet=globaldb", {
   auth: {
     username: process.env.COSMOSDB_USER,
     password: process.env.COSMOSDB_PASSWORD
   },
   useNewUrlParser: true,
   useUnifiedTopology: true,
   retryWrites: false
})
.then(() => console.log('Connection to CosmosDB successful'))
.catch((err) => console.error(err));

Nota:

En este caso, las variables de entorno se cargan mediante process.env.{variableName} con el paquete de npm dotenv.

Una vez que esté conectado a Azure Cosmos DB, puede empezar a configurar los modelos de objetos en Mongoose.

Procedimientos recomendados para usar Mongoose con Azure Cosmos DB

Por cada modelo que se crea, Mongoose crea por otro lado una nueva colección. Esta situación se aborda mejor con la opción Rendimiento en el nivel de base de datos, que se analizó anteriormente. Para usar una sola colección, debe utilizar los discriminadores de Mongoose. Los discriminadores son un mecanismo de herencia de esquemas. Le permiten tener varios modelos con esquemas superpuestos en la misma colección subyacente de MongoDB.

Puede almacenar los distintos modelos de datos en la misma colección y, a continuación, usar una cláusula de filtro a la hora de realizar la consulta para así descargar solo los datos necesarios. Vamos a ver en detalle cada uno de estos modelos.

Una colección por modelo de objetos

En esta sección le indicaremos cómo puede lograrlo gracias a la API de Azure Cosmos DB para MongoDB. Este método es la estrategia recomendada, ya que le permite controlar el costo y la capacidad. Como resultado, la cantidad de unidades de solicitud en la base de datos no depende del número de modelos de objetos. Este es el modelo de funcionamiento predeterminado de Mongoose, por lo tanto es posible que ya esté familiarizado con él.

Abra el archivo index.js de nuevo.

Cree la definición de esquema para "Family".

const Family = mongoose.model('Family', new mongoose.Schema({
    lastName: String,
    parents: [{
        familyName: String,
        firstName: String,
        gender: String
    }],
    children: [{
        familyName: String,
        firstName: String,
        gender: String,
        grade: Number
    }],
    pets:[{
        givenName: String
    }],
    address: {
        country: String,
        state: String,
        city: String
    }
}));

Cree un objeto para "Family".

const family = new Family({
    lastName: "Volum",
    parents: [
        { firstName: "Thomas" },
        { firstName: "Mary Kay" }
    ],
    children: [
        { firstName: "Ryan", gender: "male", grade: 8 },
        { firstName: "Patrick", gender: "male", grade: 7 }
    ],
    pets: [
        { givenName: "Buddy" }
    ],
    address: { country: "USA", state: "WA", city: "Seattle" }
});

Por último, guarde el objeto en Azure Cosmos DB. Esta opción crea una colección en segundo plano.
```
family.save((err, saveFamily) => {
    console.log(JSON.stringify(saveFamily));
});
```

A continuación, cree otro esquema y objeto. Esta vez vamos a crear uno para "Vacation Destinations" que pueden ser destinos de interés para las familias.

Igual que la última vez, cree el esquema.

const VacationDestinations = mongoose.model('VacationDestinations', new mongoose.Schema({
 name: String,
 country: String
}));

Cree un objeto de ejemplo (puede agregar varios objetos a este esquema) y guárdelo.

const vacaySpot = new VacationDestinations({
 name: "Honolulu",
 country: "USA"
});

vacaySpot.save((err, saveVacay) => {
 console.log(JSON.stringify(saveVacay));
});

A continuación, vaya a Azure Portal y verá dos colecciones que se crearon en Azure Cosmos DB.
Por último, lea los datos de Azure Cosmos DB. Puesto que vamos a usar el modelo de funcionamiento predeterminado de Mongoose, las lecturas son las mismas que cualquier otra en Mongoose.
```
Family.find({ 'children.gender' : "male"}, function(err, foundFamily){
    foundFamily.forEach(fam => console.log("Found Family: " + JSON.stringify(fam)));
});
```

Usar discriminadores de Mongoose para almacenar datos en una sola colección

En este método se usan los discriminadores de Mongoose para optimizar los costos de cada colección. Los discriminadores le permiten definir una "Clave" diferenciadora que a su vez le permite almacenar, diferenciar y filtrar los diferentes modelos de objetos.

En este caso, crearemos un modelo de objeto base, definiremos una clave diferenciadora y agregaremos "Family" y "VacationDestinations" a modo de extensión para el modelo base.

Realice la configuración base y defina la clave del discriminador.

const baseConfig = {
    discriminatorKey: "_type", //If you've got a lot of different data types, you could also consider setting up a secondary index here.
    collection: "alldata"   //Name of the Common Collection
};

A continuación, defina el modelo de objetos comunes.

const commonModel = mongoose.model('Common', new mongoose.Schema({}, baseConfig));

Defina el modelo "Family". Tenga en cuenta que estamos usando commonModel.discriminator en lugar de mongoose.model. Además, también agregaremos la configuración base al esquema de Mongoose. Por lo tanto, en este caso, la clave discriminatorKey es FamilyType.

const Family_common = commonModel.discriminator('FamilyType', new     mongoose.Schema({
    lastName: String,
    parents: [{
        familyName: String,
        firstName: String,
        gender: String
    }],
    children: [{
        familyName: String,
        firstName: String,
       gender: String,
        grade: Number
    }],
    pets:[{
        givenName: String
    }],
    address: {
        country: String,
        state: String,
        city: String
    }
}, baseConfig));

De forma similar, agregaremos otro esquema; esta vez para "VacationDestinations". En este caso, la clave DiscriminatorKey es VacationDestinationsType.

const Vacation_common = commonModel.discriminator('VacationDestinationsType', new mongoose.Schema({
    name: String,
    country: String
}, baseConfig));

Por último, crearemos objetos para el modelo y lo guardaremos.

Agreguemos objetos al modelo "Family".

const family_common = new Family_common({
 lastName: "Volum",
 parents: [
     { firstName: "Thomas" },
     { firstName: "Mary Kay" }
 ],
 children: [
     { firstName: "Ryan", gender: "male", grade: 8 },
     { firstName: "Patrick", gender: "male", grade: 7 }
 ],
 pets: [
     { givenName: "Buddy" }
 ],
 address: { country: "USA", state: "WA", city: "Seattle" }
});

family_common.save((err, saveFamily) => {
 console.log("Saved: " + JSON.stringify(saveFamily));
});

A continuación, vamos a agregar objetos al modelo "VacationDestinations" y lo guardaremos.

const vacay_common = new Vacation_common({
 name: "Honolulu",
 country: "USA"
});

vacay_common.save((err, saveVacay) => {
 console.log("Saved: " + JSON.stringify(saveVacay));
});

Si vuelve a Azure Portal, verá que solo tiene una colección denominada alldata con los datos de "Family" y "VacationDestinations".
Además, tenga en cuenta que cada objeto tiene otro atributo denominado "__type", que le ayudará a diferenciar entre los dos modelos de objetos diferentes.
Por último, lea los datos que se guardan en Azure Cosmos DB. Mongoose se encarga de filtrar los datos basados en el modelo. Por lo tanto, no tiene que hacer nada al leer los datos. Simplemente especifique el modelo (en este caso, Family_common) y Mongoose se encargará de los filtros en "DiscriminatorKey".
```
Family_common.find({ 'children.gender' : "male"}, function(err, foundFamily){
    foundFamily.forEach(fam => console.log("Found Family (using discriminator): " + JSON.stringify(fam)));
});
```

Como puede ver, es muy fácil trabajar con discriminadores de Mongoose. Así pues, si tiene una aplicación que usa el marco Mongoose, este tutorial es una manera de desarrollar la aplicación y ejecutarla mediante la API de Azure Cosmos DB para MongoDB sin tener que hacer demasiados cambios.

Limpieza de recursos

Cuando haya terminado tanto con la aplicación como con la cuenta de Azure Cosmos DB, puede eliminar los recursos de Azure que creó para no tener más gastos. Para eliminar los recursos:

En la barra de búsqueda de Azure Portal, busque y seleccione Grupos de recursos.
En la lista, seleccione el grupo de recursos que creó para este inicio rápido.
En la página Información general del grupo de recursos, seleccione Eliminar grupo de recursos.
En la ventana siguiente, escriba el nombre del grupo de recursos que desea eliminar y, después, seleccione Eliminar.

Pasos siguientes

Aprenda a usar Studio 3T con la API de Azure Cosmos DB para MongoDB.
Aprenda a usar Robo 3T con la API de Azure Cosmos DB para MongoDB.
Explore ejemplos de MongoDB con la API de Azure Cosmos DB para MongoDB.
¿Intenta planear la capacidad de una migración a Azure Cosmos DB? Para ello, puede usar información sobre el clúster de bases de datos existente.
- Si lo único que sabe es el número de núcleos virtuales y servidores del clúster de bases de datos existente, lea sobre el cálculo de unidades de solicitud mediante núcleos o CPU virtuales.
- Si conoce las tasas de solicitudes típicas de la carga de trabajo de la base de datos actual, obtenga información sobre el cálculo de unidades de solicitud mediante la herramienta de planeamiento de capacidad de Azure Cosmos DB.

Compartir a través de