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

  • Article

S’APPLIQUE À : MongoDB

Démarrez avec le package PyMongo pour créer des bases de données, des collections et des documents dans votre ressource Azure Cosmos DB. Suivez les étapes suivantes pour installer le package et essayer un exemple de code pour les tâches de base.

Notes

Les exemples d’extraits de code sont disponibles sur GitHub sous forme de projet Python.

Dans ce guide de démarrage rapide, vous allez communiquer avec l’API d’Azure Cosmos DB pour MongoDB à l’aide de l’un des pilotes clients MongoDB open source pour Python, PyMongo. De plus, vous allez utiliser les commandes d’extension MongoDB, conçues pour vous aider à créer et obtenir des ressources de base de données spécifiques du modèle de capacité Azure Cosmos DB.

Prérequis

Vérification du prérequis

  • Dans une fenêtre de terminal ou de commande, exécutez python --version pour vérifier que vous disposez d’une version récente de Python.
  • Exécutez az --version (Azure CLI) ou Get-Module -ListAvailable Az* (Azure PowerShell) pour vérifier que les outils de ligne de commande Azure appropriés sont installés.

Configuration

Cette section vous guide dans la création d’un compte Azure Cosmos DB et dans la configuration d’un projet qui utilise le package npm MongoDB.

Créer un compte Azure Cosmos DB

Ce guide de démarrage rapide crée un compte Azure Cosmos DB à l’aide de l’API MongoDB.

  1. Créez des variables d’interpréteur de commandes pour accountName, resourceGroupName et 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 vous ne l’avez pas déjà fait, connectez-vous à Azure CLI à l’aide de la commande az login.

  3. Utilisez la commande az group create pour créer un groupe de ressources dans votre abonnement.

    az group create \
    --name $resourceGroupName \
    --location $location

  4. Utilisez la commande az cosmosdb create pour créer un compte Azure Cosmos DB for MongoDB avec les paramètres par défaut.

    az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location
    --kind MongoDB

Obtenir la chaîne de connexion MongoDB

  1. Recherchez la chaîne de connexion de l’API MongoDB dans la liste des chaînes de connexion du compte à l’aide de la commande az cosmosdb keys list.

    az cosmosdb keys list --type connection-strings \
    --resource-group $resourceGroupName \
    --name $accountName

  2. Enregistrez les valeurs de CLÉ PRIMAIRE. Vous aurez besoin de ces informations d’identification ultérieurement.

Créer une application Python

  1. Créez un dossier vide à l’aide de votre terminal préféré et changez de répertoire pour basculer vers ce dossier.

    Notes

    Si vous voulez juste le code terminé, téléchargez ou dupliquez (fork) et clonez le dépôt des exemples d’extraits de code qui contient l’exemple complet. Vous pouvez également utiliser la commande git clone sur le dépôt dans Azure Cloud Shell pour suivre les étapes décrites dans ce guide de démarrage rapide.

  2. Créez un fichier requirements.txt qui liste les packages PyMongo et python-dotenv.

    # requirements.txt
pymongo
python-dotenv

  3. Créez un environnement virtuel et installez les packages.

    # 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

Configuration des variables d’environnement

Pour utiliser les valeurs de CHAÎNE DE CONNEXION dans votre code, définissez cette valeur dans l’environnement local exécutant l’application. Pour définir la variable d’environnement, utilisez votre terminal préféré pour exécuter les commandes suivantes :

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

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.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, collections, and docs.

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.

Exemples de code

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

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

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

  3. Définissez les constantes que vous allez utiliser dans le code.

    DB_NAME = "adventureworks"
COLLECTION_NAME = "products"

Se connecter à l’API d’Azure Cosmos DB pour 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