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

Artikel
08/15/2024

VAN TOEPASSING OP: MongoDB

Ga aan de slag met MongoDB om databases, verzamelingen en documenten te maken in uw Azure Cosmos DB-resource. Volg deze stappen om een minimale oplossing in uw omgeving te implementeren met behulp van de Azure Developer CLI.

Referentiedocumentatie voor API voor MongoDB pymongo-pakket | Azure Developer CLI |

Vereisten

Een Azure-account met een actief abonnement. Gratis een account maken
Een GitHub-account

Een Azure-account met een actief abonnement. Gratis een account maken
Azure Developer CLI
Docker Desktop

Instellen

Implementeer de ontwikkelcontainer van dit project in uw omgeving. Gebruik vervolgens de Azure Developer CLI (azd) om een Azure Cosmos DB voor MongoDB-account te maken en een containervoorbeeldtoepassing te implementeren. De voorbeeldtoepassing maakt gebruik van de clientbibliotheek voor het beheren, maken, lezen en opvragen van voorbeeldgegevens.

Belangrijk

GitHub-accounts bevatten gratis rechten voor opslag en kernuren. Zie inbegrepen opslag- en kernuren voor GitHub-accounts voor meer informatie.

Open een terminal in de hoofdmap van het project.
Verifiëren bij de Azure Developer CLI met behulp van azd auth login. Volg de stappen die door het hulpprogramma zijn opgegeven om te verifiëren bij de CLI met behulp van uw favoriete Azure-referenties.
```
azd auth login
```
Gebruik azd init dit om het project te initialiseren.
```
azd init --template cosmos-db-mongodb-python-quickstart
```
Notitie

In deze quickstart wordt gebruikgemaakt van de GitHub-opslagplaats azure-samples/cosmos-db-mongodb-python-quickstart-sjabloon . De Azure Developer CLI kloont dit project automatisch naar uw computer als dit nog niet is gebeurd.
Configureer tijdens de initialisatie een unieke omgevingsnaam.

Tip

De omgevingsnaam wordt ook gebruikt als de naam van de doelresourcegroep. Voor deze quickstart kunt u overwegen .msdocs-cosmos-db
Implementeer het Azure Cosmos DB-account met behulp van azd up. De Bicep-sjablonen implementeren ook een voorbeeldwebtoepassing.
```
azd up
```
Selecteer tijdens het inrichtingsproces uw abonnement en gewenste locatie. Wacht tot het inrichtingsproces is voltooid. Het proces kan ongeveer vijf minuten duren.

Zodra het inrichten van uw Azure-resources is voltooid, wordt er een URL naar de actieve webtoepassing opgenomen in de uitvoer.

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.

Gebruik de URL in de console om naar uw webtoepassing in de browser te navigeren. Bekijk de uitvoer van de actieve app.

De clientbibliotheek installeren

Maak een requirements.txt bestand in uw app-map met de PyMongo - en python-dotenv-pakketten .
```
# requirements.txt
pymongo
python-dotenv
```

Maak een virtuele omgeving en installeer de pakketten.

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

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 van de Azure Cosmos DB-hiërarchie, waaronder accounts, databases, verzamelingen en documenten.

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.

Met de voorbeeldcode die in dit artikel wordt beschreven, wordt een database gemaakt met de naam adventureworks productseen 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

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
```
Haal de verbindingsgegevens op uit de omgevingsvariabele die is gedefinieerd in een .env-bestand .
```
load_dotenv()
CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")
```

Definieer constanten die u in de code gaat gebruiken.

DB_NAME = "adventureworks"
COLLECTION_NAME = "products"

Verbinding maken met 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

Gebruik de Remove-AzResourceGroup cmdlet om de resourcegroep te verwijderen.

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

Delen via