Inicio rápido: controlador de Azure Cosmos DB for MongoDB para Node.js

SE APLICA A: MongoDB

• Node.js
• Python
• Java
• .NET
• Golang

Comience a utilizar el paquete npm de MongoDB para crear bases de datos, colecciones y documentos dentro de un recurso de Azure Cosmos DB. Siga estos pasos para instalar el paquete y probar el código de ejemplo para realizar tareas básicas.

Documentación de referencia de la API para MongoDB | Paquete MongoDB (NuGet) packages/Microsoft.Azure.Cosmos) | Azure Developer CLI

Requisitos previos

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
• Cuenta de GitHub

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
• CLI de desarrollo de Azure
• Docker Desktop

Instalación

Implemente el contenedor de desarrollo de este proyecto en su entorno. A continuación, use Azure Developer CLI (azd) para crear una cuenta de Azure Cosmos DB for MongoDB e implementar una aplicación de ejemplo en contenedor. La aplicación de ejemplo usa la biblioteca cliente para administrar, crear, leer y consultar datos de ejemplo.

Importante

Las cuentas de GitHub incluyen un derecho de almacenamiento y horas de núcleo sin costo alguno. Para obtener más información, consulte el almacenamiento y las horas de núcleo incluidas para las cuentas de GitHub.

1. Abra un terminal en el directorio raíz del proyecto.

2. Autentíquese en Azure Developer CLI mediante azd auth login. Siga los pasos especificados por la herramienta para autenticarse en la CLI mediante sus credenciales de Azure preferidas.

   azd auth login
   

3. Ejecute azd init para inicializar el proyecto.

   azd init --template cosmos-db-mongodb-nodejs-quickstart
   

   Nota:

   En este inicio rápido se usa el repositorio de GitHub azure-samples/cosmos-db-mongodb-nodejs-quickstart. La Azure Developer CLI clonará automáticamente este proyecto en la máquina si aún no lo está.

4. Durante la inicialización, configure un nombre de entorno único.

   Sugerencia

   El nombre del entorno también se usará como nombre del grupo de recursos de destino. Para este inicio rápido, considere la posibilidad de usar msdocs-cosmos-db.

5. Implemente la cuenta de Azure Cosmos DB mediante azd up. Las plantillas de Bicep también implementan una aplicación web de muestra.

   azd up
   

6. Durante el proceso de aprovisionamiento, seleccione la suscripción y la ubicación deseada. Espere a que se complete el proceso de aprovisionamiento. El proceso puede tardar aproximadamente cinco minutos.

7. Una vez realizado el aprovisionamiento de los recursos de Azure, se incluye una dirección URL a la aplicación web en ejecución en la salida.

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. Use la dirección URL de la consola para ir a la aplicación web en el explorador. Observe la salida de la aplicación en ejecución.

   

---

Instalar el paquete

Agregue el paquete npm de MongoDB al proyecto de JavaScript. Use el comando npm install package que especifica el nombre del paquete de npm. El paquete dotenv se usa para leer las variables de entorno de un archivo .env durante el desarrollo local.

npm install mongodb dotenv

Modelo de objetos

Antes de empezar a compilar la aplicación, consulte la jerarquía de recursos en Azure Cosmos DB. Azure Cosmos DB tiene un modelo de objetos específico que se usa para crear los recursos y acceder a ellos. Azure Cosmos DB crea recursos en una jerarquía que consta de cuentas, bases de datos, colecciones y documentos.

Diagrama jerárquico que muestra una cuenta de Azure Cosmos DB en la parte superior. La cuenta tiene dos particiones de base de datos secundarias. Una de las particiones de la base de datos incluye dos particiones de colección secundarias. La otra partición de la base de datos incluye un único nodo de colección secundaria. Esa partición de colección única tiene tres particiones de documento secundarias.

Use las siguientes clases de MongoDB para interactuar con estos recursos:

• MongoClient: Esta clase proporciona una representación lógica del cliente para la capa de la API para MongoDB en Azure Cosmos DB. El objeto de cliente se usa para configurar y ejecutar solicitudes en el servicio.
• Db: esta clase es una referencia a una base de datos que podría existir, o no, en el servicio. La base de datos se valida en el lado servidor al intentar acceder a ella o realizar alguna una operación en ella.
• Collection: esta clase es una referencia a una colección que también podría no existir todavía en el servicio. La colección se valida en el servidor al intentar utilizarla.

