Aanbevolen procedures voor Python SDK in Azure Cosmos DB for NoSQL

  • Van toepassing op: ✅ NoSQL

Deze handleiding bevat aanbevolen procedures voor oplossingen die zijn gebouwd met behulp van de nieuwste versie van de Python SDK voor Azure Cosmos DB voor NoSQL. De aanbevolen procedures die hier worden beschreven, helpen latentie te verbeteren, de beschikbaarheid te verbeteren en de algehele prestaties voor uw oplossingen te verbeteren.

Accountconfiguratie

Accountconfiguratieparameters

Parameter Standaard of beperking Wanneer gebruiken
Colocatie van regio Hetzelfde als de app-regio Latentie verminderen
Replicatie in meerdere regio's Standaard uitgeschakeld 2+ regio's inschakelen voor beschikbaarheid
Service-beheerde failover Optional Inschakelen voor productieworkloads 
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

Zie de zelfstudie over wereldwijde distributie voor meer informatie over het toevoegen van meerdere regio's met behulp van de Python SDK.

SDK-gebruik

SDK-gebruiksparameters

Parameter Standaard of beperking Wanneer gebruiken
SDK-versie Meest recente beschikbaar Altijd voor optimale prestaties
CosmosClient-exemplaar Eén per app Hergebruiken voor de levensduur van de app
voorkeurslocaties Geen Lees- en failover optimaliseren 
client = CosmosClient(
    url,
    credential,
    preferred_locations=["East US", "West US"]
)
print(client.client_connection._preferred_locations)
# Expected: ['East US', 'West US']

Een tijdelijke fout is een fout met een onderliggende oorzaak die zich snel oplost. Toepassingen die verbinding maken met uw database, moeten zo worden gebouwd dat ze deze tijdelijke fouten verwachten. Als u ze wilt afhandelen, implementeert u logica voor opnieuw proberen in uw code in plaats van ze als toepassingsfouten weer te geven aan gebruikers. De SDK heeft ingebouwde logica voor het afhandelen van deze tijdelijke fouten bij opnieuw te proberen aanvragen, zoals lees- of querybewerkingen. De SDK kan schrijfbewerkingen niet opnieuw proberen voor tijdelijke fouten, omdat schrijfbewerkingen niet idempotent zijn. Met de SDK kunnen gebruikers de logica voor het opnieuw proberen mechanismen configureren voor throttling-beperkingen. Zie de richtlijnen voor tolerante toepassingen voor meer informatie over welke fouten u opnieuw wilt proberen.

Gebruik SDK-logboekregistratie om diagnostische gegevens vast te leggen en latentieproblemen op te lossen.

Asynchrone client

Asynchrone clientvereisten

Requirement Standaard of beperking Wanneer gebruiken
Importpad azure.cosmos.aio.CosmosClient Gebruiken in asynchrone frameworks en gebeurtenislussen
aiohttp Afhankelijkheid Niet standaard geïnstalleerd Installeer expliciet: pip install aiohttp
Clientlevenscyclus Moet expliciet worden gesloten Gebruik async with of bel await client.close() 
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()

Wanneer asynchroon versus synchronisatie gebruiken

Scenario Aanbevolen client
Webframeworks (FastAPI, Kwart) azure.cosmos.aio.CosmosClient
Serverloos (Azure Functions asynchroon) azure.cosmos.aio.CosmosClient
Scripts en batchverwerkingen azure.cosmos.CosmosClient
Eenvoudige CLI-hulpprogramma's azure.cosmos.CosmosClient

Warning

Gebruik de synchronisatie CosmosClient niet binnen een asynchrone gebeurtenislus. De synchronisatieclient blokkeert I/O-aanroepen die de gebeurtenislus blokkeren, de prestaties verminderen en mogelijk impasses in uw toepassing veroorzaken.

Zie de sectie Python SDK README async voor meer informatie.

Gegevensontwerp

Parameters voor gegevensontwerp

Parameter Standaard of beperking Wanneer gebruiken
Documentgrootte N/A Houd het klein om RU-kosten te verlagen
Id-tekens Geen speciale tekens Onverwacht gedrag voorkomen
Indexeringspaden Alle paden geïndexeerd Ongebruikte paden uitsluiten voor snellere schrijfbewerkingen 
container_properties = {
    "id": "items",
    "indexingPolicy": {
        "excludedPaths": [{"path": "/*"}]
    }
}
print(container_properties["indexingPolicy"])
# Expected: excludedPaths configured

Zie indexen maken met behulp van het SDK-voorbeeld voor meer informatie.

Hostkenmerken

Parameters voor hostkenmerken

Parameter Standaard of beperking Wanneer gebruiken
CPU-gebruik <70% aanbevolen Omhoog of uitschalen indien hoog
Versneld netwerken Uitgeschakeld Inschakelen op de virtuele machines voor hoge verkeersdrukte
Grootte van query-pagina 100 items / 4 MB Verhogen om retouren te verminderen 
items = container.query_items(
    query="SELECT * FROM c",
    max_item_count=500
)
print("Page size set to 500")
# Expected: fewer round trips

Volgende stappen 

Zie Performance-tips voor Azure Cosmos DB Python SDK voor meer informatie over prestatietips voor Python SDK.

Zie Partitioneren en schalen in Azure Cosmos DB voor meer informatie over het ontwerpen van uw toepassing voor schaalaanpassing en hoge prestaties.

Wilt u capaciteitsplanning uitvoeren voor een migratie naar Azure Cosmos DB? U kunt informatie over uw bestaande databasecluster gebruiken voor capaciteitsplanning.

  • Last updated on