Guida introduttiva: Azure Cosmos DB for MongoDB per Python con il driver MongoDB

Articolo
08/15/2024

SI APPLICA A: MongoDB

È possibile iniziare a usare MongoDB per creare database, raccolte e documenti all'interno della propria risorsa di Azure Cosmos DB. Seguire questa procedura per distribuire una soluzione minima nell'ambiente usando Azure Developer CLI.

Documentazione | di riferimento dell'API per MongoDB pacchetto | pymongo dell'interfaccia della riga di comando per sviluppatori di Azure

Prerequisiti

Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
Account GitHub

Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
Azure Developer CLI
Docker Desktop

Configurazione

Distribuire il contenitore di sviluppo di questo progetto nell'ambiente. Usare quindi Azure Developer CLI (azd) per creare un account Azure Cosmos DB per MongoDB e distribuire un’applicazione di esempio in contenitori. L'applicazione di esempio usa la libreria client per gestire, creare, leggere ed eseguire query sui dati di esempio.

Importante

Gli account GitHub includono un entitlement di archiviazione e ore di core senza costi. Per altre informazioni, vedere l'articolo sullo spazio di archiviazione e le ore di core inclusi per gli account GitHub.

Aprire un terminale nella directory radice del progetto.
Eseguire l'autenticazione in Azure Developer CLI usando azd auth login. Seguire i passaggi specificati dallo strumento per eseguire l'autenticazione all'interfaccia della riga di comando usando le credenziali di Azure preferite.
```
azd auth login
```
Usare azd init per inizializzare il progetto.
```
azd init --template cosmos-db-mongodb-python-quickstart
```
Nota

Questa guida introduttiva usa il repository GitHub del modello azure-samples/cosmos-db-mongodb-python-quickstart . L'interfaccia della riga di comando per sviluppatori di Azure clona automaticamente questo progetto nel computer, se non è già presente.
Durante l'inizializzazione, configurare un nome di ambiente univoco.

Suggerimento

Il nome dell'ambiente verrà usato anche come nome del gruppo di risorse di destinazione. Per questo avvio rapido è consigliabile usare msdocs-cosmos-db.
Distribuire l'account Azure Cosmos DB usando azd up. I modelli Bicep distribuiscono anche un'applicazione Web di esempio.
```
azd up
```
Durante il processo di provisioning, selezionare la sottoscrizione e la posizione desiderata. Attendere il completamento del processo di provisioning. Per il processo sono necessari circa 5 minuti.

Al termine del provisioning delle risorse di Azure, nell'output viene incluso un URL dell'applicazione Web in esecuzione.

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.

Usare l'URL nella console per passare all'applicazione Web nel browser. Osservare l'output dell'app in esecuzione.

Installare la libreria client

Creare un requirements.txt file nella directory dell'app che elenca i pacchetti PyMongo e python-dotenv .
```
# 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

Modello a oggetti

Esaminiamo la gerarchia delle risorse nell'API per MongoDB e il modello a oggetti usato per creare e accedere a queste risorse. Azure Cosmos DB crea risorse in una gerarchia costituita da account, database, raccolte e documenti.

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

Ogni tipo di risorsa è rappresentato da una classe Python. Di seguito sono elencate le 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.

Il codice di esempio descritto in questo articolo crea un database denominato adventureworks con una raccolta denominata products. La raccolta products è progettata per contenere dettagli del prodotto, ad esempio nome, categoria, quantità e indicatore di vendita. Ogni prodotto contiene anche un identificatore univoco. Il codice di esempio completo si trova in https://github.com/Azure-Samples/azure-cosmos-db-mongodb-python-getting-started/tree/main/001-quickstart/.

Per i passaggi seguenti, il database non userà il partizionamento orizzontale e mostra un'applicazione sincrona usando il driver PyMongo. Per le applicazioni asincrone, usare il driver Motor.

Autenticare il client

Nella directory del progetto, creare un file run.py. Nell'editor aggiungere istruzioni require per fare riferimento ai pacchetti che verranno usati, inclusi i pacchetti PyMongo e python-dotenv.
```
import os
import sys
from random import randint

