Azure Cosmos DB SDK for Javaで最初に確認すべきことは、「自社のJavaアプリがどのSDKパッケージを使っているか」です。2026年5月19日前後に更新された公式リファレンスを見て対応する場合でも、サービス側の設定が自動的に変わるわけではありません。実務上の重要ポイントは、古いazure-documentdb系を使い続けていないか、現行のcom.azure:azure-cosmos v4系へ移行・更新できるか、更新後に接続方式、リージョン指定、診断ログ、依存関係の衝突を検証できているかです。
特に注意したいのは、公式の「Azure Cosmos DB SDK for Java」参照ページには古いcom.microsoft.azure:azure-documentdbの例が残っている一方で、現行のAzure Cosmos DB for NoSQL向けJavaクライアントはcom.azure:azure-cosmos v4系として案内されている点です。新規開発では古いサンプルをそのまま貼り付けず、最新のクライアントライブラリ、リリースノート、移行ガイドをセットで確認してください。MicrosoftのJava SDK v4ページでは、v4はSync APIとAsync APIを1つのMavenアーティファクトにまとめ、Project ReactorとNettyをベースにしたAsyncサポートを提供すると説明されています。(GitHub)
Azure Cosmos DB SDK for Javaは何が変わるのか
今回の公式情報を読むときは、「Azure Cosmos DBサービス本体の仕様変更」と「Java SDKリファレンス・SDKバージョンの更新」を分けて考える必要があります。
公式リファレンスの更新そのものは、既存のAzure Cosmos DBアカウントやコンテナーの設定を直接変更するものではありません。影響が出るのは、開発チームがMavenやGradleの依存関係を更新した場合、またはSpring Data Cosmosなどの上位ライブラリ経由でazure-cosmosのバージョンが変わった場合です。
| 確認ポイント | 実務上の意味 | 取るべき対応 |
|---|---|---|
| 公式リファレンスの依存関係例 | 古いazure-documentdbの例が残っている場合がある | 新規開発ではそのまま採用せず、com.azure:azure-cosmosを確認する |
| 現行Javaクライアント | Azure Cosmos DB SQL API、現在の表記ではAzure Cosmos DB for NoSQL向けのJava SDK | Maven Central、Microsoft Learn、リリースノートでバージョンを突き合わせる |
| SDK v4の更新 | 新機能、パフォーマンス改善、バグ修正、セキュリティ修正が入る | 依存関係を棚卸しし、検証環境で更新テストを行う |
| 古いSDK | サポート終了済み、または最新機能・修正を受けられない可能性がある | 移行計画を作り、API差分と依存関係を確認する |
Microsoft Learnの現行クライアントライブラリページでは、Azure Cosmos DB Client Library for Javaのバージョンとして4.80.0が表示され、Mavenの依存関係はcom.azure:azure-cosmosとして案内されています。Maven Centralでも同パッケージの4.80.0が確認できます。(Microsoft Learn)
対象になるアプリケーションと影響範囲
影響を受けるのは、JavaからAzure Cosmos DB for NoSQL、旧称SQL APIにアクセスしているアプリケーションです。MongoDB API、Apache Cassandra API、Gremlin API、Table APIをそれぞれ専用ドライバーで使っている場合は、今回のazure-cosmos Java SDK v4の影響を直接受けないケースがあります。ただし、社内の共通ライブラリやSpring Data Cosmos経由でazure-cosmosを使っている場合は、依存関係の確認が必要です。
| 対象者 | 確認すべきこと |
|---|---|
| Java開発者 | pom.xml、build.gradle、lockfile、SBOMにあるCosmos DB関連パッケージ |
| アプリ運用担当 | SDK更新後のレイテンシ、429、タイムアウト、CPU、接続数、リージョンルーティング |
| Azure管理者 | Azure Advisor、Azure Cosmos DBの推奨事項、ネットワーク、Private Link、Service Endpoint、ファイアウォール設定 |
| セキュリティ担当 | サポート終了SDK、脆弱性修正、認証方式、シークレット管理、依存ライブラリの衝突 |
| SRE・基盤担当 | カナリア展開、ロールバック、診断ログ、OpenTelemetryやApplication Insights連携 |
Azure Cosmos DBの自動推奨事項では、古いSDKの使用、インデックス作成、コスト、移行、クエリ利用などの観点で推奨事項が表示されるため、SDK更新時はAzure portalのCosmos DB通知とAzure Advisorも確認対象に含めるとよいでしょう。(Microsoft Learn)
まず依存関係を棚卸しする
開発者が最初に行うべき作業は、実際にどのSDKを使っているかの確認です。アプリケーションコードだけでなく、社内共通ライブラリ、Spring Boot Starter、古いユーティリティJAR、Dockerイメージ内のビルド成果物も対象にします。
Mavenの場合は、次のように確認します。
mvn -q dependency:tree | grep -E "azure-cosmos|azure-cosmosdb|azure-documentdb|azure-spring-data-cosmos"Gradleの場合は、次のように確認します。
./gradlew dependencies --configuration runtimeClasspath | grep -E "azure-cosmos|azure-cosmosdb|azure-documentdb|azure-spring-data-cosmos"Windows PowerShellでは、次の形式が使いやすいです。
mvn -q dependency:tree | Select-String "azure-cosmos|azure-cosmosdb|azure-documentdb|azure-spring-data-cosmos"見つかったパッケージごとの判断基準は次の通りです。
| 見つかった依存関係 | 判断 | 次の対応 |
|---|---|---|
com.azure:azure-cosmos v4.x | 現行ライン | リリースノートを確認し、検証後に更新 |
com.microsoft.azure:azure-documentdb | 旧SDK。Azure SDKの非推奨リストではazure-documentdbはcom.azure/azure-cosmosへ置き換え対象とされ、サポート終了日も示されている | v4移行を計画 |
com.microsoft.azure:azure-cosmosdb | Async Java SDK v2系の可能性 | v4移行を計画 |
com.microsoft.azure:azure-cosmos、com.azure.data.cosmos | Java SDK v3系の可能性 | API差分を確認してv4へ移行 |
azure-spring-data-cosmos | Spring Data経由でCosmos DBを利用 | 親プロジェクト、Spring Boot、Azure SDK BOM、推移的依存を確認 |
Microsoftの移行ガイドでは、Java SDK v4のパッケージはcom.azure.cosmosであり、古いJava SDK 2.xや3.xとはMavenアーティファクト名、パッケージ名、API構造が異なると説明されています。古いazure-documentdbはAzure SDKの非推奨リストでもcom.azure/azure-cosmosへの置き換え対象として掲載されています。(Microsoft Learn)
Java SDK v4.80.0で注目すべき変更点
2026年5月時点のazure-cosmos v4.80.0では、実務で見逃したくない追加機能と修正が複数あります。すべてのアプリに即時対応が必要という意味ではありませんが、該当機能を使っている場合は回帰テストに組み込むべきです。
| 変更点 | 影響するケース | 確認ポイント |
|---|---|---|
| Query Advisorサポート追加 | クエリのRU消費や実行効率を改善したいアプリ | Java SDK側のAPI、Javadoc、リリースノートを確認して検証環境で試す |
additionalHeadersサポート | リクエストにx-ms-cosmos-workload-idなどの追加ヘッダーを付けたい場合 | ワークロード識別、監査、運用分析に使う。機密情報は入れない |
readManyByPartitionKeys追加 | 複数のパーティションキー値にまたがる読み取りを効率化したい場合 | 個別クエリの乱発を置き換えられるか確認 |
Change FeedのstartFrom関連強化 | パーティションのマージ後もChange Feedを扱う処理 | リース、継続トークン、再開位置のテストを行う |
| ネストしたパーティションキーでの修正 | /address/cityのようなネストしたパスを使うコンテナー | readMany、readAllItems、クエリ結果の整合性を確認 |
| カスタムシリアライザー修正 | Jackson設定や独自シリアライザーを使うアプリ | ORDER BY、GROUP BY、集計、DISTINCT、Hybrid Searchの結果を検証 |
| AAD権限まわりの修正 | Throughput controlとMicrosoft Entra ID認証を使う場合 | 不要な権限要求が解消されるか確認 |
| IMDS無効環境での修正 | オンプレミス、ローカル、非Azure環境 | クライアント生成時の例外が再現しないか確認 |
Azure SDK for Javaのazure-cosmos changelogでは、v4.80.0でQuery Advisor、追加ヘッダー、readManyByPartitionKeys、Change Feed関連のサポート、複数のシリアライザー修正や不具合修正が追加・修正されたことが記載されています。なお、Query Advisorの一般ドキュメントには.NET SDK前提の記載が残っているため、Javaで利用する際は一般解説だけでなく、Java SDKのリリースノートとJavadocを確認するのが安全です。(GitHub)
セキュリティと信頼性の観点では古いv4も確認する
「v4を使っているから安全」とは限りません。v4系でも古いバージョンには重大な不具合や、修正済みのセキュリティ課題が残る可能性があります。
例えば、azure-cosmos v4.79.0のリリースノートでは、JavaデシリアライゼーションをJSONベースのシリアライゼーションへ置き換えることで、CWE-502に該当するリモートコード実行リスクへの修正が行われたと記載されています。また、v4.75.0については、少なくともそのバージョンを使用することが強く推奨される旨もchangelogに記載されています。(GitHub)
Azure Advisorの信頼性推奨事項にも、古いAzure Cosmos DB Java SDKを最新バージョンにアップグレードする推奨や、Java SDK v4の推奨バージョンへ更新する推奨が掲載されています。管理者は、アプリ側の依存関係だけでなく、Azure portal側の推奨事項も合わせて確認してください。(Microsoft Learn)
移行時に確認すべきコードと設定
古いSDKからv4へ移行する場合は、単にMavenのバージョンを書き換えるだけでは不十分です。API名、戻り値、非同期処理、依存ライブラリ、接続方式が変わるため、設計単位で確認します。
パッケージとAPI構造を置き換える
古いSDKでは、com.microsoft.azure.documentdbやcom.azure.data.cosmosを使っていることがあります。v4ではcom.azure.cosmosが基本になります。移行ガイドでは、v4のクラスはCosmosClient、CosmosDatabase、CosmosContainerのように階層化されたAPI構造を取ると説明されています。(Microsoft Learn)
古い書き方のイメージです。
DocumentClient client = new DocumentClient(endpoint, key, policy, ConsistencyLevel.Session);v4では、次のようにCosmosClientBuilderからクライアントを作成します。
CosmosClient client = new CosmosClientBuilder()
.endpoint(endpoint)
.key(key)
.consistencyLevel(ConsistencyLevel.SESSION)
.buildClient();
CosmosContainer container = client
.getDatabase("databaseName")
.getContainer("containerName");非同期処理を使う場合はCosmosAsyncClientを使います。
CosmosAsyncClient asyncClient = new CosmosClientBuilder()
.endpoint(endpoint)
.key(key)
.consistencyLevel(ConsistencyLevel.SESSION)
.buildAsyncClient();Microsoftのパフォーマンスガイドでは、v4にはSync APIとAsync APIがあり、高いスループットを狙う場合はAsync APIが適していると説明されています。一方、同期処理中心のアプリではSync APIを選ぶ判断もあり得ます。(Microsoft Learn)
依存関係の衝突を確認する
v2からv4へ移行すると、reactor-core、reactor-netty、netty-handler、guava、jackson、azure-coreなどの依存関係が変わります。移行ガイドでは、mvn dependency:treeで競合を確認し、必要に応じてdependencyManagementや推移的依存の除外を使うことが案内されています。(Microsoft Learn)
BOMを使う場合の例です。BOMのバージョンは、社内の検証済みバージョンまたは最新の公式情報に合わせて固定してください。
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-sdk-bom</artifactId>
<version>{検証済みのBOMバージョン}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-cosmos</artifactId>
</dependency>
</dependencies>特定バージョンを直接指定する場合は、次のようにします。
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-cosmos</artifactId>
<version>4.80.0</version>
</dependency>ただし、本番環境では「最新だから即反映」ではなく、固定バージョンを検証し、段階的に展開するのが基本です。
Javaランタイムを確認する
Azure Cosmos DB Java SDK v4のリソースページでは、最小サポートランタイムとしてJDK 8が案内されています。一方、クイックスタートのサンプルではJava 21が前提条件として挙げられているページもあります。つまり、SDK自体の最小要件と、サンプルアプリやテンプレートの実行要件は同じとは限りません。Dockerfile、CI/CD、App Service、AKS、Azure Container Appsなどの実行環境で、実際のJavaバージョンを確認してください。(Microsoft Learn)
管理者が確認すべき接続・ネットワーク設定
SDK更新後に問題が出やすいのは、コードよりも接続まわりです。特に高負荷環境、AKS、VM、Private Endpoint、NAT構成では、接続数、SNATポート、OSのopen files上限、リージョン設定を確認します。
クライアントはアプリケーション全体で使い回す
Azure Cosmos DB Java SDK v4のパフォーマンスガイドでは、Cosmos DBクライアントはスレッドセーフで、効率的な接続管理とアドレスキャッシュを行うため、アプリケーションのライフタイム中は単一インスタンスを使うことが強く推奨されています。リクエストごとにCosmosClientを作成すると、接続数の増加、レイテンシ悪化、SNATポート枯渇の原因になります。(Microsoft Learn)
悪い例です。
public Item find(String id, String pk) {
CosmosClient client = new CosmosClientBuilder()
.endpoint(endpoint)
.key(key)
.buildClient();
return client.getDatabase("db")
.getContainer("items")
.readItem(id, new PartitionKey(pk), Item.class)
.getItem();
}良い例です。
public class CosmosRepository {
private final CosmosContainer container;
public CosmosRepository(CosmosClient client) {
this.container = client.getDatabase("db").getContainer("items");
}
public Item find(String id, String pk) {
return container.readItem(id, new PartitionKey(pk), Item.class).getItem();
}
}Direct mode、Gateway mode、リージョン指定を確認する
Azure Advisorのパフォーマンス推奨事項では、Cosmos DB .NETまたはJava SDKがGateway modeを使用している場合、低レイテンシと高いスケーラビリティのために直接接続へ切り替える推奨が表示されることがあります。Direct modeを採用する場合は、ネットワーク経路、ファイアウォール、Private Endpoint、VNet、SNAT、OS制限を合わせて確認します。(Microsoft Learn)
また、複数リージョン構成ではpreferredRegions、endpointDiscoveryEnabled、excludedRegions、しきい値ベースの可用性戦略などを整理します。パフォーマンスガイドでは、しきい値ベースの可用性戦略により、preferredRegionsで定義されたセカンダリリージョンへ並列読み取りを行い、最も速い応答を採用できると説明されています。(Microsoft Learn)
429、CPU、SNAT、open filesを監視する
トラブルシューティングガイドでは、ポータルメトリックで429が多い場合はスロットリングを確認し、低スループットや高レイテンシではアプリをCosmos DBアカウントと同じリージョンで動かすこと、CPU使用率が高い場合はホスト増強や分散を検討することが案内されています。また、Linuxではopen files上限が接続数に影響し、Azure VMではSNATポート枯渇も接続問題の原因になります。(Microsoft Learn)
開発者が確認すべき実装上の注意点
Async APIでNettyのイベントループをブロックしない
v4のAsync APIはNettyの非ブロッキングI/Oを利用します。パフォーマンスガイドでは、CPU負荷の高い処理やブロッキングI/OをNettyのイベントループスレッド上で実行すると、デッドロックやスループット低下を招く可能性があると説明されています。重い処理はpublishOnなどで適切なSchedulerへ切り替えます。(Microsoft Learn)
避けたい例です。
container.createItem(item).subscribe(response -> {
heavyCpuWork(); // Nettyイベントループ上で重い処理を実行する可能性がある
});改善例です。
container.createItem(item)
.publishOn(Schedulers.boundedElastic())
.subscribe(response -> {
heavyCpuWork();
});パーティションキーを明示する
ポイント読み取り、書き込み、更新、削除では、可能な限りパーティションキーを明示します。パフォーマンスガイドでも、ポイント書き込みではパーティションキーをAPI呼び出しに指定することが推奨されています。特にネストしたパーティションキーを使っているコンテナーでは、SDK更新後にreadMany、readAllItems、クエリの結果を重点的に検証してください。(Microsoft Learn)
container.createItem(
item,
new PartitionKey(item.getTenantId()),
new CosmosItemRequestOptions()
);カスタムシリアライザーとJackson設定をテストする
v4.80.0では、CustomItemSerializerが内部SDKクエリ構造に誤って適用される問題や、SqlParameter、upsertItemでのシリアライザー適用に関する修正が含まれています。独自のObjectMapper、日付型、Enum、null除外、フィールド命名規則を使っている場合は、CRUDだけでなく、ORDER BY、GROUP BY、集計、DISTINCT、Hybrid Searchのクエリもテストしてください。(GitHub)
診断ログと可観測性を更新計画に入れる
SDK更新の成否は、例外が出ないだけでは判断できません。レイテンシ、RU消費、429、サブステータスコード、リージョンルーティング、再試行、接続タイムアウトを観測できる状態で展開します。
Java SDK v4では、CosmosDiagnosticsをレスポンスや例外から取得できます。また、v4.43.0以降では、一定条件を満たすリクエストやエラーについてCosmos Diagnosticsの自動ログ出力をサポートし、レイテンシ、リクエストチャージ、ペイロードサイズなどのしきい値を設定できます。(Microsoft Learn)
更新前後で最低限比較したい指標は次の通りです。
| 指標 | 見る理由 |
|---|---|
| 平均・p95・p99レイテンシ | 接続方式、リージョン、Async処理の影響を見る |
| RU消費量 | Query Advisor、インデックス、クエリ変更の効果を見る |
| 429件数 | スループット不足、リトライ、バースト時の挙動を見る |
| 408、タイムアウト、接続例外 | ネットワーク、SNAT、Direct mode設定を確認する |
| CPU、メモリ、スレッド数 | Nettyイベントループのブロックやログ過多を検出する |
| CosmosDiagnostics | 失敗時のリージョン、リトライ、サブステータスを追跡する |
展開前のテスト観点
SDK更新は、依存関係の更新、コード変更、ネットワーク挙動の変化が同時に起こりやすいため、通常の単体テストだけでは不十分です。次の観点を検証環境で確認してください。
| テスト項目 | 具体的に確認すること |
|---|---|
| CRUD | create、read、replace、upsert、patch、deleteが期待通り動くか |
| クエリ | WHERE、ORDER BY、GROUP BY、集計、DISTINCT、ページング、継続トークン |
| パーティションキー | 単純パス、ネストしたパス、存在しない値、ホットパーティション |
| Change Feed | リース、再起動、スケールアウト、パーティション分割・マージ後の再開 |
| 認証 | アカウントキー、Microsoft Entra ID、Managed Identity、権限不足時の挙動 |
| 高負荷 | 429、バックオフ、CPU、スレッド、接続数、SNAT、open files |
| リージョン障害想定 | preferredRegions、excludedRegions、フェイルオーバー時の読み取り・書き込み |
| ロールバック | 旧バージョンへ戻した場合にデータ・リース・設定が破綻しないか |
SDK更新後に429が増えた場合は、単純にSDKが悪いと判断せず、RU不足、クエリ変化、ページサイズ、インデックス、リトライ間隔、クライアント側の並列度を切り分けます。トラブルシューティングガイドでは、429はプロビジョニング済みスループットを消費したことを示し、サーバー指定のRetry-After間隔を尊重することが重要とされています。(Microsoft Learn)
移行・更新で失敗しやすいポイント
古い公式サンプルをそのまま使ってしまう
azure-documentdbのサンプルを見つけても、新規開発ではそのまま採用しないでください。公式参照ページに古い依存関係例が残っている場合でも、現行の移行先はcom.azure:azure-cosmosです。Azure SDKの非推奨リストでも、azure-documentdbはcom.azure/azure-cosmosへの置き換え対象として示されています。(GitHub)
v4へ上げたのにクライアントを毎回生成する
SDK v4ではクライアントの使い回しが重要です。DIコンテナ、Spring Bean、アプリケーション起動時の初期化などで単一インスタンスを管理し、リクエスト単位で生成しないようにします。
Async APIの中でブロッキング処理をする
block()の多用や、subscribe()内でCPU負荷の高い処理を直接実行すると、Async APIの利点を潰してしまいます。高スループットを狙う場合は、Reactive処理、Scheduler、バックプレッシャー、ログ出力の設計を合わせて見直します。
接続方式だけ変えてネットワークを見ない
Direct modeは低レイテンシやスケーラビリティの面で有利なことがありますが、ネットワーク要件を無視して切り替えると、ファイアウォール、SNAT、Private Endpoint、OS制限で障害が出ます。接続方式を変えるときは、アプリ、ネットワーク、Azure Cosmos DBアカウントの設定をまとめて確認します。
Spring Data Cosmosの推移的依存を見落とす
アプリのpom.xmlにazure-cosmosが直接書かれていなくても、azure-spring-data-cosmosや社内共通ライブラリが推移的に読み込んでいることがあります。依存ツリーで実際のバージョンを確認し、Spring BootやAzure SDK BOMとの整合性を取ってください。
管理者・開発者が次に取るべき行動
最初の一歩は、全Javaアプリの依存関係を棚卸しして、com.azure:azure-cosmos v4系、旧SDK、Spring Data経由の利用を分類することです。次に、旧SDKが見つかったアプリはv4移行計画を作り、すでにv4を使っているアプリはリリースノートを見て、v4.75.0未満や古い4.xを優先的に更新候補にします。
更新時は、CosmosClientの使い回し、Direct/Gateway mode、preferredRegions、診断ログ、429、SNAT、open files、カスタムシリアライザー、Change Feedを必ず確認してください。SDKは「入れ替えれば終わり」ではなく、接続・可観測性・展開手順まで含めて検証することで、Azure Cosmos DBの性能改善と信頼性向上を安全に取り込めます。
コメント