Erste Schritte mit Azure Cosmos DB for NoSQL unter Verwendung von Python
GILT FÜR: 
NoSQL
In diesem Artikel erfahren Sie, wie Sie mithilfe des Python SDK eine Verbindung mit Azure Cosmos DB for NoSQL herstellen. Sobald die Verbindung hergestellt ist, können Sie Vorgänge für Datenbanken, Container und Elemente ausführen.
Paket (PyPi) | Beispiele | API-Dokumentation | Bibliothekquellcode | Feedback einreichen
Voraussetzungen
- Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
- Azure Cosmos DB for NoSQL-Konto. Erstellen eines „API für NoSQL“-Kontos.
- Python 3.7 oder höher
- Azure-Befehlszeilenschnittstelle (CLI) oder Azure PowerShell
Einrichten des Projekts
Erstellen Sie eine Umgebung, in der Sie Python-Code ausführen können.
Mithilfe einer virtuellen Umgebung können Sie Python-Pakete in einer isolierten Umgebung installieren, ohne das übrige System zu beeinträchtigen.
Installieren Sie das Python SDK für Azure Cosmos DB for NoSQL in der virtuellen Umgebung.
pip install azure-cosmos
Erstellen der Python-Anwendung
Erstellen Sie in Ihrer Umgebung eine neue Datei app.py, und fügen Sie den folgenden Code hinzu:
import json
import os
import sys
import uuid
from azure.core.exceptions import AzureError
from azure.cosmos import CosmosClient, PartitionKey
Der oben stehende Code importiert Module, die Sie im weiteren Verlauf dieses Artikels verwenden.
Herstellen einer Verbindung mit Azure Cosmos DB for NoSQL
Um eine Verbindung mit der API für NoSQL von Azure Cosmos DB herzustellen, erstellen Sie eine Instanz der CosmosClient-Klasse. Diese Klasse ist der Ausgangspunkt, um alle Vorgänge für Datenbanken auszuführen.
Um eine Verbindung mit Ihrer API für das NoSQL-Konto mithilfe von Microsoft Entra herzustellen, verwenden Sie einen Sicherheitsprinzipal. Der genaue Prinzipaltyp hängt davon ab, wo Sie Ihren Anwendungscode hosten. Die folgende Tabelle dient als Kurzanleitung.
| Ausführungsort der Anwendung | Sicherheitsprinzipal |
|---|---|
| Lokaler Computer (Entwickeln und Testen) | Benutzeridentität oder Dienstprinzipal |
| Azure | Verwaltete Identität |
| Server oder Clients außerhalb von Azure | Dienstprinzipal |
Importieren Sie Azure.Identity
Das azure-identity-Paket enthält grundlegende Authentifizierungsfunktionen, die von allen Azure SDK-Bibliotheken gemeinsam genutzt werden.
Importieren Sie das azure-identity-Paket in Ihre Umgebung.
pip install azure-identity
Erstellen von CosmosClient mit Standard-Implementierung von Anmeldeinformationen
Wenn Sie auf einem lokalen Computer testen oder Ihre Anwendung auf Azure-Diensten mit direkter Unterstützung für verwaltete Identitäten ausgeführt wird, rufen Sie ein OAuth-Token ab, indem Sie eine DefaultAzureCredential-Instanz erstellen.
Gehen Sie in Ihrer app.py-Datei folgendermaßen vor:
Rufen Sie den Endpunkt ab, mit dem Sie Ihr Konto verbinden möchten, und legen Sie ihn Umgebungsvariable
COSMOS_ENDPOINTfest.Importieren Sie defaultAzureCredential, und erstellen Sie eine Instanz davon.
Erstellen Sie eine neue Instanz der CosmosClient-Klasse mit ENDPOINT und credential als Parametern.
from azure.identity import DefaultAzureCredential
ENDPOINT = os.environ["COSMOS_ENDPOINT"]
credential = DefaultAzureCredential()
client = CosmosClient(ENDPOINT, credential)
Wichtig
Ausführliche Informationen zum Hinzufügen der richtigen Rolle zum Aktivieren von DefaultAzureCredential finden Sie unter Konfigurieren der rollenbasierten Zugriffssteuerung mit Microsoft Entra ID für Ihr Azure Cosmos DB-Konto. Lesen Sie insbesondere den Abschnitt zum Erstellen von Rollen und zum Zuweisen dieser Rollen zu einer Prinzipal-ID.
Erstellen Ihrer Anwendung
Beim Erstellen Ihrer Anwendung interagiert Ihr Code hauptsächlich mit vier Arten von Ressourcen:
Das API für NoSQL-Konto, das der eindeutige Namespace der obersten Ebene für Ihre Azure Cosmos DB-Daten ist.
Datenbanken, die Container in Ihrem Konto organisieren.
Container, die eine Reihe einzelner Elemente in Ihrer Datenbank enthalten.
Elemente, die ein JSON-Dokument in Ihrem Container darstellen.
Im folgenden Diagramm ist die Beziehung zwischen diesen Ressourcen dargestellt.
Hierarchisches Diagramm mit einem Azure Cosmos DB-Konto oben. Das Konto verfügt über zwei untergeordnete Datenbankknoten. Einer der Datenbankknoten enthält zwei untergeordnete Containerknoten. Der andere Datenbankknoten enthält einen einzelnen untergeordneten Containerknoten. Dieser einzelne Containerknoten hat drei untergeordnete Elementknoten.
Jeder Ressourcentyp wird durch eine oder mehrere zugeordnete Python-Klassen dargestellt. Nachstehend finden Sie eine Liste der am häufigsten verwendeten Klassen für die synchrone Programmierung. (Es gibt ähnliche Klassen für die asynchrone Programmierung unter dem Namespace azure.cosmos.aio.)
| Klasse | BESCHREIBUNG |
|---|---|
CosmosClient |
Diese Klasse bietet eine clientseitige logische Darstellung für den Azure Cosmos DB-Dienst. Das Clientobjekt wird zum Konfigurieren und Ausführen von Anforderungen für den Dienst verwendet. |
DatabaseProxy |
Eine Schnittstelle zu einer Datenbank, die möglicherweise noch nicht im Dienst vorhanden ist. Diese Klasse sollte nicht direkt instanziiert werden. Stattdessen sollten Sie die CosmosClient-Methode get_database_client verwenden. |
ContainerProxy |
Eine Schnittstelle für die Interaktion mit einem bestimmten Cosmos DB-Container. Diese Klasse sollte nicht direkt instanziiert werden. Verwenden Sie stattdessen die DatabaseProxy-Methode get_container_client, um einen vorhandenen Container abzurufen, oder die Methode create_container, um einen neuen Container zu erstellen. |
In den folgenden Leitfäden wird gezeigt, wie Sie diese verschiedenen Klassen verwenden, um Ihre Anwendung zu erstellen.
| Handbuch | BESCHREIBUNG |
|---|---|
| Erstellen einer Datenbank | Erstellen von Datenbanken |
| Erstellen eines Containers | Erstellen von Containern. |
| Elementbeispiele | Punktlesevorgang eines bestimmten Elements |