import pymongo
from dotenv import load_dotenv
```
Ottenere le informazioni di connessione dalla variabile di ambiente definita in un file con estensione .env.
```
load_dotenv()
CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")
```

Definire le costanti che verranno usate nel codice.

DB_NAME = "adventureworks"
COLLECTION_NAME = "products"

Connettersi all'API di Azure Cosmos DB per MongoDB

Usare l'oggetto MongoClient per connettersi alla risorsa Azure Cosmos DB for MongoDB. Il metodo connect restituisce un riferimento al database.

client = pymongo.MongoClient(CONNECTION_STRING)

Recupera database

Controllare se il database esiste con il metodo list_database_names. Se il database non esiste, usare il comando create database extension per crearlo con una velocità effettiva con provisioning specificata.

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

Recupera una raccolta

Controllare se la raccolta esiste con il metodo list_collection_names. Se la raccolta non esiste, usare il comando create collection extension per crearlo.

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

Creare un indice

Creare un indice usando il comando update collection extension. È anche possibile impostare l'indice nel comando create collection extension. Impostare l'indice su proprietà name in questo esempio, in modo che sia possibile ordinare in un secondo momento con il metodo di ordinamento della classe cursore sul nome del prodotto.

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

Creare un documento

Creare un documento con le proprietà di product per il database adventureworks:

Una proprietà category. Questa proprietà può essere usata come chiave della partizione logica.
Una proprietà name.
Una proprietà quantity delle scorte.
Una proprietà sale che indica se il prodotto è in vendita.

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

Creare un documento nella raccolta chiamando l'operazione a livello di raccolta update_one. In questo esempio si esegue l'upsert anziché creare un nuovo documento. Upsert non è necessario in questo esempio perché il nome del prodotto è casuale. Tuttavia, è consigliabile eseguire l'upsert nel caso in cui si esegua il codice più di una volta e il nome del prodotto sia lo stesso.

Il risultato dell'operazione update_one contiene il valore del campo _id che è possibile usare nelle operazioni successive. La proprietà _id è stata creata automaticamente.

Recupera un documento

Utilizzare il metodo find_one per ottenere un documento.

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

In Azure Cosmos DB è possibile eseguire un'operazione di lettura dei punti meno costosa usando sia l'identificatore univoco (_id) che una chiave di partizione.

Eseguire query su documenti

Dopo aver inserito un documento, è possibile eseguire una query per ottenere tutti i documenti che corrispondono a un filtro specifico. Questo esempio trova tutti i documenti corrispondenti a una categoria specifica: gear-surf-surfboards. Dopo aver definito la query, chiamare Collection.find per ottenere un risultato Cursor, quindi usare l'ordinamento.

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

Risoluzione dei problemi:

Se viene restituito un errore, ad esempio The index path corresponding to the specified order-by item is excluded., verificare di aver creato l'indice.

Eseguire il codice

Questa app crea un'API per il database e la raccolta MongoDB, crea un documento e quindi legge lo stesso documento. Infine, nell'esempio viene eseguita una query che restituisce documenti che corrispondono a una categoria di prodotto specificata. Con ogni passaggio, l'esempio restituisce informazioni alla console sui passaggi eseguiti.

Per eseguire l'app, usare un terminale per passare alla directory dell'applicazione ed eseguire l'applicazione.

python run.py

L'output dell'app sarà simile a questo esempio:


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}

Pulire le risorse

Quando l'account Azure Cosmos DB for NoSQL non è più necessario, è possibile eliminare il gruppo di risorse corrispondente.

Usare il comando az group delete per eliminare il gruppo di risorse.

az group delete --name $resourceGroupName

Usare il cmdlet Remove-AzResourceGroup per eliminare il gruppo di risorse.

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

Condividi tramite