Introduzione ad Azure Cosmos DB for MongoDB e Python

Articolo
08/15/2024

SI APPLICA A: MongoDB

Questo articolo illustra come connettersi ad Azure Cosmos DB for MongoDB usando il pacchetto del driver PyMongo. Dopo la connessione è possibile eseguire operazioni su database, raccolte e documenti.

Nota

I frammenti di codice di esempio sono disponibili in GitHub come progetto Python.

Questo articolo illustra come comunicare con l'API di Azure Cosmos DB per MongoDB usando uno dei driver client MongoDB open source per Python, PyMongo.

Prerequisiti

Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
Python 3.8+
Interfaccia della riga di comando di Azure (CLI) o Azure PowerShell
Risorsa Azure Cosmos DB for MongoDB

Creare una nuova app Python

Creare una nuova cartella vuota usando il terminale preferito e passare alla cartella.

Nota

Se si vuole solo il codice finito, scaricare o creare una copia tramite fork e clonare il repository dei frammenti di codice di esempio con l'esempio completo. È anche possibile git clone eseguire il repository in Azure Cloud Shell per esaminare i passaggi illustrati in questa guida introduttiva.
Creare un file requirements.txt che elenca i pacchetti PyMongo e python-dotenv. Il pacchetto dotenv viene usato per leggere le variabili di ambiente da un file di .env durante lo sviluppo locale.
```
# requirements.txt
pymongo
python-dotenv
```

Creare un ambiente virtuale e installare i pacchetti.

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

Connettersi con il driver PyMongo ad Azure Cosmos DB for MongoDB

Per connettersi al driver PyMongo ad Azure Cosmos DB, creare un'istanza dell'oggetto MongoClient. Questa classe è il punto di partenza per eseguire tutte le operazioni sui database.

Il costruttore più comune per MongoClient richiede solo il parametro host, che in questo articolo è impostato sulla variabile di ambiente COSMOS_CONNECTION_STRING. Esistono altri parametri facoltativi e parametri di parola chiave che è possibile usare nel costruttore. Molti dei parametri facoltativi possono anche essere specificati con il parametro host. Se viene passata la stessa opzione con host e come parametro, il parametro ha la precedenza.

In caso di problemi, fare riferimento alla guida alla risoluzione dei problemi di connessione.

Ottenere il nome della risorsa

Nei comandi seguenti viene visualizzato msdocs-cosmos come nome del gruppo di risorse. Modificare il nome in base alle esigenze della situazione.

Creare una variabile di shell per resourceGroupName.

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

Usare il comando az cosmosdb list per recuperare il nome del primo account Azure Cosmos DB nel gruppo di risorse e archiviarlo nella variabile della shell accountName.

# Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

Creare una variabile di shell per RESOURCE_GROUP_NAME.

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

Usare il cmdlet Get-AzCosmosDBAccountKey per recuperare il nome del primo account Azure Cosmos DB nel gruppo di risorse e archiviarlo nella variabile della shell 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
```

Recuperare la stringa di connessione

Trovare la stringa di connessione dell'API per MongoDB dall'elenco delle stringhe di connessione per l'account con il comando az cosmosdb keys list.
```
az cosmosdb keys list --type connection-strings \
    --resource-group $resourceGroupName \
    --name $accountName 
```
Registrare i valori PRIMARY KEY. Queste credenziali saranno necessarie più avanti.

Trovare CONNECTION STRING dall'elenco di chiavi e stringhe di connessione per l'account con il cmdlet Get-AzCosmosDBAccountKey.

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

Registrare il valore di CONNECTION STRING. Queste credenziali saranno necessarie più avanti.

Configurare le variabili di ambiente

Per usare i valori della STRINGA DI CONNESSIONE all'interno del codice, impostare questo valore nell'ambiente locale che esegue l'applicazione. Per impostare la variabile di ambiente, usare il terminale preferito per eseguire i comandi seguenti:

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

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

Un file .env è un modo standard per archiviare le variabili di ambiente in un progetto. Creare un file .env nella radice del progetto. Aggiungere le righe seguenti al file .env :

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

Creare MongoClient con la stringa di connessione

Aggiungere dipendenze per fare riferimento ai pacchetti PyMongo e python-dotenv.
```
import os
import sys

import pymongo
from dotenv import load_dotenv
```

Definire una nuova istanza della classe MongoClient usando il costruttore e la stringa di connessione letta da una variabile di ambiente.

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

Per altre informazioni sui diversi modi per creare un'istanza MongoClient, fare riferimento a Creazione di una connessione con MongoClient.

Chiudere la connessione MongoClient

Al termine della connessione dell’applicazione, ricordarsi di chiuderla. Tale chiamata .close() deve essere eseguita dopo tutte le chiamate al database.

client.close()

Usare le classi client MongoDB con Azure Cosmos DB per l'API per MongoDB

Prima di iniziare a compilare l'applicazione, verrà esaminata la gerarchia di risorse in Azure Cosmos DB. Azure Cosmos DB ha un modello a oggetti specifico usato per creare e accedere alle risorse. Azure Cosmos DB crea risorse in una gerarchia costituita da account, database, raccolte e documenti.

Diagramma della gerarchia di Azure Cosmos DB DB, inclusi account, database, raccolte e documenti.

Ogni tipo di risorsa è rappresentato da una o più classi Python associate. Ecco un elenco delle classi più comuni:

MongoClient: il primo passaggio quando si usa PyMongo consiste nel creare un MongoClient per connettersi all'API di Azure Cosmos DB for MongoDB. L'oggetto client viene usato per configurare ed eseguire richieste nel servizio.
Database : l'API di Azure Cosmos DB for MongoDB può supportare uno o più database indipendenti.
Raccolta : un database può contenere una o più raccolte. Una raccolta è un gruppo di documenti archiviati in MongoDB e può essere considerata approssimativamente l'equivalente di una tabella in un database relazionale.
Documento : un documento è un set di coppie chiave-valore. I documenti hanno uno schema dinamico. “Schema dinamico” significa che i documenti nella stessa raccolta non devono avere lo stesso set di campi o struttura. E i campi comuni nei documenti di una raccolta possono contenere tipi diversi di dati.

Per altre informazioni sulla gerarchia delle entità, vedere l'articolo Modello di risorsa di Azure Cosmos DB.

Vedi anche

Passaggi successivi

Dopo aver eseguito la connessione a un account API for MongoDB, passare alla guida successiva per creare e gestire i database.

Creare un database in Azure Cosmos DB for MongoDB con Python

Condividi tramite