Inicio rápido: Uso de Azure DocumentDB con el controlador mongoDB para Node.js

En este inicio rápido, creará una aplicación básica de Azure DocumentDB mediante Node.js. Azure DocumentDB es un almacén de datos NoSQL que permite a las aplicaciones almacenar documentos en la nube y acceder a ellos mediante controladores oficiales de MongoDB. En esta guía se muestra cómo crear documentos y realizar tareas básicas en el clúster de Azure DocumentDB mediante Node.js.

Referencia de API | Código fuente | Paquete (npm)

Prerrequisitos

Una suscripción de Azure
- Si no tiene ninguna suscripción a Azure, cree una cuenta gratuita

Node.js 22 o posteriores

Creación de un clúster de Azure DocumentDB

Para empezar, primero debe crear un clúster de Azure DocumentDB, que sirve como base para almacenar y administrar los datos NoSQL.

Inicie sesión en Azure Portal (https://portal.azure.com).
En el menú de Azure Portal o en la página principal, seleccione Crear un recurso.
En la página Nuevo , busque y seleccione Azure DocumentDB.
En la página Crear clúster de Azure DocumentDB y, en la sección Aspectos básicos , seleccione la opción Configurar en la sección Nivel de clúster.
En la página Escala , configure estas opciones y seleccione Guardar para conservar los cambios en el nivel de clúster.

Importancia

Nivel de clúster M30 tier, 2 vCore, 8-GiB RAM

Almacenamiento por partición 128 GiB

	Importancia
Nivel de clúster	`M30 tier, 2 vCore, 8-GiB RAM`
Almacenamiento por partición	`128 GiB`

De nuevo en la sección Aspectos básicos , configure las siguientes opciones:

	Importancia
Subscription	Seleccione su suscripción a Azure.
Grupo de recursos	Cree un grupo de recursos nuevo o seleccione uno existente
Nombre del clúster	Proporcione un nombre único global.
Ubicación	Seleccione una región de Azure compatible para su suscripción
Versión de MongoDB	Seleccionar `8.0`
Nombre de usuario administrador	Creación de un nombre de usuario para acceder al clúster como administrador de usuarios
Contraseña	Uso de una contraseña única asociada al nombre de usuario

Captura de pantalla que muestra los parámetros del clúster.

Sugerencia

Registre los valores que usa para el nombre de usuario y la contraseña. Estos valores se usan más adelante en esta guía. Para más información sobre los valores válidos, consulte Limitaciones del clúster.

Seleccione Siguiente: Redes.
En la sección Reglas de firewall de la pestaña Redes , configure estas opciones:

Importancia

Método de conectividad Public access

Permitir el acceso público desde servicios y recursos de Azure a este clúster Enabled
Agregue una regla de firewall para el dispositivo cliente actual para conceder acceso al clúster seleccionando + Agregar dirección IP del cliente actual.

Sugerencia

En muchos entornos corporativos, las direcciones IP de la máquina del desarrollador se ocultan debido a una VPN u otra configuración de red corporativa. En estos casos, puede permitir temporalmente el acceso a todas las direcciones IP agregando el 0.0.0.0 - 255.255.255.255 intervalo de direcciones IP como regla de firewall. Use esta regla de firewall solo temporalmente como parte de las pruebas de conexión y el desarrollo.
Selecciona Revisar + crear.
Revise la configuración que proporcione y, a continuación, seleccione Crear. La operación de creación del clúster tarda unos minutos. Espere a que se complete la implementación de recursos.
Por último, seleccione Ir al recurso para ir al clúster de Azure DocumentDB en el portal.

	Importancia
Método de conectividad	`Public access`
Permitir el acceso público desde servicios y recursos de Azure a este clúster	Enabled

Captura de pantalla que muestra las opciones de recursos goto.

Obtener credenciales del clúster

Obtenga las credenciales que usa para conectarse al clúster.

En la página del clúster, seleccione la opción Cadenas de conexión en el menú de recursos.
En la sección Cadenas de conexión , copie o registre el valor del campo Cadena de conexión .

Captura de pantalla que muestra la opción cadenas de conexión.

Importante

La cadena de conexión del portal no incluye el valor de contraseña. Debe reemplazar el marcador de posición <password> por los datos de acceso que introdujo al crear el clúster o ingresar la contraseña de manera interactiva.

Inicialización del proyecto

Cree un nuevo proyecto de Node.js en el directorio actual.

Inicie en un directorio vacío.
Abra un terminal en el directorio actual.
Inicialice un proyecto de Node.js.
```
npm init -y
```
Instale TypeScript e inicialice la configuración de TypeScript (opcional para la compatibilidad con TypeScript).
```
npm install -D typescript @types/node
npx tsc --init
```

Instalación de la biblioteca cliente

La biblioteca cliente está disponible a través de npm, como paquete de mongodb.

Instale el controlador de Node.js de MongoDB mediante npm.
```
npm install mongodb
```
Abra y revise el archivo package.json para validar que existe la entrada del paquete.

Importe los módulos necesarios en el código de la aplicación:

import { MongoClient, Db, Collection, Document } from 'mongodb';

const { MongoClient } = require('mongodb');

Modelo de objetos

Nombre	Description
`MongoClient`	Tipo que se usa para conectarse a MongoDB.
`Db`	Representa una base de datos en el clúster.
`Collection<Document>`	Representa una colección dentro de una base de datos del clúster.

El código de esta aplicación se conecta a una base de datos denominada adventureworks y a una colección denominada products. La products colección contiene detalles como el nombre, la categoría, la cantidad, un identificador único y una marca de venta para cada producto. Los ejemplos de código aquí realizan las operaciones más comunes al trabajar con una colección.

Autenticar el cliente

En primer lugar, conéctese al cliente mediante una cadena de conexión básica.

Cree la función principal y configure la cadena de conexión. Reemplace <your-cluster-name>, <your-username>, y <your-password> con su información real del clúster.

async function main(): Promise<void> {
    // Connection string for Azure DocumentDB cluster
    const connectionString = "mongodb+srv://<your-username>:<your-password>@<your-cluster-name>.global.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000";

    // Create a new client and connect to the server
    const client = new MongoClient(connectionString);

async function main() {
    // Connection string for Azure DocumentDB cluster
    const connectionString = "mongodb+srv://<your-username>:<your-password>@<your-cluster-name>.global.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000";

    // Create a new client and connect to the server
    const client = new MongoClient(connectionString);

Conéctese al cliente de MongoDB y compruebe la conexión.

    try {
        // Connect to the MongoDB cluster
        await client.connect();

        // Ping the server to verify connection
        await client.db("admin").command({ ping: 1 });
        console.log("Successfully connected and pinged Azure DocumentDB");

    try {
        // Connect to the MongoDB cluster
        await client.connect();

        // Ping the server to verify connection
        await client.db("admin").command({ ping: 1 });
        console.log("Successfully connected and pinged Azure DocumentDB");

Consigue una colección

Ahora, consigue base de datos y colección. Si la base de datos y la colección aún no existen, use el controlador para crearla automáticamente.

Obtenga una referencia a la base de datos.

        // Get database reference
        const database: Db = client.db("adventureworks");
        console.log(`Connected to database: ${database.databaseName}`);

        // Get database reference
        const database = client.db("adventureworks");
        console.log(`Connected to database: ${database.databaseName}`);

Obtenga una referencia a la colección dentro de la base de datos.

        // Get collection reference
        const collection: Collection<Document> = database.collection("products");
        console.log("Connected to collection: products");

        // Get collection reference
        const collection = database.collection("products");
        console.log("Connected to collection: products");

Creación de un documento

A continuación, cree un par de documentos nuevos dentro de la colección. Inserte o actualice los documentos para asegurarse de que reemplacen cualquier documento existente si ya existen con el mismo identificador único.

Cree documentos de producto de ejemplo.

        // Create sample products
        interface Product {
            _id: string;
            name: string;
            category: string;
            quantity: number;
            price: number;
            sale: boolean;
        }

        const products: Product[] = [
            {
                _id: "00000000-0000-0000-0000-000000004018",
                name: "Windry Mittens",
                category: "apparel-accessories-gloves-and-mittens",
                quantity: 121,
                price: 35.00,
                sale: false,
            },
            {
                _id: "00000000-0000-0000-0000-000000004318",
                name: "Niborio Tent",
                category: "gear-camp-tents",
                quantity: 140,
                price: 420.00,
                sale: true,
            }
        ];

        // Create sample products
        const products = [
            {
                _id: "00000000-0000-0000-0000-000000004018",
                name: "Windry Mittens",
                category: "apparel-accessories-gloves-and-mittens",
                quantity: 121,
                price: 35.00,
                sale: false,
            },
            {
                _id: "00000000-0000-0000-0000-000000004318",
                name: "Niborio Tent",
                category: "gear-camp-tents",
                quantity: 140,
                price: 420.00,
                sale: true,
            }
        ];

Inserte los documentos mediante operaciones upsert.

        // Insert documents with upsert
        for (const product of products) {
            const filter = { _id: product._id };
            const options = { upsert: true };

            await collection.replaceOne(filter, product, options);
            console.log(`Upserted product: ${product.name}`);
        }

        // Insert documents with upsert
        for (const product of products) {
            const filter = { _id: product._id };
            const options = { upsert: true };

            await collection.replaceOne(filter, product, options);
            console.log(`Upserted product: ${product.name}`);
        }

Recuperar un documento

A continuación, realice una operación de lectura puntual para recuperar un documento específico de la colección.

Defina el filtro para buscar un documento específico por identificador.

        // Retrieve a specific document by ID
        const filter = { _id: "00000000-0000-0000-0000-000000004018" };

        // Retrieve a specific document by ID
        const filter = { _id: "00000000-0000-0000-0000-000000004018" };

Ejecute la consulta y recupere el resultado.

        const retrievedProduct = await collection.findOne(filter);

        if (retrievedProduct) {
            console.log(`Retrieved product: ${retrievedProduct.name} - $${retrievedProduct.price}`);
        } else {
            console.log("Product not found");
        }

        const retrievedProduct = await collection.findOne(filter);

        if (retrievedProduct) {
            console.log(`Retrieved product: ${retrievedProduct.name} - $${retrievedProduct.price}`);
        } else {
            console.log("Product not found");
        }

Consulta de documentos

Por último, consulte varios documentos mediante el lenguaje de consulta mongoDB (MQL).

Defina una consulta para buscar documentos que coincidan con criterios específicos.

        // Query for products on sale
        const saleFilter = { sale: true };
        const saleProducts = await collection.find(saleFilter).toArray();

        // Query for products on sale
        const saleFilter = { sale: true };
        const saleProducts = await collection.find(saleFilter).toArray();

Recorra en iteración los resultados para mostrar los documentos coincidentes.

        console.log("Products on sale:");
        for (const product of saleProducts) {
            console.log(`- ${product.name}: $${product.price.toFixed(2)} (Category: ${product.category})`);
        }

    } catch (error) {
        console.error("An error occurred:", error);
    } finally {
        await client.close();
    }
}

main().catch(console.error);

        console.log("Products on sale:");
        for (const product of saleProducts) {
            console.log(`- ${product.name}: $${product.price.toFixed(2)} (Category: ${product.category})`);
        }

    } catch (error) {
        console.error("An error occurred:", error);
    } finally {
        await client.close();
    }
}

main().catch(console.error);

Exploración de los datos mediante Visual Studio Code

Use la extensión DocumentDB en Visual Studio Code para realizar operaciones básicas de base de datos, como consultar, insertar, actualizar y eliminar datos.

Abra Visual Studio Code.
Vaya a la vista Extensiones y busque el término DocumentDB. Busque la extensión DocumentDB para VS Code .
Seleccione el botón Instalar de la extensión. Espere a que termine la instalación. Vuelva a cargar Visual Studio Code si se le solicita.
Vaya a la extensión DocumentDB seleccionando el icono correspondiente en la barra de actividad.
En el panel Conexiones de DocumentDB , seleccione + Nueva conexión....
En el cuadro de diálogo, seleccione Detección de servicios y, a continuación, Azure DocumentDB - Azure Service Discovery.
Seleccione la suscripción de Azure y el clúster de Azure DocumentDB recién creado.

Sugerencia

En muchos entornos corporativos, las direcciones IP de la máquina del desarrollador se ocultan debido a una VPN u otra configuración de red corporativa. En estos casos, puede permitir temporalmente el acceso a todas las direcciones IP agregando el 0.0.0.0 - 255.255.255.255 intervalo de direcciones IP como regla de firewall. Use esta regla de firewall solo temporalmente como parte de las pruebas de conexión y el desarrollo. Para más información, consulte Configuración del firewall.
De nuevo en el panel Conexiones de DocumentDB , expanda el nodo del clúster y vaya a los nodos de documento y colección existentes.
Abra el menú contextual de la colección y luego seleccione >.
Escriba los siguientes comandos del lenguaje de consulta de MongoDB (MQL) y, a continuación, seleccione Ejecutar todo. Observa la salida de los comandos.
```
db.products.find({
  price: { $gt: 200 },
  sale: true
})
.sort({ price: -1 })
.limit(3)
```

Limpieza de recursos

Cuando haya terminado con el clúster de Azure DocumentDB, puede eliminar los recursos de Azure que creó para que no incurra en más cargos.

En la barra de búsqueda de Azure Portal, busque y seleccione Grupos de recursos.
En la lista, seleccione el grupo de recursos que usó para este inicio rápido.
En la página del grupo de recursos, seleccione Eliminar grupo de recursos.
En el cuadro de diálogo de confirmación de eliminación, escriba el nombre del grupo de recursos para confirmar que desea eliminarlo. Por último, seleccione Eliminar para eliminar de forma permanente el grupo de recursos.

¿Qué es Azure DocumentDB?

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-11-19