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

  • Artículo

SE APLICA A: MongoDB

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.

Nota:

Los fragmentos de código de ejemplo están disponibles en GitHub como un proyecto de JavaScript.

Documentación de referencia de la API para MongoDB | Paquete de MongoDB (NuGet)

Requisitos previos

Comprobación de requisitos previos

  • En una ventana de terminal o de comandos, ejecute node --version para comprobar que Node.js es una de las versiones de LTS.
  • Ejecute az --version (CLI de Azure) o Get-Module -ListAvailable AzureRM (Azure PowerShell) para comprobar que tiene instaladas las herramientas adecuadas de la línea de comandos de Azure.

Instalación

En esta sección, se muestran los pasos a seguir para crear una cuenta de Azure Cosmos DB y configurar un proyecto que use el paquete npm de MongoDB.

Creación de una cuenta de Azure Cosmos DB

En este inicio rápido se creará una única cuenta de Azure Cosmos DB mediante la API para MongoDB.

  1. Cree variables de shell para accountName, resourceGroupName y location.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-quickstart-rg"
location="westus"

# Variable for account name with a randomnly generated suffix
let suffix=$RANDOM*$RANDOM
accountName="msdocs-$suffix"

  2. Si aún no lo ha hecho, inicie sesión en la CLI de Azure con el comando az login.

  3. Use el comando az group create para crear un nuevo grupo de recursos en la suscripción.

    az group create \
    --name $resourceGroupName \
    --location $location

  4. Use el comando az cosmosdb create para crear una nueva cuenta de Azure Cosmos DB for MongoDB con la configuración predeterminada.

    az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location
    --kind MongoDB

Obtención de la cadena de conexión de MongoDB

  1. Busque la cadena de conexión de API para MongoDB en la lista de cadenas de conexión para la cuenta con el comando az cosmosdb keys list.

    az cosmosdb keys list --type connection-strings \
    --resource-group $resourceGroupName \
    --name $accountName

  2. Anote los valores de PRIMARY KEY. Necesitará estas credenciales más adelante.

Creación de una nueva aplicación de JavaScript

Cree una nueva aplicación de JavaScript en una carpeta vacía con su terminal preferido. Use el comando npm init para comenzar a recibir las solicitudes de creación del archivo package.json. Acepte los valores predeterminados de todas las solicitudes.

npm init

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

Configuración de las variables de entorno

Para usar los valores de la CADENA DE CONEXIÓN en el código, establezca este valor en el entorno local que ejecuta la aplicación. Para establecer la variable de entorno, use el terminal preferido para ejecutar los siguientes comandos:

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

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.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, collections, and docs.

Se usaran 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 ya o no en el servicio. La base de datos se valida en el servidor al intentar acceder a ella o hacer alguna una operación.
  • Collection: Esta clase es una referencia a una colección que podría no existir aún en el servicio. La colección se valida en el servidor al intentar utilizarla.

Ejemplos de código

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.

Durante este procedimiento, la base de datos no usará técnicas de 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, se emite una consulta que solo debe devolver ese único documento. Con cada paso que se complete, el ejemplo generará metadatos en la consola sobre los pasos que haya realizado.

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.

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

az group delete --name $resourceGroupName

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