Bien démarrer avec Azure Cosmos DB for NoSQL à l’aide de Python

  • Article

S’APPLIQUE À : NoSQL

Cet article vous montre comment vous connecter à Azure Cosmos DB for NoSQL à l’aide du SDK Python. Une fois connecté, vous pouvez effectuer des opérations sur des bases de données, des conteneurs et des éléments.

Package (Pypi) | Exemples | Référence API | Code source de la bibliothèque | Envoyer des commentaires

Prérequis

Configuration de votre projet

Créez un environnement dans lequel vous pouvez exécuter du code Python.

Avec un environnement virtuel, vous pouvez installer des packages Python dans un environnement isolé sans affecter le reste de votre système.

Installez le Kit de développement logiciel (SDK) Python Azure Cosmos DB for NoSQL dans l’environnement virtuel.

pip install azure-cosmos

Créer l’application Python

Dans votre environnement, créez un fichier app.py et ajoutez-y le code suivant :

import json
import os
import sys
import uuid

from azure.core.exceptions import AzureError
from azure.cosmos import CosmosClient, PartitionKey

Le code précédent importe les modules que vous utiliserez dans le reste de l’article.

Se connecter à Azure Cosmos DB for NoSQL

Pour vous connecter à l’API pour NoSQL de Azure Cosmos DB, créez une instance de la classe CosmosClient. Cette classe est le point de départ pour effectuer toutes les opérations sur des bases de données. Il existe trois façons de se connecter à un compte d’API pour NoSQL à l’aide de la classe CosmosClient :

Se connecter avec un point de terminaison et une clé

Le constructeur pour CosmosClient a deux paramètres requis :

Paramètre Valeur d'exemple Description
url COSMOS_ENDPOINT variable d’environnement Point de terminaison d’API for NoSQL à utiliser pour toutes les requêtes.
credential COSMOS_KEY variable d’environnement Clé de compte ou jeton de ressource à utiliser lors de l’authentification.

Récupérer le point de terminaison et la clé de votre compte

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

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-python-howto-rg"

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

  3. Obtenez l’URI de point de terminaison d’API for NoSQL pour le compte à l’aide de la commande az cosmosdb show.

    az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "documentEndpoint"

  4. Recherchez la CLÉ PRIMAIRE dans la liste des clés du compte avec la commande az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

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

Pour utiliser les valeurs URI et CLÉ PRIMAIRE dans votre code Python, conservez-les dans de nouvelles variables d’environnement sur l’ordinateur local exécutant l’application.

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Créer CosmosClient avec un point de terminaison de compte et une clé

Créez une instance de la classe CosmosClient avec les variables d’environnement COSMOS_ENDPOINT et COSMOS_KEY en tant que paramètres.

ENDPOINT = os.environ["COSMOS_ENDPOINT"]
KEY = os.environ["COSMOS_KEY"]

client = CosmosClient(url=ENDPOINT, credential=KEY)

Se connecter avec une chaîne de connexion

La classe CosmosClient a une méthode from_connection_string que vous pouvez utiliser pour vous connecter avec un paramètre obligatoire :

Paramètre Valeur d'exemple Description
conn_str COSMOS_CONNECTION_STRING variable d’environnement La chaîne de connexion au compte d’API for NoSQL.
credential COSMOS_KEY variable d’environnement Autre clé de compte ou jeton de ressource facultatif à utiliser au lieu de celui de la chaîne de connexion.

Récupérer votre chaîne de connexion de compte

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

  2. Recherchez la CHAÎNE DE CONNEXION PRIMAIRE dans la liste des chaînes de connexion pour le compte avec la commande az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "connection-strings" \
    --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"

Pour utiliser la valeur CHAÎNE DE CONNEXION PRIMAIRE dans votre code Python, conservez-la dans une nouvelle variable d’environnement sur l’ordinateur local exécutant l’application.

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Créer CosmosClient avec une chaîne de connexion

Créez une instance de la classe CosmosClient avec les variables d’environnement COSMOS_CONNECTION_STRING en tant que seul paramètre.

CONN_STR = os.environ["COSMOS_CONNECTION_STRING"]

client = CosmosClient.from_connection_string(conn_str=CONN_STR)

Se connecter à l’aide de la plateforme d’identités Microsoft

Pour vous connecter à votre compte d’API for NoSQL à l’aide de la plateforme d’identités Microsoft et de Microsoft Entra ID, utilisez un principal de sécurité. Le type exact de principal dépend de l’emplacement où vous hébergez votre code d’application. Le tableau ci-dessous sert de guide de référence rapide.

Emplacement d’exécution de l’application Principal de sécurité
Ordinateur local (développement et test) Identité de l’utilisateur ou principal du service
Azure Identité managée
Serveurs ou clients en dehors d’Azure Principal du service

Importer Azure.Identity

Le package azure-identity contient les fonctionnalités d’authentification principales partagées entre toutes les bibliothèques du kit de développement logiciel (SDK) Azure.

