NoSQL için Azure Cosmos DB'de Python SDK'sı için en iyi yöntemler

  • Şunlara uygulanır: ✅ NoSQL

Bu kılavuz, NoSQL için Azure Cosmos DB için Python SDK'sının en son sürümü kullanılarak oluşturulan çözümlere yönelik en iyi yöntemleri içerir. Burada yer alan en iyi yöntemler gecikme süresini iyileştirmeye, kullanılabilirliği iyileştirmeye ve çözümleriniz için genel performansı artırmaya yardımcı olur.

Hesap yapılandırması

Hesap yapılandırma parametreleri

Parametre Varsayılan veya kısıtlama Ne zaman kullanılır?
Bölge veri merkezi yerleştirme Uygulama bölgesiyle aynı Gecikme süresini azaltma
Çok bölgeli çoğaltma Varsayılan olarak devre dışı Kullanılabilirlik için 2'den fazla bölgeyi etkinleştirme
Hizmet tarafından yönetilen yük devretme Optional Üretim iş yükleri için etkinleştirme 
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

Python SDK'sını kullanarak birden çok bölge ekleme hakkında daha fazla bilgi için genel dağıtım öğreticisine bakın.

SDK kullanımı

SDK kullanım parametreleri

Parametre Varsayılan veya kısıtlama Ne zaman kullanılır?
SDK sürümü En son mevcut Her zaman en iyi performans için
CosmosClient örneği Uygulama başına bir tane Uygulama ömrü boyunca yeniden kullanma
tercih edilen konumlar Hiçbiri Okuma ve yük devretme işlemlerini optimize etme 
client = CosmosClient(
    url,
    credential,
    preferred_locations=["East US", "West US"]
)
print(client.client_connection._preferred_locations)
# Expected: ['East US', 'West US']

Geçici hata, kısa süre içinde kendisini çözen temel bir nedeni olan bir hatadır. Veritabanınıza bağlanan uygulamalar bu geçici hataları bekleyecek şekilde oluşturulmalıdır. Bunları işlemek için, bunları kullanıcılara uygulama hatası olarak eklemek yerine kodunuzda yeniden deneme mantığını uygulayın. SDK'nın, okuma veya sorgu işlemleri gibi yeniden denenebilir isteklerde bu geçici hataları işlemek için yerleşik mantığı vardır. SDK, yazma işlemleri idempotent olmadığı için geçici yazma hatalarında yeniden deneme yapamaz. SDK, kullanıcıların hız sınırlamaları için yeniden deneme mantığını yapılandırmasına olanak tanır. Hangi hataların yeniden denendiği hakkında ayrıntılı bilgi için bkz. dayanıklı uygulama kılavuzu.

Tanılama bilgilerini yakalamak ve gecikme sorunlarını gidermek için SDK günlüğünü kullanın.

Asenkron istemci

Asenkron istemci gereksinimleri

Gereksinim Varsayılan veya kısıtlama Ne zaman kullanılır?
İçeri aktarma yolu azure.cosmos.aio.CosmosClient Asenkron çerçevelerde ve olay döngülerinde kullanın
aiohttp Bağımlılık Varsayılan olarak yüklenmez Açıkça yükleyin: pip install aiohttp
İstemci yaşam döngüsü Açıkça kapatılmalıdır Kullan async with veya ara 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()

Async ve senkron ne zaman kullanılmalı?

Scenario Önerilen istemci
Web çerçeveleri (FastAPI, Quart) azure.cosmos.aio.CosmosClient
Sunucusuz (Azure İşlevleri zaman uyumsuz) azure.cosmos.aio.CosmosClient
Komut dosyaları ve toplu işler azure.cosmos.CosmosClient
Basit CLI araçları azure.cosmos.CosmosClient

Warning

Eşitlemeyi CosmosClient zaman uyumsuz bir olay döngüsü içinde kullanmayın. Senkronizasyon istemcisi, olay döngüsünü engelleyen, performans düşüren ve uygulamanızda kilitlenmelere yol açabilecek bloklayıcı G/Ç çağrıları yapar.

Daha fazla bilgi için bkz. Python SDK README asenkron bölümü.

Veri tasarımı

Veri tasarımı parametreleri

Parametre Varsayılan veya kısıtlama Ne zaman kullanılır?
Belge boyutu N/A RU maliyetini azaltmak için küçük boyutta tutun
Tanımlayıcı karakterler Özel karakter yok Beklenmeyen davranışlardan kaçının
Dizinleme yolları Dizine alınan tüm yollar Daha hızlı yazma işlemleri için kullanılmayan yolları dışlama 
container_properties = {
    "id": "items",
    "indexingPolicy": {
        "excludedPaths": [{"path": "/*"}]
    }
}
print(container_properties["indexingPolicy"])
# Expected: excludedPaths configured

Daha fazla bilgi için bkz. SDK örneğini kullanarak dizin oluşturma.

Konak özellikleri

Ana Bilgisayar Özellikleri Parametreleri

Parametre Varsayılan veya kısıtlama Ne zaman kullanılır?
CPU kullanımı <70% önerilir Yüksekse ölçeği artırma veya genişletme
Hızlandırılmış Ağ Disabled Yüksek trafik için VM'lerde etkinleştirme
Sorgu sayfası boyutu 100 öğe / 4 MB Gidiş dönüşleri azaltmak için artırın 
items = container.query_items(
    query="SELECT * FROM c",
    max_item_count=500
)
print("Page size set to 500")
# Expected: fewer round trips

Sonraki Adımlar

Python SDK'sına yönelik performans ipuçları hakkında daha fazla bilgi edinmek için bkz. Azure Cosmos DB Python SDK'sı için performans ipuçları.

Uygulamanızı ölçek ve yüksek performans için tasarlama hakkında daha fazla bilgi edinmek için bkz. Azure Cosmos DB içinde bölümleme ve ölçeklendirme.

Azure Cosmos DB'ye geçiş için kapasite planlaması yapmaya mı çalışıyorsunuz? Kapasite planlaması için mevcut veritabanı kümeniz hakkındaki bilgileri kullanabilirsiniz.

  • Tek bildiğiniz mevcut veritabanı kümenizdeki sanal çekirdek ve sunucu sayısıysa, sanal çekirdekleri veya vCPU'ları kullanarak istek birimlerini tahmin etme hakkında bilgi edinin
  • Geçerli veritabanı iş yükünüz için tipik istek oranlarını biliyorsanız, Azure Cosmos DB kapasite planlayıcısını kullanarak istek birimlerini tahmin etme hakkında bilgi edinin.
  • Last updated on