Procedure consigliate per Python SDK in Azure Cosmos DB per NoSQL

  • Si applica a: ✅ NoSQL

Questa guida include le procedure consigliate per le soluzioni create usando la versione più recente di Python SDK per Azure Cosmos DB per NoSQL. Le procedure consigliate incluse qui consentono di migliorare la latenza, migliorare la disponibilità e migliorare le prestazioni complessive per le soluzioni.

Configurazione dell'account

Parametri di configurazione dell'account

Parametro Predefinito o vincolo Quando utilizzare
Colocation della regione Uguale all'area dell'app Ridurre la latenza
Replica in più aree Disattivato per impostazione predefinita Abilitare 2+ regioni per la disponibilità
Failover gestito dal servizio Facoltativo Abilitare per i carichi di lavoro di produzione 
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

Per altre informazioni su come aggiungere più aree usando Python SDK, vedere l'esercitazione sulla distribuzione globale.

Uso dell'SDK

Parametri di utilizzo dell'SDK

Parametro Predefinito o vincolo Quando utilizzare
Versione dell'SDK Ultima versione disponibile Sempre per ottenere prestazioni ottimali
Istanza di CosmosClient Uno per app Riutilizzare per tutta la durata dell'app
ubicazioni_preferite None Ottimizzare gli accessi di lettura e il sistema di failover. 
client = CosmosClient(
    url,
    credential,
    preferred_locations=["East US", "West US"]
)
print(client.client_connection._preferred_locations)
# Expected: ['East US', 'West US']

Un errore temporaneo è un errore che ha una causa sottostante che si risolve presto da sola. Le applicazioni che si connettono al database devono essere sviluppate in modo da prevedere tali errori temporanei. Per gestirli, implementare la logica di ripetizione dei tentativi nel codice invece di mostrarli agli utenti come errori dell'applicazione. L'SDK ha una logica predefinita per gestire questi errori temporanei nelle richieste ripetibili, come le operazioni di lettura o query. L'SDK non può riprovare a scrivere per errori temporanei perché le scritture non sono idempotenti. L'SDK consente agli utenti di configurare la logica di ripetizione dei tentativi per le limitazioni. Per informazioni dettagliate sugli errori da riprovare, vedere indicazioni sulle applicazioni resilienti.

Usare la registrazione dell'SDK per acquisire informazioni di diagnostica e risolvere i problemi di latenza.

Client asincrono

Requisiti del client asincrono

Requisito Predefinito o vincolo Quando utilizzare
Percorso di importazione azure.cosmos.aio.CosmosClient Uso nei framework asincroni e loop di eventi
aiohttp Dipendenza Non installato per impostazione predefinita Installare in modo esplicito: pip install aiohttp
Ciclo di vita del client Deve essere chiuso in modo esplicito Usare async with o chiamare 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()

Quando usare asincrono vs sincrono

Scenario Client consigliato
Framework per il Web (FastAPI, Quart) azure.cosmos.aio.CosmosClient
Serverless (Funzioni di Azure asincrono) azure.cosmos.aio.CosmosClient
Script e processi batch azure.cosmos.CosmosClient
Strumenti CLI semplici azure.cosmos.CosmosClient

Avvertimento

Non usare la sincronizzazione CosmosClient all'interno di un ciclo di eventi asincrono. Il client di sincronizzazione effettua chiamate di I/O bloccanti che bloccano il ciclo di eventi, degradando le prestazioni e causando potenzialmente deadlock nell'applicazione.

Per altre informazioni, vedere la sezione Python SDK README asincrona.

Progettazione dei dati

Parametri di progettazione dei dati

Parametro Predefinito o vincolo Quando utilizzare
Dimensioni del documento N/A Mantenere piccole dimensioni per ridurre i costi delle UR
Caratteri di identificazione Nessun carattere speciale Evitare comportamenti imprevisti
Percorsi di indicizzazione Tutti i percorsi indicizzati Escludere percorsi inutilizzati per scritture più veloci 
container_properties = {
    "id": "items",
    "indexingPolicy": {
        "excludedPaths": [{"path": "/*"}]
    }
}
print(container_properties["indexingPolicy"])
# Expected: excludedPaths configured

Per altre informazioni, vedere Creazione di indici con l'esempio SDK.

Caratteristiche dell'host

Parametri delle caratteristiche dell'host

Parametro Predefinito o vincolo Quando utilizzare
utilizzo della CPU <70% consigliato Aumentare le risorse o aumentare la scalabilità se la domanda è elevata
Rete accelerata Disattivato Abilitare sulle macchine virtuali per un traffico elevato
Dimensione della pagina di query 100 elementi / 4 MB Aumentare per ridurre i round trip 
items = container.query_items(
    query="SELECT * FROM c",
    max_item_count=500
)
print("Page size set to 500")
# Expected: fewer round trips

Passaggi successivi

Per altre informazioni sui suggerimenti sulle prestazioni per Python SDK, vedere Suggerimenti sulle prestazioni per Azure Cosmos DB Python SDK.

Per altre informazioni sulla progettazione dell'applicazione per scalabilità e prestazioni elevate, vedere Partizionamento e scalabilità in Azure Cosmos DB.

Si sta tentando di pianificare la capacità per una migrazione ad Azure Cosmos DB? È possibile usare le informazioni del cluster di database esistente per la pianificazione della capacità.

  • Last updated on