Ejemplos de código

• Autenticar el cliente
• Obtención de una instancia de base de datos
• Obtención de una instancia de colección
• Usar métodos encadenados
• Creación de un índice
• Creación de un documento
• Obtención de un documento
• Ejecución de consultas

El código de ejemplo descrito en este artículo crea una base de datos denominada adventureworks, con una colección denominada products. La colección products se ha diseñado para incluir detalles del producto, como el nombre, la categoría, la cantidad y un indicador de venta. Cada producto también contiene un identificador único.

Para este procedimiento, la base de datos no usa particionamiento.

Autenticar el cliente

1. En el directorio del proyecto, cree un archivo index.js. En el editor, agregue instrucciones requires para hacer referencia a los paquetes de npm de MongoDB y DotEnv.

   // Read .env file and set environment variables
   require('dotenv').config();
   const random = Math.floor(Math.random() * 100);
   
   // Use official mongodb driver to connect to the server
   const { MongoClient, ObjectId } = require('mongodb');
   

2. Defina una nueva instancia de la clase MongoClient, mediante el constructor y process.env. para leer la variable de entorno que creó anteriormente.

   // New instance of MongoClient with connection string
   // for Cosmos DB
   const url = process.env.COSMOS_CONNECTION_STRING;
   const client = new MongoClient(url);
   

Para obtener más información sobre las distintas formas de crear una instancia MongoClient, consulte inicio rápido del controlador NodeJS de MongoDB.

Configuración de operaciones asincrónicas

En el archivo index.js, agregue el código siguiente para admitir las operaciones asincrónicas:

async function main(){

// The remaining operations are added here
// in the main function

}

main()
  .then(console.log)
  .catch(console.error)
  .finally(() => client.close());

Los fragmentos de código siguientes se deben agregar a la función principal para controlar la sintaxis async/await.

Conectarse a la base de datos

Use el método MongoClient.connect para conectarse al recurso de Azure Cosmos DB for MongoDB. El método de conexión devuelve una referencia a la base de datos.

// Use connect method to connect to the server
await client.connect();

Obtención de una instancia de base de datos

Use el método MongoClient.db para obtener una referencia a una base de datos.

// Database reference with creation if it does not already exist
const db = client.db(`adventureworks`);
console.log(`New database:\t${db.databaseName}\n`);

Obtención de una instancia de colección

El uso del método MongoClient.Db.collection devuelve una referencia a una colección.

// Collection reference with creation if it does not already exist
const collection = db.collection('products');
console.log(`New collection:\t${collection.collectionName}\n`);

Instancias encadenadas

Puede encadenar al cliente, a la base de datos y a la colección entre sí. El encadenamiento es más conveniente si necesita acceder a varias bases de datos o colecciones.

const db = await client.db(`adventureworks`).collection('products').updateOne(query, update, options)

Creación de un índice

Use el método Collection.createIndex para crear un índice de las propiedades del documento que planea usar para organizar elementos junto con el método FindCursor.sort de MongoDB.

// create index to sort by name
const indexResult = await collection.createIndex({ name: 1 });
console.log(`indexResult: ${JSON.stringify(indexResult)}\n`);

Creación de un documento

Cree un documento que incluya las siguientes propiedades del producto de la base de datos adventureworks:

• Una propiedad _id para el identificador único de este producto.
• Una propiedad de categoría. Esta propiedad se puede usar como clave de partición lógica.
• Una propiedad de nombre.
• Una propiedad de cantidad en el inventario.
• Una propiedad de venta que indique si el producto está en venta.

// Create new doc and upsert (create or replace) to collection
const product = {
    category: "gear-surf-surfboards",
    name: `Yamba Surfboard-${random}`,
    quantity: 12,
    sale: false
};
const query = { name: product.name};
const update = { $set: product };
const options = {upsert: true, new: true};

// Insert via upsert (create or replace) doc to collection directly
const upsertResult1 = await collection.updateOne(query, update, options);
console.log(`upsertResult1: ${JSON.stringify(upsertResult1)}\n`);

