Introducción a MongoDB API y JavaScript de Azure Cosmos DB

SE APLICA A: Azure Cosmos DB API para MongoDB

En este artículo se muestra cómo conectarse a MongoDB API de Azure Cosmos DB mediante el paquete npm de MongoDB nativo. Una vez conectado, puede realizar operaciones en bases de datos, colecciones y documentos.

Nota:

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

Documentación de referencia de MongoDB API | paquete de MongoDB (npm)

Requisitos previos

Creación de una nueva aplicación de JavaScript

  1. 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
    
  2. 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
    
  3. Para ejecutar la aplicación, use un terminal para ir al directorio de la aplicación y ejecutarla.

    node index.js
    

Conexión con el controlador nativo de MongoDB a MongoDB API de Azure Cosmos DB

Para conectarse con la unidad nativa de MongoDB a Azure Cosmos DB, cree una instancia de la clase MongoClient. Esta clase es el punto inicial para realizar todas las operaciones en bases de datos.

El constructor más común para MongoClient tiene dos parámetros:

Parámetro Valor de ejemplo Descripción
url La variable de entorno COSMOS_CONNECTION_STRIN Cadena de conexión de MongoDB API que se va a usar para todas las solicitudes
options {ssl: true, tls: true, } Opciones de MongoDB para la conexión.

Consulte la guía de solución de problemas en caso de problemas de conexión.

Obtención del nombre del recurso

  1. Cree una variable de shell para resourceGroupName.

    # Variable for resource group name
    resourceGroupName="msdocs-cosmos"
    
  2. Use el comando az cosmosdb list para recuperar el nombre de la primera cuenta de Azure Cosmos DB del grupo de recursos y almacenarlo en la variable de shell accountName.

    # Retrieve most recently created account name
    accountName=$(
        az cosmosdb list \
            --resource-group $resourceGroupName \
            --query "[0].name" \
            --output tsv
    )
    

Recuperación de la cadena de conexión

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

    az cosmosdb list-connection-strings \
        --resource-group $resourceGroupName \
        --name $accountName 
    
  2. Anote los valores de PRIMARY KEY. Necesitará estas credenciales más adelante.

Configuración de las variables de entorno

Para usar los valores de CADENA DE CONEXIÓN en el código, establezca este valor en el equipo 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>"

Creación de MongoClient con cadena de conexión

  1. Agregue dependencias para hacer referencia a los paquetes npm de MongoDB y DotEnv.

    // Read .env file and set environment variables
    require('dotenv').config();
    
    // Use official mongodb driver to connect to the server
    const { MongoClient } = require('mongodb');
    
  2. Defina una nueva instancia de la clase MongoClient, mediante el constructor y process.env. para usar la cadena de conexión.

    // New instance of MongoClient with connection string
    // for Cosmos DB
    const url = process.env.COSMOS_CONNECTION_STRING;
    const client = new MongoClient(url);
    
    // connect to the server
    await client.connect();
    
    // client options
    const options = client.options
    console.log(`Options:\n${Object.keys(options).map(key => `\t${key}: ${options[key]}\n`)}`);
    

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

Cierre de la conexión MongoClient

Cuando la aplicación haya terminado con la conexión, recuerde cerrarla. Esa llamada .close() debe producirse después de realizarse todas las llamadas de base de datos.

client.close()

Uso de clases de cliente de MongoDB con Cosmos DB para MongoDB API

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 de la jerarquía de Azure Cosmos DB en el que se incluyen cuentas, bases de datos, colecciones y documentos.

Diagrama jerárquico en el que se muestra una cuenta de Azure Cosmos DB en la parte superior. La cuenta tiene dos nodos de base de datos secundarios. Uno de los nodos de base de datos incluye dos nodos de colección secundarios. El otro de los nodos de base de datos incluye un único nodo de colección secundario. Ese único nodo de colección tiene tres nodos de documento secundarios.

Cada tipo de recurso se representa mediante una o varias clases de JavaScript asociadas. A continuación, se muestra una lista de las clases más comunes:

Clase Descripción
MongoClient Esta clase proporciona una representación lógica del cliente para la capa de MongoDB API en 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 podría no existir aún en el servicio. La colección se valida en el servidor al intentar utilizarla.

En las siguientes guías se muestra cómo usar cada una de estas clases para compilar la aplicación.

Guía:

Consulte también

Pasos siguientes

Ahora que se ha conectado a una cuenta de MongoDB API, use la siguiente guía para crear y administrar bases de datos.