Freigeben über

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 Wahlfrei 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?

Szenario 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

Warnung

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 Vertikales hoch- oder runterskalieren, wenn hoch
Beschleunigter Netzwerkbetrieb Disabled 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 Ihrer Anwendung für Skalierung und hohe Leistung finden Sie unter Partitioning und Skalierung in Azure Cosmos DB.

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

  • Last updated on