Bewährte Methoden für Python SDK in Azure Cosmos DB für NoSQL

  • Gilt für:: ✅ NoSQL

Dieses Handbuch enthält bewährte Methoden für Lösungen, die mit der neuesten Version des Python SDK für Azure Cosmos DB für NoSQL erstellt wurden. Die hier enthaltenen bewährten Methoden tragen dazu bei, die Latenz zu verbessern, die Verfügbarkeit zu verbessern und die Gesamtleistung für Ihre Lösungen zu steigern.

Kontokonfiguration

Kontokonfigurationsparameter

Parameter Standard oder Einschränkung Wann verwenden?
Co-Location der Region Identisch mit app-Region Verringern der Latenz
Replikation mit mehreren Regionen Standardmäßig deaktiviert Aktivieren von 2+ Regionen für die Verfügbarkeit
Dienstseitig verwaltetes Failover Fakultativ Für Produktionsworkloads aktivieren 
from azure.cosmos import CosmosClient
client = CosmosClient(url, credential)
print(client.client_connection._global_endpoint_manager.write_endpoint)
# Expected: write endpoint resolves to configured write region

Weitere Informationen zum Hinzufügen mehrerer Regionen mithilfe des Python SDK finden Sie im Lernprogramm global distribution.

SDK-Verwendung

SDK-Verwendungsparameter

Parameter Standard oder Einschränkung Wann verwenden?
SDK-Version Neueste verfügbar Immer für optimale Leistung
CosmosClient-Instanz Eine pro App Wiederverwenden über die gesamte Lebensdauer der App
bevorzugte_Standorte Nichts Leseoperationen und Failover optimieren 
client = CosmosClient(
    url,
    credential,
    preferred_locations=["East US", "West US"]
)
print(client.client_connection._preferred_locations)
# Expected: ['East US', 'West US']

Ein vorübergehender Fehler ist ein Fehler, dessen Ursache sich innerhalb kurzer Zeit von selbst auflöst. Anwendungen, die eine Verbindung mit der Datenbank herstellen, sollten dafür ausgelegt sein, vorübergehende Fehler zu tolerieren. Behandeln Sie diese Fehler, indem Sie Wiederholungslogik in Ihrem Code implementieren und vermeiden, dass die Fehler Benutzern als Anwendungsfehler gemeldet werden. Das SDK verfügt über integrierte Logik, um diese vorübergehenden Fehler bei wiederholbaren Anforderungen wie Lese- oder Abfragevorgängen zu behandeln. Das SDK kann keine Schreibvorgänge für vorübergehende Fehler wiederholen, da Schreibvorgänge nicht idempotent sind. Benutzer können jedoch Wiederholungslogik für Drosselungen konfigurieren. Ausführliche Informationen dazu, bei welchen Fehlern ein erneuter Versuch durchgeführt werden soll, finden Sie in den Leitlinien für widerstandsfähige Anwendungen.

Verwenden Sie die SDK-Protokollierung, um Diagnoseinformationen zu erfassen und Latenzprobleme zu beheben.

Asynchroner Client

Asynchrone Clientanforderungen

Anforderung Standard oder Einschränkung Wann verwenden?
Importpfad azure.cosmos.aio.CosmosClient Verwendung in asynchronen Frameworks und Ereignisschleifen
aiohttp Abhängigkeit Standardmäßig nicht installiert Explizit installieren: pip install aiohttp
Clientlebenszyklus Muss explizit geschlossen werden Verwenden Sie async with oder rufen Sie await client.close() auf. 
from azure.cosmos.aio import CosmosClient

# Preferred: use async with to manage lifecycle automatically
async with CosmosClient(url, credential) as client:
    database = client.get_database_client("mydb")
    container = database.get_container_client("mycontainer")
    item = await container.read_item(item="id1", partition_key="pk1")

# Alternative: manage lifecycle manually
client = CosmosClient(url, credential)
try:
    database = client.get_database_client("mydb")
    container = database.get_container_client("mycontainer")
    item = await container.read_item(item="id1", partition_key="pk1")
finally:
    await client.close()

Wann sollte asynchron vs. synchron verwendet werden?

Scenario Empfohlener Client
Webframeworks (FastAPI, Quart) azure.cosmos.aio.CosmosClient
Serverless (asynchrone Azure Functions) azure.cosmos.aio.CosmosClient
Skripts und Batchaufträge azure.cosmos.CosmosClient
Einfache CLI-Tools azure.cosmos.CosmosClient

Warning

Verwenden Sie die Synchronisierung CosmosClient nicht in einer asynchronen Ereignisschleife. Der Synchronisierungsclient führt blockierende E/A-Aufrufe durch, die die Ereignisschleife blockieren, die Leistung beeinträchtigen und potenziell Deadlocks in Ihrer Anwendung verursachen.

Weitere Informationen finden Sie im Abschnitt Python SDK README async.

Datenentwurf

Datenentwurfsparameter

Parameter Standard oder Einschränkung Wann verwenden?
Dokumentgröße N/A Halten Sie klein, um die RU-Kosten zu reduzieren
Bezeichnerzeichen Keine Sonderzeichen Unerwartetes Verhalten vermeiden
Indizierungspfade Alle Pfade wurden indiziert Nicht verwendete Pfade für schnellere Schreibvorgänge ausschließen 
container_properties = {
    "id": "items",
    "indexingPolicy": {
        "excludedPaths": [{"path": "/*"}]
    }
}
print(container_properties["indexingPolicy"])
# Expected: excludedPaths configured

Weitere Informationen finden Sie unter Erstellen von Indizes mithilfe des SDK-Beispiels.

Hostmerkmale

Parameter der Hostmerkmale

Parameter Standard oder Einschränkung Wann verwenden?
CPU-Auslastung <70% empfohlen Hochskalieren oder nach außen skalieren, wenn die Nachfrage hoch ist.
Beschleunigter Netzwerkbetrieb Deaktiviert Aktivieren von virtuellen Computern für hohen Datenverkehr
Seitengröße der Abfrage 100 Artikel / 4 MB Erhöhen, um Roundtrips zu reduzieren 
items = container.query_items(
    query="SELECT * FROM c",
    max_item_count=500
)
print("Page size set to 500")
# Expected: fewer round trips

Nächste Schritte

Weitere Informationen zu Leistungstipps für Python SDK finden Sie in Performance-Tipps für Azure Cosmos DB Python SDK.

Weitere Informationen zum Entwerfen einer auf Skalierung und hohe Leistung ausgelegten Anwendung finden Sie unter Partitionieren und Skalieren in Azure Cosmos DB.

Versuchen Sie, die Kapazitätsplanung für eine Migration zu Azure Cosmos DB durchzuführen? Sie können Informationen zu Ihrem vorhandenen Datenbankcluster für die Kapazitätsplanung verwenden.

  • Last updated on