// Update via upsert on chained instance
const query2 = { _id: ObjectId(upsertResult1.upsertedId) };
const update2 = { $set: { quantity: 20 } };
const upsertResult2 = await client.db(`adventureworks`).collection('products').updateOne(query2, update2, options);
console.log(`upsertResult2: ${JSON.stringify(upsertResult2)}\n`);

Para crear un documento en la recopilación, llame a Collection.UpdateOne. En este ejemplo, hemos elegido actualizar e insertar en lugar de crear un nuevo documento por si ejecuta este código de ejemplo más de una vez.

Obtención de un documento

En Azure Cosmos DB, puede realizar una operación de lectura de punto menos costosa mediante el identificador único (_id) y la clave de partición (category).

// Point read doc from collection:
// - without sharding, should use {_id}
// - with sharding,    should use {_id, partitionKey }, ex: {_id, category}
const foundProduct = await collection.findOne({
    _id: ObjectId(upsertResult1.upsertedId), 
    category: "gear-surf-surfboards"
});
console.log(`foundProduct: ${JSON.stringify(foundProduct)}\n`);

Consulta de documentos

Después de insertar un documento, puede ejecutar una consulta para obtener todos los documentos que coincidan con un filtro específico. En este ejemplo se muestran todos los documentos que coinciden con una categoría específica: gear-surf-surfboards. Una vez que haya definido la consulta, llame al método Collection.find para obtener un resultado de tipo FindCursor. Después, convierta el cursor en una matriz para poder usar métodos de matriz de JavaScript.

// select all from product category
const allProductsQuery = { 
    category: "gear-surf-surfboards" 
};

// get all documents, sorted by name, convert cursor into array
const products = await collection.find(allProductsQuery).sort({name:1}).toArray();
products.map((product, i ) => console.log(`${++i} ${JSON.stringify(product)}`));

Solución del problema:

• Si recibe un error similar a The index path corresponding to the specified order-by item is excluded., asegúrese de que no se ha olvidado de crear el índice.

Ejecución del código

Esta aplicación crea una base de datos y una colección de la API para MongoDB y crea un documento. Después, esta lee ese mismo documento. Por último, el ejemplo emite una consulta que solo debe devolver ese único documento. Con cada paso, el ejemplo genera información en la consola sobre los pasos realizados.

Para ejecutar la aplicación, use un terminal para ir al directorio de la aplicación y ejecutarla.

node index.js

La salida de la aplicación debe ser similar a este ejemplo:

New database:   adventureworks

New collection: products

upsertResult1: {"acknowledged":true,"modifiedCount":0,"upsertedId":"62b1f492ff69395b30a03169","upsertedCount":1,"matchedCount":0}

upsertResult2: {"acknowledged":true,"modifiedCount":1,"upsertedId":null,"upsertedCount":0,"matchedCount":1}

foundProduct: {"_id":"62b1f492ff69395b30a03169","name":"Yamba Surfboard-93","category":"gear-surf-surfboards","quantity":20,"sale":false}

indexResult: "name_1"

1 {"_id":"62b1f47dacbf04e86c8abf25","name":"Yamba Surfboard-11","category":"gear-surf-surfboards","quantity":20,"sale":false}
done

Limpieza de recursos

Cuando ya no necesite la cuenta de Azure Cosmos DB for MongoDB, puede eliminar el grupo de recursos correspondiente.

CLI de Azure

Use el comando az group delete para eliminar el grupo de recursos.

az group delete --name $resourceGroupName

PowerShell

Use el cmdlet Remove-AzResourceGroup para eliminar el grupo de recursos.

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

Portal

1. Vaya al grupo de recursos que creó anteriormente en Azure Portal.

   Sugerencia

   En este inicio rápido, se recomienda el nombre msdocs-cosmos-javascript-quickstart-rg.

2. Seleccione Eliminar grupo de recursos.

   

3. En el cuadro de diálogo ¿Seguro que desea eliminar?, escriba el nombre del grupo de recursos y seleccione Eliminar.

   

Pasos siguientes

Al completar este inicio rápido, ha obtenido información sobre la creación una cuenta de Azure Cosmos DB for MongoDB, así como la creación de una base de datos y una colección mediante el controlador de MongoDB. Ahora puede profundizar más en Azure Cosmos DB for MongoDB para importar más datos, hacer consultas complejas y administrar los recursos de MongoDB de Azure Cosmos DB.

Migración de MongoDB a Azure Cosmos DB for MongoDB sin conexión