2026年5月5日公開・更新の「Azure SDK documentation update: Increment versions for cosmos releases」で確認すべき結論は、Azure SDK for Java の Azure Cosmos DB 関連パッケージで、安定版リリース後のバージョン整合と次期 beta サイクルへの更新が行われたという点です。すべての利用者が今すぐ本番環境を変更する必要はありませんが、azure-cosmos、Spring 向け Cosmos 連携、Cosmos Spark Connector、Cosmos Kafka Connect、Cosmos Encryption を使っている開発チームは、依存関係の解決結果とテスト範囲を確認しておくべきです。該当PRは Azure SDK for Java リポジトリの Pull Request #49034 で、2026年5月4日に main ブランチへマージされています。(GitHub)
Azure SDK documentation update: Increment versions for cosmos releasesとは
今回の「Increment versions for cosmos releases」は、Azure SDK の中でも Java 向け Cosmos 関連パッケージのバージョン番号を次のリリース状態に進める更新です。
ポイントは、単に「新しいSDKが出たので全員がbetaへ上げる」という話ではないことです。Azure SDK のリリースポリシーでは、パッケージをリリースした後、ソース管理上のバージョンを次の開発サイクルへ進める運用があります。Javaの場合、安定版リリース後は次の -beta.1 に進む形が示されています。(Azure)
つまり、今回の更新は大きく分けると次の2つです。
| 観点 | 内容 | 読者が見るべきポイント |
|---|---|---|
| 安定版利用者向け | Spring関連やサンプル側の azure-cosmos 依存が 4.79.1 から 4.80.0 へ更新 | 本番利用ではまず 4.80.0 を検討する |
| SDK開発・検証向け | azure-cosmos 本体や関連パッケージが次期 -beta.1 に進む | betaを本番へ無条件適用しない |
| 関連コネクタ | Spark、Kafka Connect、Encryption も次期betaへ更新 | コネクタ利用環境では依存関係の衝突を確認する |
| ドキュメント・リリース管理 | CHANGELOG に次期 Unreleased セクションを追加 | 新機能の中身は後続のCHANGELOG更新も確認する |
何が変わったのか
PR #49034 の差分では、Cosmos関連パッケージのバージョン管理ファイルと、複数の pom.xml、CHANGELOG が更新されています。主な変更は次の通りです。(GitHub)
| 対象パッケージ・領域 | 変更前 | 変更後 | 意味 |
|---|---|---|---|
com.azure:azure-cosmos | 4.79.1 または 4.80.0 | 4.80.0 または 4.81.0-beta.1 | 安定版は 4.80.0、main上の次期開発版は 4.81.0-beta.1 へ |
| Spring関連の Cosmos 依存 | 4.79.1 | 4.80.0 | Spring Cloud Azure / Spring Data Cosmos 周辺で安定版Cosmos SDKを更新 |
azure-cosmos-encryption | 2.29.0 | 2.30.0-beta.1 | Encryptionプラグインが次期betaサイクルへ |
azure-cosmos-kafka-connect | 2.10.0 | 2.11.0-beta.1 | Kafka Connectコネクタが次期betaサイクルへ |
| Cosmos Spark Connector群 | 4.48.0 | 4.49.0-beta.1 | Spark 3.3、3.4、3.5、4.0、4.1向けコネクタが次期betaへ |
| テスト・ベンチマーク関連 | 4.80.0 など | 4.81.0-beta.1 など | SDK内部の検証環境も次期バージョンに追従 |
ここで重要なのは、4.80.0 と 4.81.0-beta.1 を混同しないことです。Microsoft Learn の Azure Cosmos DB Client Library for Java ページでは、本稿確認時点で version 4.80.0 として案内されています。安定版を使う通常のアプリケーションでは、まず 4.80.0 の変更内容と互換性を確認するのが現実的です。(Microsoft Learn)
対応が必要な人、様子見でよい人
今回の Azure SDK documentation update は、Cosmos DB を使っているJava系プロジェクトに関係します。ただし、影響の大きさは利用形態によって異なります。
| 利用状況 | 対応優先度 | 理由 |
|---|---|---|
com.azure:azure-cosmos を直接指定しているJavaアプリ | 高 | pom.xml やGradleで固定しているバージョンを確認すべき |
Azure SDK BOMで azure-cosmos を管理している | 中 | BOMのバージョン次第で解決されるSDKが変わる |
| Spring Cloud Azure / Azure Spring Data Cosmosを使っている | 中〜高 | Spring側の推移的依存で azure-cosmos が入る可能性がある |
| Cosmos Spark Connectorを使うDatabricks/Spark環境 | 高 | Spark・Scalaの組み合わせとコネクタのartifact名が重要 |
| Cosmos Kafka Connectを使っている | 高 | コネクタと基盤SDKの組み合わせを検証する必要がある |
| Cosmos Encryptionプラグインを使っている | 高 | 暗号化・復号化処理は回帰テストが必須 |
| .NET、Python、JavaScriptだけでCosmos DBを使っている | 低 | 今回のPRは Java SDK リポジトリのCosmos関連更新が中心 |
| Cosmos DBを使っていないAzure SDK利用者 | 低 | 直接の影響は基本的にない |
4.80.0で確認したい主な変更点
azure-cosmos の 4.80.0 では、Query Advisor、追加ヘッダー、readManyByPartitionKeys、Change Feed関連、未知のRNTBDトークンを扱うSDK capabilityなどが追加されています。また、ネストしたパーティションキーでの readMany / readAllItems の結果不正、スループット制御で不要な権限が必要になる問題、初回クラスロード時のJVMデッドロック、CustomItemSerializer 周りの不具合なども修正されています。(GitHub)
実務で特に確認したいのは次の観点です。
| 確認項目 | なぜ重要か | 具体的なチェック例 |
|---|---|---|
| クエリ結果 | ネストしたパーティションキーや集計系クエリの修正が含まれる | /address/city のようなパーティションキーを持つコンテナで検索・集計を再実行 |
| カスタムシリアライザ | CustomItemSerializer 関連の修正が複数ある | upsertItem、ORDER BY、GROUP BY、DISTINCT、集計クエリをテスト |
| Change Feed | merged partitionsやstartFrom関連の変更がある | 分割・マージ後のChange Feed Processorの継続処理を確認 |
| 認証・権限 | AAD利用時のスループット制御の挙動修正がある | 最小権限のマネージドIDで読み書き・スループット制御を検証 |
| HTTP/2・Nettyログ | 接続リセット時のログや例外処理の改善がある | Gateway/Directの接続方式ごとに負荷テストを実施 |
| 非Azure環境 | ClientTelemetry初期化失敗の修正がある | ローカル、CI、オンプレ実行環境でクライアント生成を確認 |
betaへ上げるべきか、安定版に留めるべきか
本番環境では、明確な理由がない限り 4.81.0-beta.1 へ急いで上げる必要はありません。Azure SDK のリリースポリシーでは、betaは早期検証やフィードバックのために提供される位置づけで、beta間では破壊的変更が起こり得るとされています。(Azure)
判断基準は次の通りです。
| 判断 | 推奨するバージョン方針 | 例 |
|---|---|---|
| 本番運用中の一般的なJavaアプリ | 安定版 4.80.0 を検証して採用 | Web API、バッチ、業務アプリ |
| 新機能を早期検証したい | 検証環境のみ 4.81.0-beta.1 を試す | PoC、性能検証、preview機能の確認 |
| Spark/Kafka/Encryptionの互換性検証をしたい | betaを isolated な検証環境で試す | Databricksジョブ、Kafka Connectクラスタ |
| 障害対応中で安定性を優先したい | 既存安定版または 4.80.0 に限定 | 本番ホットフィックス、短期リリース |
| 古いJava SDK v2系を使っている | v4への移行計画を立てる | 古い同期Java SDKからの移行 |
Azure Cosmos DB Java SDK v4 は、同期APIと非同期APIを1つのMaven artifactで提供し、JDK 8以上が前提です。古いv4未満のSDKを使っている場合は、単純なパッチ更新ではなく、v4への移行ガイドを確認する必要があります。(Microsoft Learn)
まず確認すべき依存関係
最初にやるべきことは、アプリケーションが実際にどのバージョンのCosmos関連ライブラリを解決しているかを確認することです。pom.xml に書かれているバージョンと、実際にビルドで解決されるバージョンが一致しているとは限りません。
Mavenなら、次のコマンドで確認できます。
mvn dependency:tree -Dincludes=com.azure:azure-cosmos
mvn dependency:tree -Dincludes=com.azure:azure-cosmos-encryption
mvn dependency:tree -Dincludes=com.azure.cosmos.spark
mvn dependency:tree -Dincludes=com.azure.cosmos.kafkaGradleなら、次のように依存関係を確認します。
./gradlew dependencies --configuration runtimeClasspath
./gradlew dependencyInsight --dependency azure-cosmos --configuration runtimeClasspath確認時は、次の3点をメモしておくと移行判断がしやすくなります。
| 確認すること | 見る場所 | 判断のポイント |
|---|---|---|
| 直接依存か推移的依存か | pom.xml、dependency:tree | 直接依存なら自分でバージョン更新が必要 |
| BOMで管理しているか | dependencyManagement | BOMを使う場合は個別バージョン指定を避ける |
| 複数バージョンが混在していないか | 依存関係ツリー | Spark/Kafka/Encryptionで混在しやすい |
Microsoft Learn の手順でも、GA版ライブラリを利用する場合は azure-sdk-bom を dependencyManagement に入れ、個別dependency側ではversionタグを省く形が案内されています。個別に固定する場合は、BOMとの二重管理にならないよう注意が必要です。(Microsoft Learn)
Mavenでの設定例
azure-cosmos を直接指定している場合、安定版を明示するなら次のように指定します。
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-cosmos</artifactId>
<version>4.80.0</version>
</dependency>BOMで管理する場合は、dependency側にversionを書かない構成にします。
<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>避けたいのは、BOMで管理しているにもかかわらず、一部のCosmos関連パッケージだけ個別にbetaへ上げることです。特に azure-cosmos-encryption、azure-cosmos-kafka-connect、Cosmos Spark Connector は、内部で azure-cosmos に依存します。片方だけ更新すると、ビルドは通っても実行時に想定外の動作やクラス競合が起きる可能性があります。
Spark Connector利用時の注意点
Cosmos Spark Connectorを使っている場合は、通常のJavaアプリよりも確認項目が増えます。今回の差分では、Spark 3.3、3.4、3.5、4.0、4.1向けの複数artifactが 4.49.0-beta.1 に進められています。(GitHub)
特に注意すべきなのは、artifact名に含まれるSpark/Scalaの組み合わせです。
<artifactId>azure-cosmos-spark_3-5_2-12</artifactId>この例では、Spark 3.5系、Scala 2.12系向けであることがartifact名に含まれています。DatabricksやSparkクラスタ側のScalaバージョンと合わないartifactを入れると、コンパイル時ではなくジョブ実行時にエラーになることがあります。
確認すべき項目は次の通りです。
| 項目 | 確認内容 |
|---|---|
| Sparkバージョン | 3.3、3.4、3.5、4.0、4.1のどれか |
| Scalaバージョン | 2.12か2.13か |
| コネクタartifact | Spark/Scalaの組み合わせと一致しているか |
| クラスタ配布方法 | Maven coordinates、JAR配置、init scriptのどれで配布しているか |
| ジョブ検証 | 読み込み、書き込み、UPSERT、Change Feed、スキーマ推論を確認 |
Kafka ConnectとEncryption利用時の注意点
Cosmos Kafka Connectでは、コネクタ本体が 2.10.0 から 2.11.0-beta.1 に進み、内部の azure-cosmos 依存も 4.81.0-beta.1 へ更新されています。(GitHub)
Kafka Connect環境では、次の確認が必要です。
| 項目 | チェックポイント |
|---|---|
| Connector plugin path | 古いJARと新しいJARが同じディレクトリに混在していないか |
| Source/Sink設定 | connection string、key、AAD認証、database/container名が変わっていないか |
| 再処理リスク | offset管理、失敗時の再送、重複書き込みの扱い |
| ロールバック | 旧コネクタJARに戻せる配置手順があるか |
Encryptionプラグインでは、暗号化・復号化の処理結果が最優先の確認対象です。今回の差分では azure-cosmos-encryption が 2.30.0-beta.1 に進み、依存する azure-cosmos も次期betaへ更新されています。(GitHub)
検証では、既存データの読み取り、新規データの暗号化保存、キー管理設定、失敗時の例外メッセージを必ず確認してください。暗号化系の更新では、単にCRUDが成功するだけでなく、過去に保存したデータが復号できるかまで見る必要があります。
移行・更新時の実務チェックリスト
今回のAzure SDK更新に対応する際は、次の順番で進めると失敗しにくくなります。
| 手順 | 作業 | 完了条件 |
|---|---|---|
| 依存関係の棚卸し | dependency:tree や dependencyInsight でCosmos関連を確認 | 利用中のartifactとバージョンが一覧化されている |
| 更新方針の決定 | 安定版 4.80.0 か beta 検証かを決める | 本番・検証環境の方針が分かれている |
| ローカル検証 | 主要CRUD、クエリ、Change Feed、シリアライズを確認 | 既存テストが通る |
| ステージング検証 | 本番に近いRU、データ量、接続方式で試す | 429、408、410、5xx、遅延が悪化していない |
| ログ確認 | CosmosDiagnostics、Nettyログ、アプリログを確認 | 新しい例外や警告が増えていない |
| ロールバック準備 | 旧バージョンに戻す手順を用意 | 旧artifact・設定・手順が残っている |
| 本番反映 | 段階的に展開 | 影響範囲を限定して監視できている |
よくある失敗パターン
LATESTやバージョン範囲で意図せずbetaを拾う
MavenやGradleで曖昧な指定をしていると、意図しないバージョンが解決されることがあります。特にbetaを検証したい場合でも、検証環境だけに限定し、バージョンは明示的に固定してください。
避けたい指定例です。
<version>LATEST</version>推奨は、検証対象を明確にする指定です。
<version>4.80.0</version>Spring側の依存管理を無視して個別に上書きする
Spring Cloud AzureやAzure Spring Data Cosmosを使っている場合、azure-cosmos は推移的依存として入っていることがあります。個別に azure-cosmos だけを上書きすると、Spring側が想定している組み合わせから外れる場合があります。
まずは、利用しているSpring Cloud AzureやSpring Data Cosmosのリリースノート、BOM、依存関係ツリーを確認し、必要な場合だけ上書きします。
Spark ConnectorでScalaバージョンを取り違える
azure-cosmos-spark_3-5_2-12 と azure-cosmos-spark_3-5_2-13 は似ていますが、Scalaのバージョンが違います。クラスタと合わないartifactを指定すると、ジョブ実行時に NoClassDefFoundError や NoSuchMethodError のようなエラーが出ることがあります。
CHANGELOGの「Unreleased」を正式リリース済みと誤解する
PR #49034 では、複数のパッケージに次期バージョンの Unreleased セクションが追加されています。これは次のリリースに向けた枠であり、その時点で安定版として公開されたという意味ではありません。(GitHub)
この記事を読んだ後に取るべき行動
まずは、自分のプロジェクトで azure-cosmos や関連コネクタを使っているかを確認してください。直接依存している場合は、4.80.0 を検証対象にし、betaは検証目的に限定するのが安全です。Spring、Spark、Kafka Connect、Encryptionを使っている場合は、単体のSDKバージョンだけでなく、関連パッケージ全体の組み合わせを確認しましょう。
今回のAzure SDK documentation updateは、緊急の設定変更というより、Cosmos関連リリース後のバージョン整合と次期開発サイクルへの移行準備です。依存関係を見える化し、安定版とbetaの役割を分けて検証すれば、不要なアップデート事故を避けながら新しいCosmos SDKの改善を取り込めます。
コメント