Inicio rápido: Azure Cosmos DB for MongoDB para Python con el controlador de MongoDB

  • Artículo

SE APLICA A: MongoDB

Comience a utilizar el paquete PyMongo 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 Python.

En este inicio rápido, se comunicará 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. Además, usará los comandos de extensión de MongoDB, que están diseñados para ayudarle a crear y obtener recursos de base de datos específicos del modelo de capacidad de Azure Cosmos DB.

Requisitos previos

Comprobación de requisitos previos

  • En un terminal o ventana de comandos, ejecute python --version para comprobar que tiene una versión reciente de Python.
  • Ejecute az --version (CLI de Azure) o Get-Module -ListAvailable Az* (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 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.

    # requirements.txt
pymongo
python-dotenv

  3. Cree un entorno virtual e instale los paquetes.

    # 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

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

Vamos a examinar la jerarquía de recursos de la API para MongoDB y el modelo de objetos que se usa para crear estos 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.

Cada tipo de recurso se representa mediante una clase de Python. Estos son 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.

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. El código de ejemplo completo se encuentra en https://github.com/Azure-Samples/azure-cosmos-db-mongodb-python-getting-started/tree/main/001-quickstart/.

Para los pasos siguientes, la base de datos no usará el particionamiento y mostrará una aplicación sincrónica mediante el controlador PyMongo. Para las aplicaciones asincrónicas, use el controlador Motor.

Autenticar el cliente

  1. En el directorio del proyecto, cree un archivo run.py. En el editor, agregue las instrucciones necesarias para hacer referencia a los paquetes que usará, incluidos los paquetes PyMongo y python-dotenv.

    import os
import sys
from random import randint

import pymongo
from dotenv import load_dotenv

  2. Obtenga la información de conexión de la variable de entorno definida en un archivo .env.

    load_dotenv()
CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")

  3. Defina las constantes que usará en el código.

    DB_NAME = "adventureworks"
COLLECTION_NAME = "products"

Conexión a la API de Azure Cosmos DB para MongoDB

Use el objeto MongoClient para conectarse al recurso de Azure Cosmos DB for MongoDB. El método de conexión devuelve una referencia a la base de datos.

client = pymongo.MongoClient(CONNECTION_STRING)

Obtener una base de datos

Compruebe si la base de datos existe con el método list_database_names. Si la base de datos no existe, use el comando create database extension para crearla con un rendimiento aprovisionado especificado.

# Create database if it doesn't exist
db = client[DB_NAME]
if DB_NAME not in client.list_database_names():
    # Create a database with 400 RU throughput that can be shared across
    # the DB's collections
    db.command({"customAction": "CreateDatabase", "offerThroughput": 400})
    print("Created db '{}' with shared throughput.\n".format(DB_NAME))
else:
    print("Using database: '{}'.\n".format(DB_NAME))

Obtener una colección

Compruebe si la colección existe con el método list_collection_names. Si la colección no existe, use el comando create collection extension para crearla.

# Create collection if it doesn't exist
collection = db[COLLECTION_NAME]
if COLLECTION_NAME not in db.list_collection_names():
    # Creates a unsharded collection that uses the DBs shared throughput
    db.command(
        {"customAction": "CreateCollection", "collection": COLLECTION_NAME}
    )
    print("Created collection '{}'.\n".format(COLLECTION_NAME))
else:
    print("Using collection: '{}'.\n".format(COLLECTION_NAME))

Creación de un índice

Cree un índice mediante el comando update collection extension. También puede establecer el índice en el comando create collection extension. Establezca el índice en la propiedad name de este ejemplo para poder ordenar más adelante con el método de ordenación de clase de cursor en el nombre del producto.

indexes = [
    {"key": {"_id": 1}, "name": "_id_1"},
    {"key": {"name": 2}, "name": "_id_2"},
]
db.command(
    {
        "customAction": "UpdateCollection",
        "collection": COLLECTION_NAME,
        "indexes": indexes,
    }
)
print("Indexes are: {}\n".format(sorted(collection.index_information())))

Creación de un documento

Cree un documento que incluya las propiedades del producto de la base de datos adventureworks:

  • 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 document and upsert (create or replace) to collection"""
product = {
    "category": "gear-surf-surfboards",
    "name": "Yamba Surfboard-{}".format(randint(50, 5000)),
    "quantity": 1,
    "sale": False,
}
result = collection.update_one(
    {"name": product["name"]}, {"$set": product}, upsert=True
)
print("Upserted document with _id {}\n".format(result.upserted_id))

Cree un documento en la colección llamando a la operación de nivel de colección update_one. En este ejemplo, insertará (upsert) en lugar de crear un nuevo documento. La inserción (upsert) no es necesaria en este ejemplo porque el nombre del producto es aleatorio. Sin embargo, se recomienda la inserción (upsert) en caso de que ejecute el código más de una vez y el nombre del producto sea el mismo.

El resultado de la operación update_one contiene el valor de campo _id que puede usar en las operaciones posteriores. La propiedad _id se ha creado automáticamente.

Obtención de un documento

Use el método find_one para obtener un documento.

doc = collection.find_one({"_id": result.upserted_id})
print("Found a document with _id {}: {}\n".format(result.upserted_id, doc))

En Azure Cosmos DB, puede realizar una operación de lectura de puntos menos costosa mediante el identificador único (_id) y una clave de partició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 a Collection.find para obtener un resultado de tipo Cursor y, a continuación, use ordenar.

"""Query for documents in the collection"""
print("Products with category 'gear-surf-surfboards':\n")
allProductsQuery = {"category": "gear-surf-surfboards"}
for doc in collection.find(allProductsQuery).sort(
    "name", pymongo.ASCENDING
):
    print("Found a product with _id {}: {}\n".format(doc["_id"], doc))

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, el ejemplo emite una consulta que devuelve documentos que coinciden con una categoría de producto especificada. Con cada paso, el ejemplo genera información en la consola sobre los pasos que ha realizado.

Para ejecutar la aplicación, use un terminal para ir al directorio de la aplicación y ejecutarla.

python run.py

La salida de la aplicación debe ser similar a este ejemplo:


Created db 'adventureworks' with shared throughput.

Created collection 'products'.

Indexes are: ['_id_', 'name_1']

Upserted document with _id <ID>

Found a document with _id <ID>:
{'_id': <ID>,
'category': 'gear-surf-surfboards',
'name': 'Yamba Surfboard-50',
'quantity': 1,
'sale': False}

Products with category 'gear-surf-surfboards':

Found a product with _id <ID>:
{'_id': ObjectId('<ID>'),
'name': 'Yamba Surfboard-386',
'category': 'gear-surf-surfboards',
'quantity': 1,
'sale': False}

Limpieza de recursos

Cuando ya no necesite la cuenta de Azure Cosmos DB for NoSQL, puede eliminar el grupo de recursos correspondiente.

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

az group delete --name $resourceGroupName