Azure Cosmos DB SDK for Python の2026年5月更新でまず押さえるべき点は、「PythonからAzure Cosmos DBを扱うときに、どのライブラリを使い、どこを確認すべきか」が公式リファレンス上で整理されていることです。実装でデータを作成・読み取り・更新・検索するなら azure-cosmos、アカウントやリソースを管理する自動化では azure-mgmt-cosmosdb を使い分けます。既存システムでは、SDKバージョン、Python実行環境、CosmosClient の生成方法、マルチリージョン設定、診断ログ、非同期処理の使い方を確認するのが優先です。Microsoft Learnの該当ページは現在、最終更新日が2026年5月20日と表示されていますが、本稿では2026年5月19日前後に公開・更新された公式情報として、管理者と開発者が確認すべき実務ポイントを整理します。 (Microsoft Learn)
Azure Cosmos DB SDK for Pythonで確認すべき結論
Azure Cosmos DB SDK for Python は、PythonアプリケーションからAzure Cosmos DB上のJSONドキュメントを保存・検索するためのSDKです。公式リファレンスでは、アプリケーション開発やデータ探索向けのクライアントライブラリとして azure-cosmos、アカウントレベルの管理操作向けライブラリとして azure-mgmt-cosmosdb が示されています。 (Microsoft Learn)
今回の情報で重要なのは、「すぐに全アプリを移行しなければならない」という告知ではなく、次のような確認を促す内容だと捉えるべきです。
| 確認項目 | まず見るべきポイント | 影響を受けやすい人 |
|---|---|---|
| 利用ライブラリ | データ操作は azure-cosmos、管理操作は azure-mgmt-cosmosdb | Python開発者、SRE、クラウド管理者 |
| 対象API | azure-cosmos は主にAzure Cosmos DB for NoSQL、旧SQL API向け | MongoDB、Cassandra、Gremlin、Table API利用者 |
| 実行環境 | PythonバージョンとSDKの対応範囲 | アプリ基盤担当、CI/CD管理者 |
| 接続方式 | CosmosClient の使い回し、リージョン、タイムアウト、再試行設定 | バックエンド開発者 |
| 運用設定 | 診断ログ、例外処理、RU消費、フェールオーバー | 運用担当、監視担当 |
| 移行計画 | 古いSDKや固定バージョンの棚卸し | 管理者、プロジェクトリード |
特に注意したいのは、SDKリファレンスの更新を「新機能の追加」とだけ見るのではなく、既存アプリの依存関係と運用設定を見直す機会にすることです。Azure Cosmos DBはRU消費、リージョン構成、整合性レベル、パーティションキー設計の影響が大きいため、SDK更新だけを機械的に行うと、レイテンシや課金、可用性に影響が出る場合があります。
何が変わるのか：ライブラリの使い分けが重要になる
公式情報で最も実務的に重要なのは、Python向けSDKの用途が明確に分かれている点です。
| 用途 | ライブラリ | 主な操作 | 判断基準 |
|---|---|---|---|
| アプリからデータを扱う | azure-cosmos | データベース作成、コンテナー作成、ItemのCRUD、SQL風クエリ | Webアプリ、API、バッチ処理からCosmos DBのデータを読む・書く場合 |
| Azure Cosmos DBアカウントを管理する | azure-mgmt-cosmosdb | アカウント、キー、メトリック、リソース設定の取得・管理 | IaC補助、運用自動化、管理スクリプトで使う場合 |
azure-cosmos は、データベース、コンテナー、Itemに対するCRUD操作やクエリ実行に使うライブラリです。公式ページでも、データベース作成、コンテナー作成、コンテナー内ItemのCRUD、コンテナーへのクエリが主要なサンプルとして示されています。 (Microsoft Learn)
一方で、azure-mgmt-cosmosdb はAzure Cosmos DBのResource Providerを操作する管理系ライブラリです。たとえば、既存アカウントの取得、アカウント一覧、接続文字列やキー、メトリック定義の取得などは管理ライブラリ側の役割です。 (Microsoft Learn)
実務で間違えやすいポイント
よくある失敗は、アプリケーションコードの中で管理操作までまとめて行おうとすることです。
たとえば、通常のWeb APIで商品データやユーザーデータを読み書きするだけなら、基本的には azure-cosmos で十分です。逆に、Azureサブスクリプション配下のCosmos DBアカウント一覧を取得したり、運用スクリプトでキーやメトリックを確認したりするなら、azure-mgmt-cosmosdb が対象になります。
本番アプリの中に管理系処理を混ぜると、権限が広くなりすぎます。セキュリティ設計上は、アプリはデータ操作に必要な最小権限、運用スクリプトは管理操作に必要な権限、と分けるのが安全です。
対象者：PythonでCosmos DBを使う開発者と運用担当者
今回の公式情報を確認すべき対象者は、主に次のような人です。
| 対象者 | 確認すべき内容 |
|---|---|
| Pythonバックエンド開発者 | azure-cosmos のバージョン、CosmosClient の使い方、クエリ、例外処理 |
| FastAPIやAzure Functions利用者 | 同期クライアントと非同期クライアントの使い分け |
| クラウド管理者 | azure-mgmt-cosmosdb の利用範囲、権限、管理スクリプト |
| SRE・運用担当 | 診断ログ、タイムアウト、再試行、リージョン設定 |
| 移行担当 | 古いSDK、古いPython、依存ライブラリの固定状況 |
公式のベストプラクティスでは、FastAPIやQuartのようなWebフレームワーク、非同期Azure Functionsでは azure.cosmos.aio.CosmosClient、スクリプトやバッチジョブ、シンプルなCLIツールでは同期版の azure.cosmos.CosmosClient が推奨例として示されています。非同期イベントループ内で同期クライアントを使うと、イベントループをブロックし、パフォーマンス低下やデッドロックを招く可能性があります。 (Microsoft Learn)
既存アプリへの影響範囲
今回のリファレンス更新だけで、既存のAzure Cosmos DBアプリが即座に停止するわけではありません。ただし、次の条件に当てはまる場合は、影響確認が必要です。
古いSDKを使っている場合
Azure Cosmos DB Python SDK for API for NoSQLの1.xおよび2.xは、2022年8月31日以降、バグ修正やサポートの対象外です。リクエスト自体は引き続き処理されると説明されていますが、新機能、修正、サポートを受けられない状態になります。 (Microsoft Learn)
つまり、古いSDKを使い続けることは「すぐ壊れる」というより、「障害時に原因切り分けや修正が難しくなる」リスクです。特に本番環境、金融・医療・認証などの重要データを扱うシステムでは、サポート外SDKの継続利用は避けるべきです。
Pythonバージョンが古い場合
SDK更新時は、Python本体のバージョンも確認が必要です。Azure SDK for Pythonのリリース履歴では、azure-cosmos 4.14.0以降はPython 3.9以上が必要とされています。また、PyPI上の azure-cosmos 4.15.0もPython 3.9以上を要求しています。 (GitHub)
開発端末では動いても、本番コンテナーやAzure Functionsのランタイム、CI環境だけPythonが古いというケースは珍しくありません。SDK更新前に、次のコマンドで棚卸ししてください。
python --version
python -m pip show azure-cosmos
python -m pip show azure-mgmt-cosmosdb
python -m pip show azure-identity本番環境では、単に pip install --upgrade azure-cosmos を実行するのではなく、検証済みバージョンを requirements.txt やロックファイルで固定するのが安全です。
azure-cosmos==検証済みバージョン
azure-identity==検証済みバージョン開発者が確認すべき設定
CosmosClient はアプリ内で使い回す
CosmosClient はAzure Cosmos DBアカウントを表すクライアントで、リクエストの設定と実行に使います。公式リファレンスでは、効率的な接続管理とパフォーマンスのため、アプリケーションのライフタイム内で単一インスタンスを維持することが推奨されています。また、CosmosClient の初期化は重い操作であり、資格情報やネットワーク接続の検証目的で安易に繰り返すべきではありません。 (Microsoft Learn)
避けたい実装例は、リクエストごとに CosmosClient を生成するコードです。
# 避けたい例：APIリクエストごとに生成すると無駄が大きい
def handler(request):
client = CosmosClient(url, credential=key)
container = client.get_database_client("db").get_container_client("items")
return list(container.read_all_items())実務では、アプリ起動時にクライアントを作成し、各リクエストでは既存インスタンスを再利用します。
import os
from azure.cosmos import CosmosClient
client = CosmosClient(
os.environ["ACCOUNT_URI"],
credential=os.environ["ACCOUNT_KEY"]
)
database = client.get_database_client("appdb")
container = database.get_container_client("items")
def get_item(item_id, partition_key):
return container.read_item(item=item_id, partition_key=partition_key)接続方式はGateway前提で考える
Python SDKの connection_mode は、現在Gatewayのみをサポートすると説明されています。Direct TCP Modeを前提にネットワーク設計や性能見積もりをしている場合は、Python SDKの仕様と合っているか確認してください。 (Microsoft Learn)
特に、.NET SDKやJava SDKからPythonへ移行する場合、「同じCosmos DBだから接続方式も同じ」と考えると見落としが発生します。移行時は、レイテンシ、ファイアウォール、プロキシ、プライベートエンドポイント、アプリ配置リージョンを含めて確認する必要があります。
マルチリージョン構成では preferred_locations を確認する
Azure Cosmos DBを複数リージョンで使っている場合、preferred_locations の設定が重要です。公式ベストプラクティスでは、読み取りとフェールオーバーの最適化に優先場所を使う例が示されています。 (Microsoft Learn)
from azure.cosmos import CosmosClient
client = CosmosClient(
url,
credential,
preferred_locations=["Japan East", "Japan West"]
)アプリの配置先がJapan Eastなのに、優先読み取りリージョンが遠いリージョンになっていると、不要な遅延が発生します。障害時の挙動も含めて、アプリの配置リージョン、Cosmos DBの書き込みリージョン、読み取りリージョンの順序を確認してください。
書き込みリトライは安易に有効化しない
retry_write は、Itemの書き込み操作をSDKが自動再試行する回数を指定できる設定です。ただし、公式リファレンスでは、冪等性が保証されない書き込みでも再試行されるため、アプリケーションが重複処理のリスクを許容できる場合、または安全に検出・処理できるロジックがある場合に限って有効化すべきと説明されています。 (Microsoft Learn)
たとえば、注文作成やポイント付与のような処理では、同じ書き込みが再実行されると二重登録や二重付与につながる可能性があります。使う場合は、ItemのID設計、ユニークキー、業務側の冪等キーをセットで設計してください。
管理者が確認すべき設定
管理ライブラリの権限を広げすぎない
azure-mgmt-cosmosdb は、Cosmos DBアカウントやキー、メトリックなど管理系の情報を扱えます。DatabaseAccountsOperationsでは、アカウント取得、一覧取得、接続文字列、アクセスキー、メトリック関連の操作が提供されています。 (Microsoft Learn)
そのため、アプリケーション本体に管理ライブラリを入れる場合は注意が必要です。必要以上に広いAzure RBAC権限やキー取得権限を付けると、アプリ侵害時の影響範囲が大きくなります。
推奨される分離は次の通りです。
| 処理 | 推奨する実行場所 | 権限の考え方 |
|---|---|---|
| Itemの読み書き | アプリケーション | データ操作に必要な最小権限 |
| アカウント設定確認 | 管理スクリプト、CI/CD、運用端末 | 管理操作に限定した権限 |
| キーや接続文字列の取得 | 原則として運用管理プロセス内 | アプリコードに埋め込まない |
| メトリック取得 | 監視基盤、運用自動化 | 監視に必要な読み取り権限 |
Azure AD認証とマネージドIDを優先する
アカウントキーで接続する実装は簡単ですが、キーの漏えいやローテーション運用が課題になります。PyPIの公式パッケージ説明では、azure-identity を使ったAzure AD認証、DefaultAzureCredential の利用例が示されています。また、Azure AD認証で利用するマネージドIDには readMetadata 権限が必要とされています。 (PyPI)
import os
from azure.identity import DefaultAzureCredential
from azure.cosmos import CosmosClient
client = CosmosClient(
os.environ["ACCOUNT_URI"],
credential=DefaultAzureCredential()
)本番環境では、ローカル開発、CI/CD、本番アプリで認証方式が変わることがあります。DefaultAzureCredential を使う場合でも、どの資格情報が実際に使われるかを環境ごとに確認してください。
移行・展開前のチェックリスト
SDK更新や実行環境の変更は、小さく見えても本番影響が出やすい作業です。以下の順序で確認すると、トラブルを減らせます。
| 手順 | 作業内容 | 失敗しやすいポイント |
|---|---|---|
| 1 | 現在のSDKとPythonバージョンを確認 | 本番コンテナーだけPythonが古い |
| 2 | requirements.txt やロックファイルを確認 | 暗黙のアップグレードで未検証版が入る |
| 3 | 同期・非同期クライアントの使い分けを確認 | FastAPIなどで同期クライアントを使いイベントループをブロック |
| 4 | CosmosClient の生成箇所を確認 | リクエストごとに生成して接続効率が悪化 |
| 5 | クエリとパーティションキーを確認 | クロスパーティションクエリでRU消費が増える |
| 6 | タイムアウト・再試行・リージョン設定を確認 | 障害時に想定外リージョンへ流れる |
| 7 | 診断ログを検証環境で有効化 | DEBUGログに機密情報が出る可能性を見落とす |
| 8 | カナリアリリースで監視 | 429、タイムアウト、RU消費、レイテンシを見ないまま全面展開 |
診断ログは便利だが、出力内容に注意する
Python SDKでは標準の logging ライブラリを使って診断ログを出せます。詳細なDEBUGレベルのログでは、リクエストやレスポンスの本文、マスクされていないヘッダーが出力される可能性があるため、本番環境で常時有効化するのは避けるべきです。公式説明では、CosmosHttpLoggingPolicy と enable_diagnostics_logging による診断情報の取得にも触れられています。 (PyPI)
障害調査で一時的に詳細ログを出す場合は、次の点を必ず確認してください。
| 確認項目 | 理由 |
|---|---|
| ログにキーやトークンが出ないか | 認証情報漏えいを防ぐため |
| 個人情報や業務データが本文に含まれないか | コンプライアンス上のリスクを下げるため |
| ログ保存先のアクセス権限 | 調査担当以外が閲覧できないようにするため |
| 有効化期間 | 調査後にDEBUGログを止め忘れないため |
クエリとパーティション設計の確認ポイント
Azure Cosmos DB SDK for Pythonでは、ContainerProxy.query_items を使ってSQL風のクエリを実行できます。公式パッケージ説明では、パラメーター化クエリの例も示されています。 (PyPI)
ただし、実務では「動くクエリ」と「本番で使えるクエリ」は別です。特に次の点を確認してください。
| 観点 | 確認内容 |
|---|---|
| パーティションキー | 単一パーティションで処理できるか |
enable_cross_partition_query | 必要な場合だけ有効化しているか |
| RU消費 | 検索条件やインデックス設計に無駄がないか |
| ページング | 大量データ取得時に一括取得していないか |
| パラメーター化 | 文字列連結でクエリを組み立てていないか |
クロスパーティションクエリは便利ですが、データ量が増えるほどRU消費やレイテンシに影響します。検索画面や集計バッチで多用している場合は、SDK更新のついでにクエリメトリックやRU消費も確認しましょう。
Python SDKで注意したい制限
Python SDKには、他言語SDKと同じように扱えない点があります。公式パッケージ説明では、Direct TCP Mode、Change Feed Processor、Python SDKでのBulk requests未実装などが制限として挙げられています。Bulk相当の処理は非同期クライアントを使った回避例が示されていますが、RUを急速に消費する可能性があるため、Cosmos DB Emulatorなどで検証することが推奨されています。 (PyPI)
特に移行案件では、次のような思い込みに注意してください。
| 思い込み | 実際に確認すべきこと |
|---|---|
| .NET SDKでできたからPython SDKでも同じ | Python SDKの制限と代替手段を確認する |
| 非同期にすればBulk処理と同じになる | RU消費、並列数、失敗時の再試行を設計する |
| SDK更新だけなら負荷試験は不要 | クエリ、再試行、リージョン設定で挙動が変わる可能性がある |
| 開発環境で動けば本番も動く | Pythonバージョン、ネットワーク、認証方式が本番と一致しているか確認する |
展開時に見るべき監視項目
SDK更新後は、アプリが起動するかだけでなく、Azure Cosmos DB側のメトリックも確認してください。最低限、次の項目を更新前後で比較します。
| 監視項目 | 見る理由 |
|---|---|
| RU消費量 | クエリや再試行の変化で消費が増えていないか |
| 429 Too Many Requests | スロットリングが増えていないか |
| レイテンシ | リージョン設定や接続方式の影響を見る |
| 5xx、408、接続エラー | タイムアウトや一時障害時の挙動を見る |
| リクエスト数 | 再試行や初期化の増加を検知する |
| アプリログ | SDK例外、認証失敗、パーティションキー指定漏れを見る |
SDK更新後に429が増えた場合、単純にRUを増やす前に、クロスパーティションクエリ、並列数、再試行設定、リクエストごとの CosmosClient 生成がないかを確認してください。特にバッチ処理や非同期処理では、並列数を上げすぎると短時間でRUを使い切ることがあります。
まず実施すべきアクション
Azure Cosmos DB SDK for Pythonの公式情報を確認したら、最初にやるべきことは「SDKを上げる」ではなく「現状を棚卸しする」ことです。
python --version
python -m pip show azure-cosmos
python -m pip show azure-mgmt-cosmosdb
python -m pip show azure-identity次に、アプリコードで次の点を確認します。
| 確認対象 | 見直す内容 |
|---|---|
CosmosClient | アプリ内で使い回しているか |
| 認証 | アカウントキー固定ではなく、可能ならAzure AD認証を使えるか |
| クエリ | パーティションキー指定、パラメーター化、RU消費を確認したか |
| リージョン | preferred_locations がアプリ配置と合っているか |
| 再試行 | retry_write を安易に有効化していないか |
| ログ | DEBUGログを本番で常時出していないか |
| 依存関係 | PythonバージョンとSDKバージョンが対応しているか |
Azure Cosmos DB SDK for Pythonの更新は、単なるドキュメント確認で終わらせるより、依存関係、接続設計、運用監視を点検するタイミングとして活用するのが効果的です。特に本番環境では、検証済みバージョンを固定し、ステージングでCRUD、クエリ、認証、リージョンフェールオーバー、RU消費を確認してから段階的に展開してください。
コメント