Quickstart: Azure Cosmos DB voor MongoDB voor Python met MongoDB-stuurprogramma

  • Artikel

VAN TOEPASSING OP: MongoDB

Ga aan de slag met het PyMongo-pakket om databases, verzamelingen en documenten te maken in uw Azure Cosmos DB-resource. Volg deze stappen om het pakket te installeren en voorbeeldcode voor basistaken uit te proberen.

Notitie

De voorbeeldcodefragmenten zijn beschikbaar op GitHub als een Python-project.

In deze quickstart communiceert u met de API van Azure Cosmos DB voor MongoDB met behulp van een van de opensource MongoDB-clientstuurprogramma's voor Python, PyMongo. U gebruikt ook de MongoDB-extensieopdrachten, die zijn ontworpen om u te helpen bij het maken en verkrijgen van databasebronnen die specifiek zijn voor het Azure Cosmos DB-capaciteitsmodel.

Vereisten

Controle van vereisten

  • Voer in een terminal- of opdrachtvenster uit python --version om te controleren of u een recente versie van Python hebt.
  • Voer az --version (Azure CLI) of Get-Module -ListAvailable Az* (Azure PowerShell) uit om te controleren of de juiste Azure-opdrachtregelprogramma's zijn geïnstalleerd.

Instellen

In deze sectie wordt uitgelegd hoe u een Azure Cosmos DB-account maakt en een project instelt dat gebruikmaakt van het MongoDB NPM-pakket.

Een Azure Cosmos DB-account maken

In deze quickstart maakt u één Azure Cosmos DB-account met behulp van de API voor MongoDB.

  1. Maak shell-variabelen voor accountName, resourceGroupName en locatie.

    # 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. Als u dat nog niet hebt gedaan, meldt u zich aan bij de Azure CLI met behulp van de az login opdracht.

  3. Gebruik de az group create opdracht om een nieuwe resourcegroep in uw abonnement te maken.

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

  4. Gebruik de az cosmosdb create opdracht om een nieuw Azure Cosmos DB voor MongoDB-account te maken met standaardinstellingen.

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

MongoDB-verbindingsreeks ophalen

  1. Zoek de API voor MongoDB-verbindingsreeks in de lijst met verbindingsreeks s voor het account met de az cosmosdb keys list opdracht.

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

  2. Noteer de WAARDEN VAN DE PRIMAIRE SLEUTEL . U gebruikt deze referenties later.

Een nieuwe Python-app maken

  1. Maak een nieuwe lege map met behulp van de gewenste terminal en wijzig de map in de map.

    Notitie

    Als u alleen de voltooide code wilt, downloadt of forkt u de voorbeeldcodefragmentenopslagplaats met het volledige voorbeeld. U kunt ook git clone de opslagplaats in Azure Cloud Shell gebruiken om de stappen in deze quickstart te doorlopen.

  2. Maak een requirements.txt-bestand met de PyMongo - en python-dotenv-pakketten .

    # requirements.txt
pymongo
python-dotenv

  3. Maak een virtuele omgeving en installeer de pakketten.

    # 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

Omgevingsvariabelen configureren

Als u de WAARDEN VOOR VERBINDINGSREEKS in uw code wilt gebruiken, stelt u deze waarde in in de lokale omgeving waarop de toepassing wordt uitgevoerd. Als u de omgevingsvariabele wilt instellen, gebruikt u de terminal van uw voorkeur om de volgende opdrachten uit te voeren:

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

Objectmodel

Laten we eens kijken naar de hiërarchie van resources in de API voor MongoDB en het objectmodel dat wordt gebruikt voor het maken en openen van deze resources. Azure Cosmos DB maakt resources in een hiërarchie die bestaat uit accounts, databases, verzamelingen en documenten.

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

Elk type resource wordt vertegenwoordigd door een Python-klasse. Dit zijn de meest voorkomende klassen:

  • MongoClient : de eerste stap bij het werken met PyMongo is het maken van een MongoClient om verbinding te maken met de API van Azure Cosmos DB voor MongoDB. Het clientobject wordt gebruikt om aanvragen aan de service te configureren en uitvoeren.

  • Database : de API van Azure Cosmos DB voor MongoDB kan een of meer onafhankelijke databases ondersteunen.

  • Verzameling : een database kan een of meer verzamelingen bevatten. Een verzameling is een groep documenten die zijn opgeslagen in MongoDB en kan worden beschouwd als ongeveer het equivalent van een tabel in een relationele database.

  • Document - Een document is een set sleutel-waardeparen. Documenten hebben een dynamisch schema. Dynamisch schema betekent dat documenten in dezelfde verzameling niet dezelfde set velden of structuur hoeven te hebben. En algemene velden in documenten van een verzameling kunnen verschillende typen gegevens bevatten.

Zie het artikel over het Azure Cosmos DB-resourcemodel voor meer informatie over de hiërarchie van entiteiten.

Codevoorbeelden

