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

  • Articolo

SI APPLICA A: Mongodb

Introduzione al pacchetto PyMongo per creare database, raccolte e documenti all'interno della risorsa di Azure Cosmos DB. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per le attività di base.

Nota

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

In questa guida introduttiva si comunicheranno con l'API di Azure Cosmos DB per MongoDB usando uno dei driver client MongoDB open source per Python, PyMongo. Si useranno anche i comandi dell'estensione MongoDB, progettati per creare e ottenere risorse di database specifiche per il modello di capacità di Azure Cosmos DB.

Prerequisiti

Controllo dei prerequisiti

  • In un terminale o in una finestra di comando eseguire python --version per verificare di avere una versione recente di Python.
  • Eseguire az --version (interfaccia della riga di comando di Azure) o Get-Module -ListAvailable Az* (Azure PowerShell) per verificare che siano installati gli strumenti da riga di comando di Azure appropriati.

Configurazione

Questa sezione illustra come creare un account Azure Cosmos DB e configurare un progetto che usa il pacchetto npm mongoDB.

Creare un account Azure Cosmos DB

Questa guida introduttiva creerà un singolo account Azure Cosmos DB usando l'API per MongoDB.

  1. Creare variabili della shell per accountName, resourceGroupName e 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. Se non è già stato fatto, accedere all'interfaccia della riga di comando di Azure usando il az login comando .

  3. Usare il az group create comando per creare un nuovo gruppo di risorse nella sottoscrizione.

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

  4. Usare il az cosmosdb create comando per creare un nuovo account Azure Cosmos DB per MongoDB con le impostazioni predefinite.

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

Ottenere la stringa di connessione di MongoDB

  1. Trovare l'API per MongoDB stringa di connessione dall'elenco di stringa di connessione per l'account con il az cosmosdb keys list comando .

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

  2. Registrare i valori PRIMARY KEY . Queste credenziali verranno usate in un secondo momento.

Creare una nuova app Python

  1. 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 git clone possibile eseguire il repository in Azure Cloud Shell per esaminare i passaggi illustrati in questa guida introduttiva.

  2. Creare un file requirements.txt che elenca i pacchetti PyMongo e python-dotenv .

    # requirements.txt
pymongo
python-dotenv

  3. Creare un ambiente virtuale e installare i pacchetti.

    # 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

Configurare le variabili di ambiente

Per usare i valori CONNECTION STRING 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>"

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.

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

Ogni tipo di risorsa è rappresentato da una classe Python. Ecco 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 per MongoDB. L'oggetto client viene usato per configurare ed eseguire richieste nel servizio.

  • Database : l'API di Azure Cosmos DB per 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 considerato 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. Lo 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 risorse di Azure Cosmos DB.

Esempi di codice

Il codice di esempio descritto in questo articolo crea un database denominato con una raccolta denominata adventureworksproducts. La products raccolta è 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 motore .

Autenticare il client

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

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

  3. Definire le costanti che verranno usate nel codice.

    DB_NAME = "adventureworks"
COLLECTION_NAME = "products"

Connessione all'API di Azure Cosmos DB per MongoDB

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

client = pymongo.MongoClient(CONNECTION_STRING)

Recupera database

Controllare se il database esiste con list_database_names metodo. 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 .Create an index using the update collection extension command. È anche possibile impostare l'indice nel comando create collection extension .You can also set the index in the create collection extension command. Impostare l'indice su name proprietà 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à del prodotto per il adventureworks database:

  • Proprietà di categoria . Questa proprietà può essere usata come chiave di partizione logica.
  • Proprietà name .
  • Proprietà della quantità di inventario.
  • Proprietà di vendita 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 _id campo che è possibile usare nelle operazioni successive. La proprietà _id è stata creata automaticamente.

Ottenere 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. In questo esempio vengono trovati tutti i documenti corrispondenti a una categoria specifica: gear-surf-surfboards. Dopo aver definito la query, chiamare Collection.find per ottenere un Cursor risultato e 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 visualizzato un errore, The index path corresponding to the specified order-by item is excluded.ad esempio , assicurarsi di aver creato l'indice.

Eseguire il codice

Questa app crea un'API per il database e la raccolta mongoDB e crea un documento e quindi legge lo stesso documento esattamente. 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 dovrebbe essere 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 non è più necessario l'account Azure Cosmos DB per NoSQL, è possibile eliminare il gruppo di risorse corrispondente.

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

az group delete --name $resourceGroupName