Schnellstart: Azure Cosmos DB for MongoDB für Python mit MongoDB-Treiber

GILT FÜR: MongoDB

Erste Schritte mit MongoDB zum Erstellen von Datenbanken, Sammlungen und Dokumenten in Ihrer Azure Cosmos DB-Ressource. Führen Sie die folgenden Schritte aus, um mithilfe von Azure Developer CLI eine minimale Lösung für Ihre Umgebung bereitzustellen.

Referenzdokumentation für die API für MongoDB | pymongo-Paket | Azure Developer CLI

Voraussetzungen

Einrichten

Stellen Sie den Entwicklungscontainer dieses Projekts in Ihrer Umgebung bereit. Verwenden Sie dann das Azure Developer CLI (azd), um ein Azure Cosmos DB for MongoDB-Konto zu erstellen und eine containerisierte Beispielanwendung bereitzustellen. Die Beispielanwendung verwendet die Clientbibliothek zum Verwalten, Erstellen, Lesen und Abfragen von Beispieldaten.

1. Öffnen Sie ein Terminal im Stammverzeichnis des Projekts.

2. Authentifizieren Sie sich mithilfe von azd auth login bei Azure Developer CLI. Führen Sie die vom Tool angegebenen Schritte aus, um sich mit Ihren bevorzugten Azure-Anmeldeinformationen bei der CLI zu authentifizieren.

   azd auth login
   

3. Verwenden Sie azd init, um das Projekt zu initialisieren.

   azd init --template cosmos-db-mongodb-python-quickstart
   

   Hinweis

   Diese Schnellstartanleitung verwendet das GitHub-Vorlagenrepository azure-samples/cosmos-db-mongodb-python-quickstart. Die Azure Developer CLI klont dieses Projekt automatisch auf Ihrem Computer, wenn es noch nicht vorhanden ist.

4. Konfigurieren Sie während der Initialisierung einen eindeutigen Umgebungsnamen.

   Tipp

   Der Umgebungsname wird auch als Name der Zielressourcengruppe verwendet. Ziehen Sie für diese Schnellstartanleitung die Verwendung von msdocs-cosmos-db in Betracht.

5. Stellen Sie das Azure Cosmos DB-Konto mit azd up bereit. Die Bicep-Vorlagen stellen auch eine Beispielwebanwendung bereit.

   azd up
   

6. Wählen Sie während des Bereitstellungsprozesses Ihr Abonnement und den gewünschten Standort aus. Warten Sie auf den Abschluss des Bereitstellungsvorgangs. Dieser Prozess kann ca. fünf Minuten dauern.

7. Sobald die Bereitstellung Ihrer Azure-Ressourcen abgeschlossen ist, enthält die Ausgabe eine URL zur ausgeführten Webanwendung.

   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.
   

8. Verwenden Sie die URL in der Konsole, um im Browser zu Ihrer Webanwendung zu navigieren. Sehen Sie sich die Ausgabe der ausgeführten App an.

   

Installieren der Clientbibliothek

1. Erstellen Sie in Ihrem App-Verzeichnis eine requirements.txt-Datei, in der die Pakete PyMongo und python-dotenv aufgelistet werden.

   # requirements.txt
   pymongo
   python-dotenv
   

2. Erstellen Sie eine virtuelle Umgebung, und installieren Sie die Pakete.

   • 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
   

Objektmodell

Befassen wir uns nun mit der Hierarchie der Ressourcen in der API für MongoDB und dem Objektmodell, das verwendet wird, um diese Ressourcen zu erstellen und darauf zuzugreifen. Azure Cosmos DB erstellt Ressourcen in einer Hierarchie, die aus Konten, Datenbanken, Sammlungen und Dokumenten besteht.

Jeder Ressourcentyp wird durch eine Python-Klasse dargestellt. Hier sind die häufigsten Klassen aufgeführt:

• MongoClient: Der erste Schritt beim Arbeiten mit PyMongo besteht darin, einen MongoClient zu erstellen, um eine Verbindung mit der API für MongoDB von Azure Cosmos DB herzustellen. Das Clientobjekt wird zum Konfigurieren und Ausführen von Anforderungen für den Dienst verwendet.

• Datenbank: Die API für MongoDB von Azure Cosmos DB kann eine oder mehrere unabhängige Datenbanken unterstützen.

• Sammlung: Eine Datenbank kann eine oder mehrere Sammlungen enthalten. Eine Sammlung ist eine Gruppe von Dokumenten, die in MongoDB gespeichert sind, und ähnelt ungefähr einer Tabelle in einer relationalen Datenbank.

• Dokument: Ein Dokument ist eine Gruppe von Schlüssel-Wert-Paaren. Dokumente weisen ein dynamisches Schema auf. Ein dynamisches Schema bedeutet, dass Dokumente in derselben Sammlung nicht über denselben Satz von Feldern oder dieselbe Struktur verfügen müssen. Außerdem können allgemeine Felder in den Dokumenten einer Sammlung verschiedene Arten von Daten enthalten.

Weitere Informationen zur Hierarchie von Entitäten finden Sie im Artikel Azure Cosmos DB-Ressourcenmodell.

Codebeispiele

• Authentifizieren des Clients
• Abrufen der Datenbank
• Abrufen der Sammlung
• Erstellen eines Index
• Erstellen eines Dokuments
• Abrufen eines Dokuments
• Abfragedokumente

