Azure Cosmos DB for NoSQL での Python SDK のベスト プラクティス

  • 適用対象: ✅ NoSQL

このガイドには、最新バージョンの Python SDK for Azure Cosmos DB for NoSQL を使用して構築されたソリューションのベスト プラクティスが含まれています。 ここに記載されているベスト プラクティスは、待機時間の短縮、可用性の向上、ソリューションの全体的なパフォーマンスの向上に役立ちます。

アカウントの構成

アカウント構成パラメーター

パラメーター 既定または制約 いつ使用するか
リージョン共置 アプリリージョンと同じ 待機時間を短縮する
複数リージョンのレプリケーション 既定では無効になっています 可用性のために 2 つ以上のリージョンを有効にする
サービスマネージド フェールオーバー Optional 運用環境のワークロードに対して有効にする 
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 を使用して複数のリージョンを追加する方法の詳細については、 グローバル配布のチュートリアルを参照してください。

SDK の使用

SDK の使用パラメーター

パラメーター 既定または制約 いつ使用するか
SDK バージョン 利用可能な最新 常に最適なパフォーマンスを実現
CosmosClient インスタンス アプリごとに 1 つ アプリの有効期間中に再利用する
優先場所 None 読み取りとフェールオーバーを最適化する 
client = CosmosClient(
    url,
    credential,
    preferred_locations=["East US", "West US"]
)
print(client.client_connection._preferred_locations)
# Expected: ['East US', 'West US']

一時エラーとは、その基になる原因がすぐに自動的に解決されるエラーです。 データベースに接続するアプリケーションは、これらの一時エラーを想定して構築する必要があります。 これに対処するには、アプリケーション エラーとしてユーザーに表示するのではなく、コードに再試行ロジックを実装します。 SDK には、読み取りやクエリの操作など、再試行可能な要求でこれらの一時的なエラーを処理するロジックが組み込まれています。 書き込みがべき等ではないため、SDK は一時的な障害に対して書き込みを再試行できません。 ユーザーは、SDK を使用して、スロットルの再試行ロジックを構成できます。 再試行するエラーの詳細については、 回復性のあるアプリケーション ガイダンスを参照してください。

SDK ログを使用して 診断情報をキャプチャ し、待機時間の問題をトラブルシューティングします。

非同期クライアント

非同期クライアントの要件

Requirement 既定または制約 いつ使用するか
インポート パス azure.cosmos.aio.CosmosClient 非同期フレームワークとイベント ループでの使用
aiohttp 依存関係 既定ではインストールされていません 明示的にインストールします。 pip install aiohttp
クライアントのライフサイクル 明示的に閉じる必要があります async withを使用するか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()

非同期と同期を使用するタイミング

Scenario 推奨されるクライアント
Web フレームワーク (FastAPI、Quart) azure.cosmos.aio.CosmosClient
サーバーレス (非同期 Azure Functions) azure.cosmos.aio.CosmosClient
スクリプトとバッチ ジョブ azure.cosmos.CosmosClient
シンプルな CLI ツール azure.cosmos.CosmosClient

Warning

非同期イベント ループ内で同期 CosmosClient を使用しないでください。 同期クライアントは、イベント ループをブロックするブロック I/O 呼び出しを行い、パフォーマンスを低下させ、アプリケーションでデッドロックを引き起こす可能性があります。

詳細については、「Python SDK README async」セクションを参照してください。

データ設計

データ 設計パラメーター

パラメーター 既定または制約 いつ使用するか
ドキュメント サイズ N/A RU コストを削減するために小規模に保つ
識別子文字 特別な文字なし 予期しない動作を回避する
インデックス作成パス すべてのパスがインデックス化されました 書き込みを高速化するために未使用のパスを除外する 
container_properties = {
    "id": "items",
    "indexingPolicy": {
        "excludedPaths": [{"path": "/*"}]
    }
}
print(container_properties["indexingPolicy"])
# Expected: excludedPaths configured

詳細については、 SDK サンプルを使用したインデックスの作成を参照してください。

ホストの特性

ホスト特性パラメーター

パラメーター 既定または制約 いつ使用するか
CPU 使用率 <70% 推奨 スケールアップまたはスケールアウト (高い場合)
高速ネットワーク Disabled VM 上で高トラフィックを処理する設定を有効にする
クエリ ページ サイズ 100 アイテム/ 4 MB ラウンド トリップを減らすために増やす 
items = container.query_items(
    query="SELECT * FROM c",
    max_item_count=500
)
print("Page size set to 500")
# Expected: fewer round trips

次のステップ

Python SDK のパフォーマンスに関するヒントの詳細については、 Azure Cosmos DB Python SDK のパフォーマンスに関するヒントを参照してください。

スケーリングと高パフォーマンスのためのアプリケーションの設計について詳しくは、「Azure Cosmos DB でのパーティション分割とスケーリング」をご覧ください。

Azure Cosmos DB への移行のための容量計画を実行しようとしていますか? 容量計画のために、既存のデータベース クラスターに関する情報を使用できます。

  • Last updated on