Met de voorbeeldcode die in dit artikel wordt beschreven, wordt een database gemaakt met de naam adventureworksproductseen verzameling. De products verzameling is ontworpen om productdetails te bevatten, zoals naam, categorie, hoeveelheid en een verkoopindicator. Elk product bevat ook een unieke id. De volledige voorbeeldcode bevindt zich op https://github.com/Azure-Samples/azure-cosmos-db-mongodb-python-getting-started/tree/main/001-quickstart/.

Voor de onderstaande stappen gebruikt de database geen sharding en wordt een synchrone toepassing weergegeven met behulp van het PyMongo-stuurprogramma . Gebruik het motorstuurprogramma voor asynchrone toepassingen.

De client verifiëren

  1. Maak in de projectmap een run.py-bestand . Voeg in uw editor vereiste instructies toe om te verwijzen naar pakketten die u gaat gebruiken, inclusief de PyMongo- en python-dotenv-pakketten.

    import os
import sys
from random import randint

import pymongo
from dotenv import load_dotenv

  2. Haal de verbindingsgegevens op uit de omgevingsvariabele die is gedefinieerd in een .env-bestand .

    load_dotenv()
CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")

  3. Definieer constanten die u in de code gaat gebruiken.

    DB_NAME = "adventureworks"
COLLECTION_NAME = "products"

Verbinding maken naar de API van Azure Cosmos DB voor MongoDB

Gebruik het MongoClient-object om verbinding te maken met uw Azure Cosmos DB voor MongoDB-resource. De verbindingsmethode retourneert een verwijzing naar de database.

client = pymongo.MongoClient(CONNECTION_STRING)

Database ophalen

Controleer of de database bestaat met list_database_names methode. Als de database niet bestaat, gebruikt u de opdracht database-extensie maken om deze te maken met een opgegeven ingerichte doorvoer.

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

Verzameling ophalen

Controleer of de verzameling bestaat met de methode list_collection_names . Als de verzameling niet bestaat, gebruikt u de opdracht verzamelingsextensie maken om deze te maken.

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

Een index maken

Maak een index met behulp van de opdracht voor de updateverzamelingsextensie. U kunt de index ook instellen in de opdracht verzamelingsextensie maken. Stel de index name in op eigenschap in dit voorbeeld, zodat u later kunt sorteren met de sorteermethode van de cursorklasse op productnaam.

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

Een document maken

Maak een document met de producteigenschappen voor de adventureworks database:

  • Een categorie-eigenschap . Deze eigenschap kan worden gebruikt als de logische partitiesleutel.
  • Een naameigenschap .
  • Een voorraadhoeveelheideigenschap.
  • Een verkoopeigenschap , waarmee wordt aangegeven of het product te koop is.
"""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))

Maak een document in de verzameling door de bewerking op verzamelingsniveau aan te roepen update_one. In dit voorbeeld gaat u upsert in plaats van een nieuw document te maken . Upsert is in dit voorbeeld niet nodig omdat de productnaam willekeurig is. Het is echter een goede gewoonte om te upsert voor het geval u de code meer dan één keer uitvoert en de productnaam hetzelfde is.

Het resultaat van de update_one bewerking bevat de _id veldwaarde die u in volgende bewerkingen kunt gebruiken. De eigenschap _id is automatisch gemaakt.

Een document ophalen

Gebruik de methode find_one om een document op te halen.

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

In Azure Cosmos DB kunt u een goedkopere leesbewerking voor punten uitvoeren met behulp van zowel de unieke id (_id) als een partitiesleutel.

Query's uitvoeren voor documenten

Nadat u een document hebt ingevoegd, kunt u een query uitvoeren om alle documenten op te halen die overeenkomen met een specifiek filter. In dit voorbeeld vindt u alle documenten die overeenkomen met een specifieke categorie: gear-surf-surfboards. Zodra de query is gedefinieerd, roept Collection.find u aan om een Cursor resultaat op te halen en gebruikt u vervolgens sorteren.

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

Problemen oplossen:

  • Als er een fout optreedt, bijvoorbeeld The index path corresponding to the specified order-by item is excluded., controleert u of u de index hebt gemaakt.

De code uitvoeren

Met deze app maakt u een API voor mongoDB-database en -verzameling en maakt u een document en leest u vervolgens exact hetzelfde document terug. Ten slotte geeft het voorbeeld een query uit die documenten retourneert die overeenkomen met een opgegeven productcategorie. Bij elke stap voert het voorbeeld informatie uit naar de console over de stappen die deze heeft uitgevoerd.

Als u de app wilt uitvoeren, gebruikt u een terminal om naar de toepassingsmap te navigeren en de toepassing uit te voeren.

python run.py

De uitvoer van de app moet er ongeveer uitzien als in dit voorbeeld:


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}

Resources opschonen

Wanneer u het Azure Cosmos DB for NoSQL-account niet meer nodig hebt, kunt u de bijbehorende resourcegroep verwijderen.

Gebruik de az group delete opdracht om de resourcegroep te verwijderen.

az group delete --name $resourceGroupName