Démarrage rapide : Azure Cosmos DB for MongoDB pour Python avec pilote MongoDB

Article
08/16/2024

S’APPLIQUE À : MongoDB

Bien démarrer avec MongoDB pour créer des bases de données, des collections et des documents dans votre ressource Azure Cosmos DB. Suivez ces étapes pour déployer une solution minimale sur votre environnement à l’aide de l’interface Azure Developer CLI.

Documentation de référence sur l’API pour MongoDB | Package pymongo | Azure Developer CLI

Prérequis

Compte Azure avec un abonnement actif. Créez un compte gratuitement.
Compte GitHub

Compte Azure avec un abonnement actif. Créez un compte gratuitement.
Azure Developer CLI
Docker Desktop

Configuration

Déployez le conteneur de développement de ce projet sur votre environnement. Utilisez ensuite l’interface Azure Developer CLI (azd) pour créer un compte Azure Cosmos DB for MongoDB et déployer un exemple d’application conteneurisée. L’exemple d’application utilise la bibliothèque de client pour gérer, créer, lire et interroger des exemples de données.

Important

Les comptes GitHub incluent un droit d’utilisation relatif au stockage et aux heures cœur gratuites. Pour plus d’informations, consultez Stockage et heures cœur inclus pour les comptes GitHub.

Ouvrez un terminal dans le répertoire racine du projet.
Authentifiez-vous auprès de l’interface Azure Developer CLI en utilisant azd auth login. Suivez les étapes spécifiées par l’outil pour vous authentifier auprès de l’interface CLI à l’aide de vos informations d’identification Azure préférées.
```
azd auth login
```
Utilisez azd init pour initialiser le projet.
```
azd init --template cosmos-db-mongodb-python-quickstart
```
Remarque

Ce guide de démarrage rapide utilise le dépôt GitHub de modèles azure-samples/cosmos-db-mongodb-python-quickstart. Azure Developer CLI clone automatiquement ce projet sur votre machine s’il ne s’y trouve pas déjà.
Lors de l’initialisation, configurez un nom d’environnement unique.

Conseil

Le nom de l’environnement sera également utilisé comme nom du groupe de ressources cible. Pour ce guide de démarrage rapide, utilisez msdocs-cosmos-db.
Déployez le compte Azure Cosmos DB en utilisant azd up. Les modèles Bicep déploient également un exemple d’application web.
```
azd up
```
Pendant le processus d’approvisionnement, sélectionnez votre abonnement et l’emplacement souhaité. Attendez la fin du processus de provisionnement. Le processus peut prendre environ cinq minutes.

Une fois le provisionnement de vos ressources Azure effectué, une URL vers l’application web en cours d’exécution est incluse dans la sortie.

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.

Utilisez l’URL dans la console pour accéder à votre application web dans le navigateur. Observez la sortie de l’application en cours d’exécution.

Installer la bibliothèque de client

Créez un fichier requirements.txt dans votre répertoire d’application qui liste les paquets PyMongo et python-dotenv.
```
# requirements.txt
pymongo
python-dotenv
```

Créez un environnement virtuel et installez les packages.

Windows
Linux/macOS

# 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

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

Modèle objet

Examinons à présent la hiérarchie des ressources dans l’API pour MongoDB et le modèle objet utilisé pour créer ces ressources et y accéder. Azure Cosmos DB crée des ressources dans une hiérarchie qui se compose de comptes, de bases de données, de collections et de documents.

Diagramme de la hiérarchie d’Azure Cosmos DB comprenant les comptes, les bases de données, les collections et les documents.

Chaque type de ressource est représenté par une classe Python. Voici les erreurs les plus courantes :

MongoClient : La première étape pour utiliser PyMongo consiste à créer un MongoClient pour se connecter à l’API d’Azure Cosmos DB pour MongoDB. Ce client est utilisé pour configurer et exécuter des requêtes sur le service.
Base de données : L’API d’Azure Cosmos DB pour MongoDB peut prendre en charge une ou plusieurs bases de données indépendantes.
Collection : Chaque base de données peut contenir une ou plusieurs collections. Une collection est un groupe de documents stockés dans MongoDB. Elle peut être considérée comme l’équivalent d’une table dans une base de données relationnelle.
Document : Un document est un ensemble de paires clé-valeur. Les documents ont un schéma dynamique. Un schéma dynamique signifie que les documents inclus dans la même collection n’ont pas besoin d’avoir le même ensemble de champs ou ni la même structure. Les champs communs dans les documents d’une collection peuvent contenir des types de données différents.

Pour plus d’informations sur la hiérarchie des entités, consultez l’article Modèle des ressources d’Azure Cosmos DB.

