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

  • Artikel

GILT FÜR: MongoDB

Erste Schritte mit dem PyMongo-Paket zum Erstellen von Datenbanken, Sammlungen und Dokumenten in Ihrer Azure Cosmos DB-Ressource. Führen Sie die nachfolgenden Schritte aus, um das Paket zu installieren und den Beispielcode für grundlegende Aufgaben zu testen.

Hinweis

Die Beispielcodeausschnitte sind auf GitHub als Python-Projekt verfügbar.

In dieser Schnellstartanleitung kommunizieren Sie mit der API für MongoDB von Azure Cosmos DB über einen der Open-Source-MongoDB-Clienttreiber für Python namens PyMongo. Außerdem verwenden Sie die MongoDB-Erweiterungsbefehle, mit denen Sie Datenbankressourcen erstellen und abrufen können, die für das Azure Cosmos DB-Kapazitätsmodell spezifisch sind.

Voraussetzungen

Prüfen der Voraussetzungen

  • Führen Sie in einem Terminal- oder Befehlsfenster den Befehl python --version aus, um zu überprüfen, ob Sie über eine aktuelle Version von Python verfügen.
  • Führen Sie az --version (Azure CLI) oder Get-Module -ListAvailable Az* (Azure PowerShell) aus, um zu überprüfen, ob die geeigneten Azure-Befehlszeilentools installiert wurden.

Einrichten

In diesem Abschnitt werden Sie durch die Schritte zum Erstellen eines Azure Cosmos DB-Kontos und Einrichten eines Projekts geführt, bei dem das MongoDB-npm-Paket verwendet wird.

Erstellen eines Azure Cosmos DB-Kontos

In diesem Schnellstart wird ein einzelnes Azure Cosmos DB-Konto mithilfe der API für MongoDB erstellt.

  1. Erstellen Sie Shellvariablen für accountName, resourceGroupName und 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. Wenn Sie das noch nicht getan haben, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an.

  3. Erstellen Sie mit dem Befehl az group create eine neue Ressourcengruppe in Ihrem Abonnement.

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

  4. Erstellen Sie mit dem Befehl az cosmosdb create ein neues Azure Cosmos DB for MongoDB-Konto mit Standardeinstellungen.

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

Abrufen der MongoDB-Verbindungszeichenfolge

  1. Suchen Sie mit dem Befehl az cosmosdb keys list die Verbindungszeichenfolge der API für MongoDB in der Liste der Verbindungszeichenfolgen für das Konto.

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

  2. Zeichnen Sie die PRIMARY KEY-Werte (Primärschlüsselwerte) auf. Sie werden diese Anmeldeinformationen zu einem späteren Zeitpunkt verwenden.

Erstellen einer neuen Python-App

  1. Erstellen Sie mithilfe Ihres bevorzugten Terminals einen neuen leeren Ordner, und ändern Sie das Verzeichnis in den Ordner.

    Hinweis

    Wenn Sie nur den fertigen Code wünschen, laden Sie das Repository der Beispielcodeausschnitte mit dem vollständigen Beispiel herunter oder forken und klonen Sie es. Sie können auch git clone für das Repository in Azure Cloud Shell ausführen, um die in dieser Schnellstartanleitung gezeigten Schritte durchzuführen.

  2. Erstellen Sie eine Datei requirements.txt, in der die Pakete PyMongo und python-dotenv aufgelistet sind.

    # requirements.txt
pymongo
python-dotenv

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

    # 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

Konfigurieren von Umgebungsvariablen

Wenn Sie die Werte von CONNECTION STRING (Verbindungszeichenfolge) in Ihrem Code verwenden möchten, legen Sie diesen Wert in der lokalen Umgebung fest, in der die Anwendung ausgeführt wird. Verwenden Sie zum Festlegen der Umgebungsvariablen Ihr bevorzugtes Terminal, um die folgenden Befehle auszuführen:

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

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.

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

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

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 API für MongoDB von Azure Cosmos DB

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.

Verwenden Sie den Befehl az group delete zum Löschen der Ressourcengruppe.

az group delete --name $resourceGroupName