Prise en main d’Azure Cosmos DB for MongoDB et de Python

Article
08/15/2024

S’APPLIQUE À : MongoDB

Cet article explique comment se connecter à Azure Cosmos DB for MongoDB à l’aide du package de pilotes PyMongo. Une fois connecté, vous pouvez effectuer des opérations sur des bases de données, des collections et des documents.

Notes

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

Cet article vous montre comment communiquer avec l’API d’Azure Cosmos DB pour MongoDB à l’aide de l’un des pilotes clients MongoDB open source pour Python, PyMongo.

Prérequis

Compte Azure avec un abonnement actif. Créez un compte gratuitement.
Python 3.8+
Interface de ligne de commande Azure (CLI) ou Azure PowerShell
Ressource Azure Cosmos DB for MongoDB

Créer une application Python

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.
Créez un fichier requirements.txt qui liste les packages PyMongo et python-dotenv. Le package dotenv est utilisé pour lire les variables d’environnement à partir d’un fichier .env pendant le développement local.
```
# 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

Connexion avec le pilote PyMongo à Azure Cosmos DB for MongoDB

Pour vous connecter à Azure Cosmos DB avec le pilote PyMongo, créez une instance de l’objet MongoClient. Cette classe est le point de départ pour effectuer toutes les opérations sur des bases de données.

Le constructeur le plus courant pour MongoClient prend uniquement le paramètre host, qui, dans cet article, est défini sur la variable d’environnement COSMOS_CONNECTION_STRING. D’autres paramètres facultatifs et paramètres de mot clé sont utilisables dans le constructeur. La plupart des paramètres facultatifs peuvent également être spécifiés avec le paramètre host. Si la même option est transmise avec host et en paramètre, le paramètre est prioritaire.

Reportez-vous au guide de résolution des problèmes de connexion.

Obtenir le nom de la ressource

Dans les commandes ci-dessous, nous affichons msdocs-cosmos comme nom du groupe de ressources. Modifiez le nom en fonction de votre situation.

Créez une variable d’interpréteur de commandes pour resourceGroupName.
```
# Variable for resource group name
resourceGroupName="msdocs-cosmos"
```
Utilisez la commande az cosmosdb list pour récupérer le nom du premier compte Azure Cosmos DB dans votre groupe de ressources et le stocker dans la variable d’interpréteur de commandes accountName.
```
# Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)
```

Créez une variable d’interpréteur de commandes pour RESOURCE_GROUP_NAME.

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

Utilisez la cmdlet Get-AzCosmosDBAccountKey pour récupérer le nom du premier compte Azure Cosmos DB de votre groupe de ressources et le stocker dans la variable d’interpréteur de commandes 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
```

Récupération de votre chaîne de connexion

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 
```
Enregistrez les valeurs de CLÉ PRIMAIRE. Vous aurez besoin de ces informations d’identification ultérieurement.

Recherchez la CHAÎNE DE CONNEXION dans la liste des chaînes de connexion du compte à l’aide de l’applet de commande Get-AzCosmosDBAccountKey.

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
    Type = "ConnectionStrings"
}    
Get-AzCosmosDBAccountKey @parameters |
    Select-Object -Property "Primary MongoDB Connection String"

Enregistrez la valeur de CHAÎNE DE CONNEXION. Vous aurez besoin de ces informations d’identification ultérieurement.

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

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

L’utilisation d’un fichier .env constitue la méthode standard de stockage des variables d’environnement dans un projet. Créez un fichier .env à la racine de votre projet. Ajoutez les lignes suivantes au fichier .env :

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

Créer un client MongoClient avec une chaîne de connexion

Ajoutez des dépendances pour faire référence aux packages npm PyMongo et python-dotenv.
```
import os
import sys

import pymongo
from dotenv import load_dotenv
```

Définissez une nouvelle instance de la classe MongoClient en utilisant le constructeur et la chaîne de connexion lue à partir d’une variable d’environnement.

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

Pour plus d’informations sur les différentes façons de créer une instance MongoClient, consultez Établissement d’une connexion avec MongoClient.

Fermer la connexion MongoClient

Lorsque votre application en a terminé avec la connexion, n’oubliez pas de la fermer. Cet appel .close() doit être effectué une fois tous les appels de base de données effectués.

client.close()

Utiliser des classes de clients MongoDB avec l’API Azure Cosmos DB for MongoDB

Avant de commencer à générer l’application, examinons la hiérarchie des ressources dans Azure Cosmos DB. Azure Cosmos DB a un modèle objet spécifique utilisé pour créer et accéder aux ressources. 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 de base de données 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 ou plusieurs classes Python associées. Voici une liste des classes 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.

Voir aussi

Étapes suivantes

Une fois que vous avez établi une connexion à un compte d’API pour MongoDB, utilisez le guide suivant pour créer et gérer des bases de données.

Création d’une base de données dans Azure Cosmos DB for MongoDB à l’aide de Python

Partager via