Erste Schritte mit Azure Cosmos DB for MongoDB und Python

GILT FÜR: MongoDB

In diesem Artikel wird gezeigt, wie Sie mithilfe des PyMongo-Treiberpakets eine Verbindung mit Azure Cosmos DB for MongoDB herstellen. Sobald die Verbindung hergestellt ist, können Sie Vorgänge für Datenbanken, Sammlungen und Dokumente ausführen.

Hinweis

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

In diesem Artikel wird gezeigt, wie Sie mit der API für MongoDB von Azure Cosmos DB über einen der Open-Source-MongoDB-Clienttreiber für Python namens PyMongo kommunizieren.

Voraussetzungen

• Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
• Ab Python 3.8
• Azure-Befehlszeilenschnittstelle (CLI) oder Azure PowerShell
• Azure Cosmos DB for MongoDB-Ressource

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. Das Paket dotenv wird verwendet, um die Umgebungsvariablen während der lokalen Entwicklung aus einer .env-Datei zu lesen.

   # requirements.txt
   pymongo
   python-dotenv
   

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

   Windows

   # 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
   

   Linux/macOS

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

Herstellen einer Verbindung mit Azure Cosmos DB for MongoDB mithilfe des PyMongo-Treibers

Um eine Verbindung mit Azure Cosmos DB mithilfe des PyMongo-Treibers herzustellen, erstellen Sie eine Instanz des MongoClient-Objekts. Diese Klasse ist der Ausgangspunkt, um alle Vorgänge für Datenbanken auszuführen.

Der häufigste Konstruktor für MongoClient erfordert nur den Parameter host, der in diesem Artikel auf die Umgebungsvariable COSMOS_CONNECTION_STRING festgelegt ist. Es gibt weitere optionale Parameter und Schlüsselwortparameter, die Sie im Konstruktor verwenden können. Viele der optionalen Parameter können auch mit dem host-Parameter angegeben werden. Wenn dieselbe Option mit host und als Parameter übergeben wird, hat der Parameter Vorrang.

Weitere Informationen zu Verbindungsproblemen finden Sie im Handbuch zur Problembehandlung.

Ressourcennamen abrufen

In den folgenden Befehlen wird msdocs-cosmos als Ressourcengruppenname angezeigt. Ändern Sie den Namen entsprechend Ihrer Situation.

Azure-Befehlszeilenschnittstelle

1. Erstellen Sie eine Shell-Variable für resourceGroupName.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos"
   

2. Verwenden Sie den Befehlaz cosmosdb list, um den Namen des ersten Azure Cosmos DB-Kontos in Ihrer Ressourcengruppe abzurufen und in der Shell-Variable accountName zu speichern.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

PowerShell

1. Erstellen Sie eine Shell-Variable für RESOURCE_GROUP_NAME.

   # Variable for resource group name
   $RESOURCE_GROUP_NAME = "msdocs-cosmos"
   

2. Verwenden Sie das Cmdlet Get-AzCosmosDBAccountKey, um den Namen des ersten Azure Cosmos DB-Kontos in Ihrer Ressourcengruppe abzurufen und in der Shellvariable accountName zu speichern.

   # Get the name of the first Azure Cosmos DB account in your resource group
   $ACCOUNT_NAME = (Get-AzCosmosDBAccount -ResourceGroupName $RESOURCE_GROUP_NAME)[0].Name
   

Portal

Überspringen Sie diesen Schritt, und verwenden Sie die Informationen für das Portal im nächsten Schritt.

Abrufen der Verbindungszeichenfolge

Azure-Befehlszeilenschnittstelle

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.

PowerShell

1. Suchen Sie mit dem Cmdlet Get-AzCosmosDBAccountKey die CONNECTION STRING (Verbindungszeichenfolge) in der Liste der Schlüssel und Verbindungszeichenfolgen für das Konto.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary MongoDB Connection String"    
   

2. Zeichnen Sie den Wert für CONNECTION STRING auf. Sie werden diese Anmeldeinformationen zu einem späteren Zeitpunkt verwenden.

Portal

1. Melden Sie sich beim Azure-Portal an.

2. Navigieren Sie zur Seite des vorhandenen Azure Cosmos DB for MongoDB-Kontos.

3. Wählen Sie auf der Seite für das Azure Cosmos DB for MongoDB-Konto im Navigationsmenü die Option Verbindungszeichenfolge aus.

4. Zeichnen Sie den Wert für das Feld PRIMARY CONNECTION STRING (Primäre Verbindungszeichenfolge) auf. Sie verwenden diesen Wert in einem späteren Schritt.

   

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:

Windows

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

Linux/macOS

export COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

.env

Eine .env-Datei ist eine Standardmöglichkeit zum Speichern von Umgebungsvariablen in einem Projekt. Erstellen Sie eine .env-Datei im Stammverzeichnis Ihres Projekts. Fügen Sie der Datei .env die folgenden Zeilen hinzu:

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

MongoClient mit Verbindungszeichenfolge erstellen

1. Fügen Sie Abhängigkeiten hinzu, um auf die Pakete PyMongo und python-dotenv zu verweisen.

   import os
   import sys
   
   import pymongo
   from dotenv import load_dotenv
   

2. Definieren Sie eine neue Instanz der MongoClient-Klasse mit dem Konstruktor und der aus einer Umgebungsvariablen gelesenen Verbindungszeichenfolge.

   load_dotenv()
   CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")
   client = pymongo.MongoClient(CONNECTION_STRING)
   
   for prop, value in vars(client.options).items():
       print("Property: {}: Value: {} ".format(prop, value))
   

Weitere Informationen zu verschiedenen Möglichkeiten zum Erstellen einer MongoClient-Instanz finden Sie unter Erste Schritte mit Azure Cosmos DB for MongoDB und Python.

MongoClient-Verbindung schließen

Denken Sie daran, die Verbindung zu schließen, wenn die Anwendung die Verbindung nicht mehr benötigt. Der betreffende .close()-Aufruf sollte erfolgen, nachdem alle Datenbankaufrufe ausgeführt wurden.

client.close()

Verwenden von MongoDB-Clientklassen mit Azure Cosmos DB für die API für MongoDB

Bevor Sie mit dem Erstellen der Anwendung beginnen, sehen Sie sich die Hierarchie von Ressourcen in Azure Cosmos DB an. Bei Azure Cosmos DB gibt es ein spezifisches Objektmodell, das zum Erstellen von und Zugreifen auf Ressourcen verwendet wird. Azure Cosmos DB erstellt Ressourcen in einer Hierarchie, die aus Konten, Datenbanken, Sammlungen und Dokumenten besteht.

Hierarchisches Diagramm mit einem Azure Cosmos DB-Konto oben. Das Konto verfügt über zwei untergeordnete Datenbankknoten. Einer der Datenbankknoten enthält zwei untergeordnete Sammlungsknoten. Der andere Datenbankknoten enthält einen einzelnen untergeordneten Sammlungsknoten. Dieser einzelne Sammlungsknoten verfügt über drei untergeordnete Dokumentknoten.

Jeder Ressourcentyp wird durch eine oder mehrere zugeordnete Python-Klassen dargestellt. Nachstehend finden Sie eine Liste der gängigsten Klassen:

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

Siehe auch

• PyPI-Paket
• API-Referenz

Nächste Schritte

Nachdem Sie nun eine Verbindung mit einem API für MongoDB-Konto hergestellt haben, befolgen Sie die nächste Anleitung zum Erstellen und Verwalten von Datenbanken.

Verwalten einer MongoDB-Datenbank mithilfe von Python