Introducción a Azure Cosmos DB for MongoDB y Python

SE APLICA A: MongoDB

En este artículo se muestra cómo conectarse a Azure Cosmos DB for MongoDB mediante el paquete de controladores PyMongo. 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 Python.

En este artículo se muestra cómo comunicarse con la API de Azure Cosmos DB para MongoDB mediante uno de los controladores de cliente de MongoDB de código abierto para Python, PyMongo.

Requisitos previos

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
• Python 3.8 y versiones posteriores
• 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 Python

1. Cree una nueva carpeta vacía con el terminal que prefiera y cambie el directorio a la carpeta.

   Nota:

   Si solo quiere el código terminado, descargue o bifurque y clone el repositorio de fragmentos de código de ejemplo que contiene el ejemplo completo. También puede git clone el repositorio en Azure Cloud Shell para recorrer los pasos que se muestran en este inicio rápido.

2. Cree un archivo requirements.txt que enumere los paquetes PyMongo y python-dotenv. El paquete dotenv se usa para leer las variables de entorno de un archivo .env durante el desarrollo local.

   # requirements.txt
   pymongo
   python-dotenv
   

3. Cree un entorno virtual e instale los paquetes.

   Windows

   # py -3 uses the global python interpreter. You can also use python3 -m venv .venv.
   py -3 -m venv .venv
   source .venv/Scripts/activate   
   pip install -r requirements.txt
   

   Linux/macOS

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

Conexión con el controlador PyMongo a Azure Cosmos DB for MongoDB

Para conectarse con el controlador PyMongo a Azure Cosmos DB, cree una instancia del objeto MongoClient. Esta clase es el punto inicial para realizar todas las operaciones en bases de datos.

El constructor más común para MongoClient solo requiere el parámetro host, que en este artículo se establece en la variable de entorno COSMOS_CONNECTION_STRING. Hay otros parámetros opcionales y parámetros de palabra clave que puede usar en el constructor. Muchos de los parámetros opcionales también se pueden especificar con el parámetro host. Si se pasa la misma opción con host y como parámetro, el parámetro tiene prioridad.

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

Obtención del nombre del recurso

En los comandos siguientes, se muestra msdocs-cosmos como nombre del grupo de recursos. Cambie el nombre según corresponda para su situación.

CLI de Azure

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
   )
   

PowerShell

1. Cree una variable de shell para RESOURCE_GROUP_NAME.

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

2. 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
   

Portal

Omita este paso y use la información del portal en el paso siguiente.

Recuperación de la cadena de conexión

CLI de Azure

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.

PowerShell

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

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

Portal

1. Inicie sesión en Azure Portal.

2. Vaya a la página de la cuenta de Azure Cosmos DB for MongoDB existente.

3. 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.

4. Registre el valor del campo CADENA DE CONEXIÓN PRINCIPAL. 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:

Windows

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

Linux/macOS

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

.env

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

1. Agregue dependencias para hacer referencia a los paquetes PyMongo y python-dotenv.

   import os
   import sys
   
   import pymongo
   from dotenv import load_dotenv
   

2. Defina una nueva instancia de la clase MongoClient mediante el constructor y la cadena de conexión leída de una variable de entorno.

   load_dotenv()
   CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")
   client = pymongo.MongoClient(CONNECTION_STRING)
   
   for prop, value in vars(client.options).items():
       print("Property: {}: Value: {} ".format(prop, value))
   

Para más información sobre las distintas formas de crear una instancia de MongoClient, consulte Creación de una conexión con MongoClient.

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 Azure Cosmos DB para la API para 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 jerárquico que muestra una cuenta de la base de datos 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 Python asociadas. A continuación, se muestra una lista de las clases más comunes:

• MongoClient: el primer paso al trabajar con PyMongo es crear una instancia de MongoClient para conectarse a la API de Azure Cosmos DB para MongoDB. El objeto de cliente se usa para configurar y ejecutar solicitudes en el servicio.

• Base de datos: la API de Azure Cosmos DB para MongoDB puede admitir una o varias bases de datos independientes.

• Colección: una base de datos puede contener una o más colecciones. Una colección es un grupo de documentos almacenados en MongoDB, que se puede considerar como el equivalente aproximado de una tabla en una base de datos relacional.

• Documento: un documento es un conjunto de pares clave-valor. Los documentos tienen un esquema dinámico. El esquema dinámico significa que los documentos de la misma colección no necesitan tener el mismo conjunto de campos ni la misma estructura. Y los campos comunes de los documentos de una colección pueden contener diferentes tipos de datos.

Para más información sobre la jerarquía de entidades, consulte el artículo Modelo de recursos de Azure Cosmos DB.

Consulte también

• Paquete PyPi
• Referencia de las API

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.

Creación de una base de datos en Azure Cosmos DB for MongoDB mediante Python