Importez le package azure-identity dans votre environnement.

pip install azure-identity

Créer CosmosClient avec l’implémentation des informations d’identification par défaut

Si vous testez sur une machine locale ou que votre application s’exécute sur des services Azure avec prise en charge directe des identités managées, obtenez un jeton OAuth en créant une instance DefaultAzureCredential.

Dans votre app.py :

  • Obtenez le point de terminaison auquel se connecter comme indiqué dans la section ci-dessus pour Se connecter avec un point de terminaison et une clé et définissez-le en tant que variable COSMOS_ENDPOINTd’environnement .

  • Importez defaultAzureCredential et créez une instance de celui-ci.

  • Créez une instance de la classe CosmosClient avec les variables d’environnement ENDPOINT et informations de connexion en tant que paramètres.

from azure.identity import DefaultAzureCredential

ENDPOINT = os.environ["COSMOS_ENDPOINT"]

credential = DefaultAzureCredential()

client = CosmosClient(ENDPOINT, credential)

Important

Pour plus d’informations sur l’ajout du rôle approprié pour permettre DefaultAzureCredential fonctionner, consultez Configurer le contrôle d’accès en fonction du rôle avec l’ID Microsoft Entra pour votre compte Azure Cosmos DB. En particulier, consultez la section sur la création de rôles et leur affectation à un ID principal.

Créer CosmosClient avec l’implémentation des informations d’identification par défaut

Si vous prévoyez de déployer l’application en dehors d’Azure, vous pouvez obtenir un jeton OAuth en utilisant d’autres classes de la bibliothèque de client Azure.Identity pour Python. Ces autres classes dérivent également de la classe TokenCredential.

Pour cet exemple, nous créons une instance ClientSecretCredential à l’aide d’identificateurs client et de locataire, ainsi qu’une clé secrète client.

Dans votre app.py :

  • Obtenez les informations d’identification à partir de variables d’environnement pour un principal de service. Vous pouvez obtenir l’ID client, l’ID locataire et la clé secrète client lorsque vous inscrivez une application dans Microsoft Entra ID. Pour plus d’informations concernant l’inscription d’applications Microsoft Entra, consultez Inscrire une application auprès de la plateforme d’identités Microsoft.

  • Importez ClientSecretCredential et créez une instance avec les variables d’environnement TENANT_ID, CLIENT_IDet CLIENT_SECRET en tant que paramètres.

  • Créez une instance de la classe CosmosClient avec les variables d’environnement ENDPOINT et informations de connexion en tant que paramètres.

from azure.identity import ClientSecretCredential

ENDPOINT = os.environ["COSMOS_ENDPOINT"]
TENANT_ID = os.environ["TENANT_ID"]
CLIENT_ID = os.environ["CLIENT_ID"]
CLIENT_SECRET = os.environ["CLIENT_SECRET"]

credential = ClientSecretCredential(
    tenant_id=TENANT_ID, client_id=CLIENT_ID, client_secret=CLIENT_SECRET
)

client = CosmosClient(ENDPOINT, credential)

Générer votre application

À mesure que vous générez votre application, votre code interagit principalement avec quatre types de ressources :

  • Le compte d’API for NoSQL qui est l’unique espace de noms de niveau supérieur pour vos données Azure Cosmos DB.

  • Bases de données, qui organisent les conteneurs dans votre compte.

  • Conteneurs, qui contiennent un ensemble d’éléments individuels dans votre base de données.

  • Éléments, qui représentent un document JSON dans votre conteneur.

Le diagramme suivant montre la relation entre ces ressources.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, containers, and items.

Chaque type de ressource est représenté par une ou plusieurs classes Python associées. Voici une liste des classes les plus courantes pour la programmation synchrone. (Il existe des classes similaires pour la programmation asynchrone sous l’espace de noms azure.cosmos.aio .)

Classe Description
CosmosClient Cette classe fournit une représentation logique du côté client pour le service Azure Cosmos DB. Ce client est utilisé pour configurer et exécuter des requêtes sur le service.
DatabaseProxy Une interface à une base de données qui peut, ou non, exister dans le service. Cette classe ne devrait pas être instanciée directement. Vous devez plutôt utiliser la méthode CosmosClient get_database_client.
ContainerProxy Interface permettant d’interagir avec un conteneur Cosmos DB spécifique. Cette classe ne devrait pas être instanciée directement. Utilisez plutôt la méthode databaseProxy get_container_client pour obtenir un conteneur existant ou la méthode create_container pour créer un conteneur.

Les guides suivants vous montrent comment utiliser chacune de ces classes pour générer votre application.

Guide Description
Créer une base de données Créer des bases de données
Créer un conteneur Créer des conteneurs
Exemples d’éléments Pointer et lire un élément spécifique

Voir aussi

Étapes suivantes

Une fois que vous êtes connecté à un compte d’API pour NoSQL, utilisez le guide suivant pour créer et gérer des bases de données.

Créer une base de données dans Azure Cosmos DB for NoSQL à l’aide de Python