Introducción a Azure Cosmos DB para MongoDB mediante JavaScript

Se aplica a: ✅ MongoDB

SE APLICA A: MongoDB

Importante

¿Desea migrar una aplicación de MongoDB existente o usar las características del lenguaje de consulta de MongoDB (MQL)? Considere la posibilidad de usar Azure DocumentDB.

¿Busca una solución de base de datos para escenarios a gran escala con un contrato de nivel de servicio (SLA) de disponibilidad de 99,999%, escalabilidad automática instantánea y conmutación automática por error en varias regiones? Considere la posibilidad de usar Azure Cosmos DB para NoSQL.

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

Note

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

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

Prerequisites

Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
Node.js LTS
Interfaz de la línea de comandos (CLI) de Azure o Azure PowerShell
Azure Cosmos DB para el recurso de MongoDB

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 npm init comando para iniciar las indicaciones para crear el package.json archivo. Aceptar los valores predeterminados de las indicaciones.
```
npm init
```
Agregue el paquete npm de MongoDB al proyecto de JavaScript. Use el npm install package comando que especifica el nombre del paquete npm. El paquete dotenv se usa para leer las variables de entorno de un archivo .env durante el desarrollo local.
```
npm install mongodb dotenv
```
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 para Azure Cosmos DB para MongoDB

Para conectarse con el controlador nativo de MongoDB en 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	Ejemplo de valor	Description
`url`	La variable de entorno `COSMOS_CONNECTION_STRING`	API para la cadena de conexión de MongoDB que se debe usar en 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

Cree una variable de shell para resourceGroupName.

# Variable for resource group name
resourceGroupName="msdocs-cosmos"

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
)

Cree una variable de shell para RESOURCE_GROUP_NAME.

# Variable for resource group name
$RESOURCE_GROUP_NAME = "msdocs-cosmos"

Use el cmdlet Get-AzCosmosDBAccountKey para recuperar el nombre de la primera cuenta de Azure Cosmos DB del grupo de recursos y almacenarlo en la variable de shell accountName.
```
# Get the name of the first Azure Cosmos DB account in your resource group
$ACCOUNT_NAME = (Get-AzCosmosDBAccount -ResourceGroupName $RESOURCE_GROUP_NAME)[0].Name
```

Recuperación de la cadena de conexión

Busque la cadena de conexión de la API de MongoDB en la lista de cadenas de conexión de la cuenta con el comando az cosmosdb keys list.
```
az cosmosdb keys list --type connection-strings \
    --resource-group $resourceGroupName \
    --name $accountName 
```
Anote los valores de PRIMARY KEY. Necesitará estas credenciales más adelante.

Busque CONNECTION STRING en la lista de claves y cadenas de conexión para la cuenta con el cmdlet Get-AzCosmosDBAccountKey.

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
    Type = "ConnectionStrings"
}    
Get-AzCosmosDBAccountKey @parameters |
    Select-Object -Property "Primary MongoDB Connection String"

Registre el valor de CONNECTION STRING. Necesitará estas credenciales más adelante.

Tip

Para esta guía, se recomienda usar el nombre del grupo de recursos msdocs-cosmos.

Inicie sesión en Azure Portal.
Vaya a la página de la cuenta existente de Azure Cosmos DB para MongoDB.
En la página de la cuenta de Azure Cosmos DB for MongoDB, seleccione la opción de menú de navegación Cadena de conexión.
Registre el valor del campo CADENA DE CONEXIÓN PRINCIPAL. Se usará este valor en un paso posterior.

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>"

export COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

Un archivo .env es una manera estándar de almacenar variables de entorno en un proyecto. Cree un archivo .env en el directorio raíz del proyecto. Agregue las líneas siguientes al archivo .env:

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

Creación de MongoClient con cadena de conexión

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

// Use official mongodb driver to connect to the server
import { MongoClient } from 'mongodb';

Defina una nueva instancia de la clase MongoClient mediante el constructor, y utilice la cadena de conexión con process.env..

// 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 MongoClient instancia, 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. La .close() llamada debe ser después de que se realicen todas las llamadas de base de datos.

client.close()

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

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 for MongoDB que incluye cuentas, bases de datos, colecciones y documentos.

Cada tipo de recurso se representa mediante una o varias clases de JavaScript asociadas. Esta es una lista de las clases más comunes:

Class	Description
`MongoClient`	Esta clase proporciona una representación lógica del cliente para la capa de 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 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 crear tu aplicación.

Guía:

Consulte también

Pasos siguientes

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

Crear una base de datos en Azure Cosmos DB para MongoDB mediante JavaScript

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-04-27