Share via

Erste Schritte mit Azure Cosmos DB for NoSQL unter Verwendung von Python

  • Artikel

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

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. Es gibt drei Methoden zum Herstellen einer Verbindung mit einem API für NoSQL-Konto mithilfe der CosmosClient-Klasse:

Verbinden Sie sich mit einem Endpunkt und Schlüssel

Der Konstruktor für CosmosClient hat zwei erforderliche Parameter:

Parameter Beispielwert BESCHREIBUNG
url Umgebungsvariable COSMOS_ENDPOINT API für NoSQL-Endpunkt, der für alle Anforderungen verwendet werden soll
credential Umgebungsvariable COSMOS_KEY Kontoschlüssel oder Ressourcentoken zur Verwendung bei der Authentifizierung

Rufen Sie Ihren Kontoendpunkt und -schlüssel ab

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

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

  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
)

  3. Rufen Sie den API für NoSQL-Endpunkt-URI für das Konto mithilfe des az cosmosdb show-Befehls ab.

    az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "documentEndpoint"

  4. Suchen Sie den PRIMÄRSCHLÜSSEL aus der Liste der Schlüssel für das Konto mit dem az-cosmosdb-keys-list-Befehl.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

  5. Aufzeichnen der Werte von URI und PRIMÄRSCHLÜSSEL. Sie werden diese Anmeldeinformationen zu einem späteren Zeitpunkt verwenden.

Um die Werte von URI und PRIMÄRSCHLÜSSEL in Ihrem Python-Code zu verwenden, speichern Sie sie in neuen Umgebungsvariablen auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird.

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Erstellen Sie CosmosClient mit Kontoendpunkt und Schlüssel

Erstellen Sie eine neue Instanz der CosmosClient-Klasse mit den Variablen und COSMOS_ENDPOINTCOSMOS_KEY Umgebungsvariablen als Parameter.

ENDPOINT = os.environ["COSMOS_ENDPOINT"]
KEY = os.environ["COSMOS_KEY"]

client = CosmosClient(url=ENDPOINT, credential=KEY)

Verbinden mit einer Verbindungszeichenfolge

Die CosmosClient-Klasse verfügt über eine Methode from_connection_string, mit der Sie eine Verbindung mit einem erforderlichen Parameter herstellen können:

Parameter Beispielwert BESCHREIBUNG
conn_str Umgebungsvariable COSMOS_CONNECTION_STRING Die Verbindungszeichenfolge für das API für NoSQL-Konto.
credential Umgebungsvariable COSMOS_KEY Ein optionaler alternativer Kontoschlüssel oder ein Ressourcentoken, der bzw. das anstelle der Vorgabe in der Verbindungszeichenfolge verwendet werden soll.

Rufen Sie Ihre Kontoverbindungszeichenfolge ab

  1. 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
)

  2. Suchen Sie mit dem Befehl az-cosmosdb-keys-list die PRIMÄRE VERBINDUNGSZEICHENFOLGE in der Liste der Verbindungszeichenfolgen für das Konto.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "connection-strings" \
    --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"

Um den Wert von PRIMÄRE VERBINDUNGSZEICHENFOLGE in Ihrem Python-Code zu verwenden, speichern Sie ihn in einer neuen Umgebungsvariablen auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird.

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

CosmosClient mit Verbindungszeichenfolge erstellen

Erstellen Sie eine neue Instanz der CosmosClient-Klasse mit der COSMOS_CONNECTION_STRINGUmgebungsvariablen als einzigem Parameter.

CONN_STR = os.environ["COSMOS_CONNECTION_STRING"]

client = CosmosClient.from_connection_string(conn_str=CONN_STR)

Verbinden mithilfe von Microsoft Identity Platform

Verwenden Sie einen Sicherheitsprinzipal, um mithilfe von Microsoft Identity Platform und Microsoft Entra ID eine Verbindung mit Ihrem API für NoSQL-Konto herzustellen. 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, mit dem eine Verbindung hergestellt werden soll, ab (siehe Abschnitt Verbinden Sie sich mit einem Endpunkt und Schlüssel oben), und legen Sie diesen als Umgebungsvariable COSMOS_ENDPOINT fest.

  • 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 von CosmosClient mit Standard-Implementierung von Anmeldeinformationen

Wenn Sie die Anwendung außerhalb von Azure bereitstellen möchten, können Sie ein OAuth-Token abrufen, indem Sie andere Klassen in der Azure.Identity-Clientbibliothek für Python verwenden. Auch diese anderen Klassen leiten sich von der TokenCredential-Klasse ab.

Für dieses Beispiel erstellen wir eine ClientSecretCredential-Instanz, indem wir Client- und Mandanten-IDs zusammen mit einem geheimen Clientschlüssel verwenden.

Gehen Sie in Ihrer app.py-Datei folgendermaßen vor:

  • Rufen Sie die Anmeldeinformationen aus Umgebungsvariablen für einen Dienstprinzipal ab. Sie können die Client-ID, die Mandanten-ID und den geheimen Clientschlüssel abrufen, wenn Sie eine Anwendung in Microsoft Entra ID registrieren. Weitere Informationen zum Registrieren von Microsoft Entra-Anwendungen finden Sie unter Registrieren einer Anwendung bei Microsoft Identity Platform.

  • Importieren Sie clientSecretCredential, und erstellen Sie eine Instanz mit den Umgebungsvariablen TENANT_ID, CLIENT_IDund CLIENT_SECRET als Parametern.

  • Erstellen Sie eine neue Instanz der CosmosClient-Klasse mit ENDPOINT und credential als Parametern.

from azure.identity import ClientSecretCredential

ENDPOINT = os.environ["COSMOS_ENDPOINT"]
TENANT_ID = os.environ["TENANT_ID"]
CLIENT_ID = os.environ["CLIENT_ID"]
CLIENT_SECRET = os.environ["CLIENT_SECRET"]

credential = ClientSecretCredential(
    tenant_id=TENANT_ID, client_id=CLIENT_ID, client_secret=CLIENT_SECRET
)

client = CosmosClient(ENDPOINT, credential)

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.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, containers, and items.

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

Weitere Informationen

Nächste Schritte

Nachdem Sie sich mit einem API für NoSQL-Konto verbunden haben, befolgen Sie zum Erstellen und Verwalten von Datenbanken die nächste Anleitung.

Erstellen einer Datenbank in Azure Cosmos DB for NoSQL mit Python