Praktik terbaik untuk SDK Python di Azure Cosmos DB untuk NoSQL

  • Berlaku untuk: ✅ NoSQL

Panduan ini mencakup praktik terbaik untuk solusi yang dibangun menggunakan versi terbaru SDK Python untuk Azure Cosmos DB untuk NoSQL. Praktik terbaik yang disertakan di sini membantu meningkatkan latensi, meningkatkan ketersediaan, dan meningkatkan performa keseluruhan untuk solusi Anda.

Konfigurasi akun

Parameter konfigurasi akun

Parameter Default atau kendala Kapan digunakan
Kolokasi wilayah Sama seperti wilayah aplikasi Mengurangi latensi
Replikasi multi-wilayah Dinonaktifkan secara default Mengaktifkan 2+ wilayah untuk ketersediaan
Failover dikelola oleh layanan Optional Aktifkan untuk beban kerja produksi 
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

Untuk informasi selengkapnya tentang cara menambahkan beberapa wilayah menggunakan Python SDK, lihat tutorial distribusi global.

Penggunaan SDK

Parameter penggunaan SDK

Parameter Default atau kendala Kapan digunakan
Versi SDK Versi terbaru tersedia Selalu untuk performa optimal
Instans CosmosClient Satu per aplikasi Gunakan kembali untuk masa pakai aplikasi
preferred_locations Tidak Mengoptimalkan pembacaan dan failover pada sistem 
client = CosmosClient(
    url,
    credential,
    preferred_locations=["East US", "West US"]
)
print(client.client_connection._preferred_locations)
# Expected: ['East US', 'West US']

Kesalahan sementara adalah kesalahan yang memiliki penyebab mendasar yang segera teratasi dengan sendirinya. Aplikasi yang tersambung ke database Anda harus dibangun untuk memperkirakan kesalahan sementara ini. Untuk menanganinya, terapkan logika coba lagi dalam kode Anda alih-alih menampilkannya kepada pengguna sebagai kesalahan aplikasi. SDK memiliki logika bawaan untuk menangani kegagalan sementara ini pada permintaan yang dapat dicoba lagi seperti operasi baca atau kueri. SDK tidak dapat mengulang penulisan untuk kegagalan yang bersifat sementara karena penulisan tidak idempoten. SDK memungkinkan pengguna untuk mengonfigurasi logika pengulangan untuk pembatasan lalu lintas. Untuk detail tentang kesalahan mana yang akan diulang, lihat panduan aplikasi yang tangguh.

Gunakan pengelogan SDK untuk mengambil informasi diagnostik dan memecahkan masalah latensi.

Klien asinkron

Persyaratan klien asinkron

Persyaratan Default atau kendala Kapan digunakan
Jalur impor azure.cosmos.aio.CosmosClient Gunakan dalam kerangka kerja asinkron dan perulangan peristiwa
aiohttp Ketergantungan Tidak diinstal secara default Instal secara eksplisit: pip install aiohttp
Siklus hidup klien Harus ditutup secara eksplisit Menggunakan async with atau memanggil 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()

Kapan menggunakan asinkron vs sinkronisasi

Scenario Klien yang direkomendasikan
Kerangka kerja web (FastAPI, Quart) azure.cosmos.aio.CosmosClient
Tanpa server (asinkron Azure Functions) azure.cosmos.aio.CosmosClient
Skrip dan tugas batch azure.cosmos.CosmosClient
Alat CLI sederhana azure.cosmos.CosmosClient

Warning

Jangan gunakan sinkronisasi CosmosClient di dalam perulangan peristiwa asinkron. Klien sinkronisasi membuat pemblokiran panggilan I/O yang memblokir perulangan peristiwa, menurunkan performa, dan berpotensi menyebabkan kebuntuan di aplikasi Anda.

Untuk informasi selengkapnya, lihat bagian asinkron Python SDK README.

Desain data

Parameter desain data

Parameter Default atau kendala Kapan digunakan
Ukuran dokumen N/A Tetap kecil untuk mengurangi biaya RU
Karakter pengidentifikasi Tidak ada karakter khusus Hindari perilaku tak terduga
Jalur pengindeksan Semua jalur diindeks Mengecualikan jalur yang tidak digunakan untuk penulisan yang lebih cepat 
container_properties = {
    "id": "items",
    "indexingPolicy": {
        "excludedPaths": [{"path": "/*"}]
    }
}
print(container_properties["indexingPolicy"])
# Expected: excludedPaths configured

Untuk informasi selengkapnya, lihat membuat indeks menggunakan sampel SDK.

Karakteristik host

Karakteristik tuan rumah

Parameter Default atau kendala Kapan digunakan
Pemanfaatan CPU <70% direkomendasikan Tingkatkan kapasitas atau perluas jangkauan jika permintaan tinggi
Penjaringan Dipercepat Nonaktif Aktifkan pada VM untuk lalu lintas tinggi
Ukuran halaman kueri 100 item / 4 MB Tingkatkan untuk mengurangi perjalanan pulang pergi 
items = container.query_items(
    query="SELECT * FROM c",
    max_item_count=500
)
print("Page size set to 500")
# Expected: fewer round trips

Langkah berikutnya

Untuk mempelajari selengkapnya tentang tips performa untuk Python SDK, lihat Tips performa untuk Azure Cosmos DB Python SDK.

Untuk mempelajari selengkapnya tentang perancangan aplikasi Anda untuk skala dan kinerja tinggi, lihat Pemartisian dan penyekalaan di Azure Cosmos DB.

Mencoba melakukan perencanaan kapasitas untuk migrasi ke Azure Cosmos DB? Anda dapat menggunakan informasi tentang kluster database Anda yang ada saat ini untuk membuat perencanaan kapasitas.

  • Last updated on