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

SE APLICA A: MongoDB

• Node.js
• Python
• Java
• .NET
• Golang

Comience a utilizar MongoDB para crear bases de datos, colecciones y documentos dentro de un recurso de Azure Cosmos DB. Siga estos pasos para implementar una solución mínima en su entorno mediante la Azure Developer CLI.

Documentación de referencia de la API para MongoDB | Paquete pymongo | Azure Developer CLI

Requisitos previos

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
• Cuenta de GitHub

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
• CLI de desarrollo de Azure
• Docker Desktop

Instalación

Implemente el contenedor de desarrollo de este proyecto en su entorno. A continuación, use Azure Developer CLI (azd) para crear una cuenta de Azure Cosmos DB for MongoDB e implementar una aplicación de ejemplo en contenedor. La aplicación de ejemplo usa la biblioteca cliente para administrar, crear, leer y consultar datos de ejemplo.

Importante

Las cuentas de GitHub incluyen un derecho de almacenamiento y horas de núcleo sin costo alguno. Para obtener más información, consulte el almacenamiento y las horas de núcleo incluidas para las cuentas de GitHub.

1. Abra un terminal en el directorio raíz del proyecto.

2. Autentíquese en Azure Developer CLI mediante azd auth login. Siga los pasos especificados por la herramienta para autenticarse en la CLI mediante sus credenciales de Azure preferidas.

   azd auth login
   

3. Ejecute azd init para inicializar el proyecto.

   azd init --template cosmos-db-mongodb-python-quickstart
   

   Nota:

   En este inicio rápido se usa la plantilla azure-samples/cosmos-db-mongodb-python-quickstart del repositorio de GitHub. La Azure Developer CLI clona automáticamente este proyecto en la máquina si aún no lo está.

4. Durante la inicialización, configure un nombre de entorno único.

   Sugerencia

   El nombre del entorno también se usará como nombre del grupo de recursos de destino. Para este inicio rápido, considere la posibilidad de usar msdocs-cosmos-db.

5. Implemente la cuenta de Azure Cosmos DB mediante azd up. Las plantillas de Bicep también implementan una aplicación web de muestra.

   azd up
   

6. Durante el proceso de aprovisionamiento, seleccione la suscripción y la ubicación deseada. Espere a que se complete el proceso de aprovisionamiento. El proceso puede tardar aproximadamente cinco minutos.

7. Una vez realizado el aprovisionamiento de los recursos de Azure, se incluye una dirección URL a la aplicación web en ejecución en la salida.

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. Use la dirección URL de la consola para ir a la aplicación web en el explorador. Observe la salida de la aplicación en ejecución.

   

---

Instalación de la biblioteca cliente

1. Cree un archivo requirements.txt en el directorio de la aplicación que muestre los paquetes PyMongo y python-dotenv.

   # requirements.txt
   pymongo
   python-dotenv
   

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

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.

Diagrama jerárquico que muestra una cuenta de Azure Cosmos DB en la parte superior. La cuenta tiene dos particiones de base de datos secundarias. Una de las particiones de la base de datos incluye dos particiones de colección secundarias. La otra partición de base de datos incluye una sola partición de colección secundaria. Esa partición de colección única tiene tres particiones de documento secundarias.

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

• Autenticar el cliente
• Obtener una base de datos
• Obtener una colección
• Creación de un índice
• Creación de un documento
• Obtención de un documento
• Consulta de documentos

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

CLI de Azure

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

az group delete --name $resourceGroupName

PowerShell

Use el cmdlet Remove-AzResourceGroup para eliminar el grupo de recursos.

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

Portal

1. Vaya al grupo de recursos que ha creado anteriormente en Azure Portal.

2. Seleccione Eliminar grupo de recursos.

3. En el cuadro de diálogo ¿Seguro que desea eliminar?, escriba el nombre del grupo de recursos y seleccione Eliminar.