Der in diesem Artikel beschriebene Beispielcode erstellt die Datenbank adventureworks mit der Sammlung products. Die Sammlung products soll Produktdetails wie Name (name), Kategorie (category), Menge (quantity) und einen Verkaufsindikator (sale) enthalten. Jedes Produkt enthält außerdem einen eindeutigen Bezeichner. Der vollständige Beispielcode befindet sich unter https://github.com/Azure-Samples/azure-cosmos-db-mongodb-python-getting-started/tree/main/001-quickstart/.

Für die folgenden Schritte verwendet die Datenbank kein Sharding und zeigt eine synchrone Anwendung mit dem PyMongo-Treiber an. Verwenden Sie für asynchrone Anwendungen den Motor-Treiber.

Authentifizieren des Clients

1. Erstellen Sie im Projektverzeichnis eine Datei run.py. Fügen Sie in Ihrem Editor require-Anweisungen hinzu, um auf von Ihnen verwendete Pakete zu verweisen, einschließlich der Pakete PyMongo und python-dotenv.

   import os
   import sys
   from random import randint
   
   import pymongo
   from dotenv import load_dotenv
   

2. Rufen Sie die Verbindungsinformationen aus der Umgebungsvariable ab, die in einer .env-Datei definiert ist.

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

3. Definieren Sie Konstanten, die Sie im Code verwenden.

   DB_NAME = "adventureworks"
   COLLECTION_NAME = "products"
   

Herstellen einer Verbindung mit der Azure Cosmos DB-API für MongoDB

Verwenden Sie das MongoClient-Objekt zum Herstellen einer Verbindung mit Ihrer Azure Cosmos DB for MongoDB-Ressource. Diese Methode gibt einen Verweis auf die Datenbank zurück.

client = pymongo.MongoClient(CONNECTION_STRING)

Abrufen der Datenbank

Überprüfen Sie mit der Methode list_database_names, ob die Datenbank vorhanden ist. Wenn die Datenbank nicht vorhanden ist, verwenden Sie den Erweiterungsbefehl „CreateDatabase“, um sie mit einem festgelegten bereitgestellten Durchsatz zu erstellen.

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

Abrufen der Sammlung

Überprüfen Sie mit der Methode list_collection_names, ob die Sammlung vorhanden ist. Wenn die Sammlung nicht vorhanden ist, verwenden Sie den Erweiterungsbefehl „CreateCollection“, um sie zu erstellen.

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

Erstellen eines Index

Erstellen Sie einen Index mit dem Erweiterungsbefehl „UpdateCollection“. Sie können den Index auch im Erweiterungsbefehl „CreateCollection“ festlegen. Legen Sie den Index in diesem Beispiel auf die name-Eigenschaft fest, damit Sie später mit der Methode sort der cursor-Klasse nach Produktname sortieren können.

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

Erstellen eines Dokuments

Erstellen Sie ein Dokument mit den product-Eigenschaften für die adventureworks-Datenbank:

• Eine category-Eigenschaft. Sie kann als logischer Partitionsschlüssel verwendet werden.
• Eine name-Eigenschaft.
• Eine quantity-Bestandseigenschaft.
• Eine sale-Eigenschaft, die angibt, ob das Produkt verkauft wird.

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

Erstellen Sie ein Dokument in der Sammlung, indem Sie den Vorgang update_one auf Sammlungsebene aufrufen. In diesem Beispiel führen Sie ein Upsert für ein Dokument aus, anstatt ein neues Dokument zu erstellen. Ein Upsert ist in diesem Beispiel nicht erforderlich, da der Produktname zufällig ist. Es empfiehlt sich jedoch ein Upsert, falls Sie den Code mehrmals ausführen und der Produktname identisch ist.

Das Ergebnis des Vorgangs update_one enthält den _id-Feldwert, den Sie in nachfolgenden Vorgängen verwenden können. Die _id-Eigenschaft wurde automatisch erstellt.

Abrufen eines Dokuments

Verwenden Sie die find_one-Methode zum Abrufen eines Dokuments.

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

In Azure Cosmos DB können Sie einen kostengünstigeren Punktlesevorgang durchführen, indem Sie sowohl den eindeutigen Bezeichner (_id) als auch den Partitionsschlüssel verwenden.

Abfragedokumente

Nachdem Sie ein Dokument eingefügt haben, können Sie eine Abfrage zum Abrufen aller Dokumente ausführen, die einem bestimmten Filter entsprechen. In diesem Beispiel werden alle Dokumente gesucht, die einer bestimmten Kategorie entsprechen: gear-surf-surfboards. Sobald die Abfrage definiert wurde, rufen Sie Collection.find auf, um ein Cursor-Ergebnis zu erhalten. Anschließend verwenden Sie sort.

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

Problembehandlung:

• Vergewissern Sie sich bei Anzeige einer Fehlermeldung wie The index path corresponding to the specified order-by item is excluded., dass der Index erstellt wurde.

Ausführen des Codes

Diese App erstellt eine API für MongoDB-Datenbank und -Sammlung sowie ein Dokument und zeigt dann das betreffende Dokument an. Schließlich gibt das Beispiel eine Abfrage aus, die Dokumente zurückgibt, die einer angegebenen Produktkategorie entsprechen. In jedem Schritt gibt das Beispiel Informationen über die ausgeführten Schritte an die Konsole aus.

Verwenden Sie zur Ausführung der App ein Terminal, um zum Anwendungsverzeichnis zu navigieren und die Anwendung auszuführen.

python run.py

Die Ausgabe der App sollte ähnlich wie dieses Beispiel aussehen:

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}

Bereinigen von Ressourcen

Wenn Sie das Azure Cosmos DB for NoSQL-Konto nicht mehr benötigen, können Sie die entsprechende Ressourcengruppe löschen.

az group delete --name $resourceGroupName

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