L’exemple de code décrit dans cet article crée une base de données nommée adventureworks avec une collection nommée products. La collection products est conçue pour contenir des détails de produit comme le nom, la catégorie, la quantité et un indicateur de vente. Chaque produit contient également un identificateur unique. L’exemple de code complet se trouve à l’adresse https://github.com/Azure-Samples/azure-cosmos-db-mongodb-python-getting-started/tree/main/001-quickstart/.

Pour les étapes ci-après, la base de données n’utilise pas de partitionnement et présente une application synchrone à l’aide du pilote PyMongo. Pour des applications asynchrones, utilisez le pilote Motor.

Authentifier le client

Dans le répertoire du projet, créez un fichier run.py. Dans votre éditeur, ajoutez les instructions nécessaires pour référencer les packages que vous allez utiliser, notamment les packages PyMongo et python-dotenv.
```
import os
import sys
from random import randint

import pymongo
from dotenv import load_dotenv
```
Obtenez les informations de connexion à partir de la variable d’environnement définie dans un fichier .env.
```
load_dotenv()
CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")
```
Définissez les constantes que vous allez utiliser dans le code.
```
DB_NAME = "adventureworks"
COLLECTION_NAME = "products"
```

Connexion à l’API d’Azure Cosmos DB for MongoDB

Utilisez l’objet MongoClient pour vous connecter à votre ressource Azure Cosmos DB for MongoDB. Cette méthode de connexion retourne une référence à la base de données.

client = pymongo.MongoClient(CONNECTION_STRING)

Obtenir une base de données

Vérifiez si la base de données existe avec la méthode list_database_names. Si la base de données n’existe pas, utilisez la commande d’extension create database pour la créer avec un débit provisionné spécifié.

# 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))

Obtenir une collection

Vérifiez si la collection existe avec la méthode list_collection_names. Si la collection n’existe pas, utilisez la commande d’extension create collection pour la créer.

# 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))

Création d'un index

Créez un index à l’aide de la commande d’extension update collection. Vous pouvez également définir l’index dans la commande d’extension create collection. Définissez l’index sur la propriété name dans cet exemple afin de pouvoir effectuer un tri ultérieurement avec la méthode de tri de classe curseur sur le nom du produit.

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())))

Créer un document

Créez un document avec les propriétés product pour la base de données adventureworks :

Propriété category. Cette propriété peut être utilisée comme clé de partition logique.
Propriété name.
Propriété quantity de l’inventaire.
Propriété sale, indiquant si le produit est en vente.

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

Créez un document dans la collection en appelant l’opération au niveau de la collection update_one. Dans cet exemple, vous allez faire un upsert au lieu de créer un document. Un upsert n’est pas nécessaire dans cet exemple, car le nom du produit est aléatoire. En revanche, il est recommandé de faire un upsert si vous exécutez le code plusieurs fois et que le nom du produit est le même.

Le résultat de l’opération update_one contient la valeur du champ _id que vous pouvez utiliser dans les opérations suivantes. La propriété _id a été créée automatiquement.

Obtenir un document

Utilisez la méthode find_one pour obtenir un document.

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

Dans Azure Cosmos DB, vous pouvez effectuer une opération de lecture de point moins coûteuse à l’aide de l’identificateur unique (_id) et d’une clé de partition.

Interroger des documents

Après avoir inséré un document, vous pouvez exécuter une requête pour obtenir tous les documents qui correspondent à un filtre spécifique. Cet exemple recherche tous les documents qui correspondent à une catégorie spécifique : gear-surf-surfboards. Une fois la requête définie, appelez Collection.find pour obtenir un résultat Cursor, puis utilisez sort.

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

Résolution des problèmes :

Si vous obtenez une erreur telle que The index path corresponding to the specified order-by item is excluded., vérifiez que vous avez créé l’index.

Exécuter le code

Cette application crée une base de données et une collection d’API pour MongoDB et crée un document, puis lit exactement le même document. Enfin, l’exemple émet une requête qui retourne des documents qui correspondent à une catégorie de produit spécifiée. Avec chaque étape, l’exemple génère des informations dans la console sur les étapes qu’elle a effectuées.

Pour exécuter l’application, utilisez un terminal pour accéder au répertoire de l’application et exécuter l’application.

python run.py

La sortie de l’application doit être similaire à l’exemple suivant :


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}

Nettoyer les ressources

Lorsque vous n’avez plus besoin du compte d’API Table Azure Cosmos DB, vous pouvez supprimer le groupe de ressources correspondant.

Pour supprimer le groupe de ressources, utilisez la commande az group delete.

az group delete --name $resourceGroupName

Pour supprimer le groupe de ressources, appelez le cmdlet Remove-AzResourceGroup.

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

Partager via