MENU

Azure SDKのMongoCluster更新まとめ：.NET生成PRで変わる点と確認ポイント

Azure

2026年5月5日のAzure SDK関連更新として確認すべきポイントは、Azure.ResourceManager.MongoCluster の.NET管理SDKが、Microsoft.DocumentDB/MongoCluster の新しい 2026-02-01-preview API仕様に合わせて再生成される動きです。すぐ本番コードを書き換えるというより、MongoClusterを.NET SDKで作成・更新しているチームは、APIバージョン、ネットワーク設定、長時間実行操作の扱い、テストコードへの影響を確認するのが現実的な対応です。

特に注意したいのは、新たに追加される networkBypassMode です。名前だけ見ると単なるネットワーク設定に見えますが、AzureCosmosDB を指定するとAzure Cosmos DBサービスによるネットワーク制限のバイパスを許可する意味を持つため、セキュリティ設計や監査方針とセットで確認する必要があります。PRはSDK生成のAutoPRであり、NuGetの公開済み安定版やMicrosoft Learn上の現在のAPIリファレンスと完全に同じ状態とは限りません。

目次

Azure SDK documentation updateで確認すべき結論

今回の Azure SDK documentation update: [AutoPR Azure.ResourceManager.MongoCluster]-generated-from-SDK Generation - .NET-6240123 は、Azure SDK for .NETの Azure.ResourceManager.MongoCluster を対象にした管理プレーンSDKの更新です。GitHub上のPRでは、Azure/azure-sdk-for-net の main ブランチへ1コミットを取り込むAutoPRとして表示され、対象ブランチは sdkauto/Azure.ResourceManager.MongoCluster-6240123 です。PR本文には、生成元として specification/mongocluster/resource-manager/Microsoft.DocumentDB/MongoCluster/tspconfig.yaml と、SpecRepo側のCommitSHA b0a55df5d0486a2faa05a3c93b2b90da6cce081b が記載されています。(GitHub)

実務上の結論は次のとおりです。

確認項目変更内容実務での見方
対象SDKAzure.ResourceManager.MongoClusterAzure Cosmos DB for MongoDB vCoreのクラスター、Firewall rule、Private endpoint connectionなどを管理する.NET向けSDK
API仕様2026-02-01-preview への対応Preview APIのため、本番適用前にリージョン、テナント、運用ポリシーで利用可否を確認
既定APIバージョン2025-09-01 から 2026-02-01-preview へ生成物上で更新明示的にAPIバージョンを固定していないコードでは、将来のSDK更新時に挙動差が出る可能性
新規プロパティnetworkBypassModeネットワーク制限のバイパス可否に関わるため、セキュリティレビューが必要
LRO処理CreateOrUpdateの最終状態取得方法に変更WaitUntil.Completed や独自ポーリング処理のテストを確認
影響範囲管理プレーン中心MongoDBアプリの通常接続処理だけなら直接影響は限定的

関連するAzure REST API仕様側のPRでは、Microsoft.DocumentDB/MongoCluster に 2026-02-01-preview APIバージョンを追加し、networkBypassMode プロパティと NetworkBypassMode union typeを追加したことが記載されています。また、APIViewではSwagger、Go、Python、JavaScript、Java向けのAPIレビューも作成されており、仕様変更は.NETだけに閉じない可能性があります。(GitHub)

何が変わったのか

既定のREST APIバージョンが2026-02-01-previewに更新される

今回の生成物では、metadata.json の Microsoft.DocumentDB APIバージョンが 2025-09-01 から 2026-02-01-preview に変更されています。PRのファイル差分上でもこの変更が確認できます。(GitHub)

これは単なる文字列変更ではありません。Azure.ResourceManager系SDKでは、明示的なAPIバージョン指定がない場合、生成コード側の既定バージョンがRESTリクエストに使われます。実際、生成後の MongoClusterCollection では、MongoCluster関連のRESTクライアント生成時に 2026-02-01-preview がフォールバック値として使われています。(GitHub)

ただし、この記事執筆時点で公開されているMicrosoft Learnの MongoClusterResource.Update APIページでは、既定APIバージョンとして 2025-09-01 が表示されています。つまり、PR上の生成物、ドキュメント反映、NuGet公開版の状態はタイミングによってずれる可能性があります。(Microsoft Learn)

このため、SDK更新時は「PRに出ているから本番で使える」と判断せず、次の順に確認してください。

確認対象確認する内容
NuGetAzure.ResourceManager.MongoCluster の公開済みバージョン
Microsoft LearnAPIリファレンスの既定APIバージョン
GitHub PR変更内容、マージ状況、生成元Spec
実行環境対象リージョンとサブスクリプションでPreview APIが利用可能か
CI/CDSDK更新後に既存の作成・更新・削除テストが通るか

networkBypassModeがMongoClusterのモデルに追加される

もっとも実務影響が出やすい変更は、networkBypassMode の追加です。生成後の .NET モデルでは、MongoClusterProperties と MongoClusterUpdateProperties に NetworkBypassMode プロパティが追加されています。説明には、AzureCosmosDB に設定するとAzure Cosmos DBサービスがネットワーク制限をバイパスできる旨が記載されています。(GitHub)

また、新しい MongoClusterNetworkBypassMode 型には、少なくとも次の値が定義されています。(GitHub)

値意味判断の目安
Noneネットワークバイパスを有効にしないゼロトラスト、Private Endpoint中心、厳格なネットワーク制限を優先する場合
AzureCosmosDBAzure Cosmos DBサービスによるネットワーク制限のバイパスを許可サービス連携上どうしても必要な場合に、ネットワーク設計・監査・承認フローを確認してから使う

ここで避けたいのは、「新しい値が追加されたから有効化しておく」という対応です。networkBypassMode は可用性や連携のための設定である一方、ネットワーク制御の例外を作る設定でもあります。特に本番環境では、ファイアウォールルール、Private Endpoint、Azure Policy、監査ログ、変更承認のルールと一緒に扱うべきです。

更新処理で既存設定を変えたくない場合は、PATCHリクエストで NetworkBypassMode を明示的に設定しない方針を検討してください。反対に、意図的に制御したい場合は、コード上で値を明示し、変更後にGETで実際のリソース状態を確認するのが安全です。

var patch = new MongoClusterPatch
{
    Properties = new MongoClusterUpdateProperties
    {
        NetworkBypassMode = MongoClusterNetworkBypassMode.None
    }
};

await mongoCluster.UpdateAsync(WaitUntil.Completed, patch);

上記は実装イメージです。実際に使う前に、利用中のSDKバージョンで該当プロパティが公開されているか、対象APIバージョンでサポートされているかを確認してください。

CreateOrUpdateのLRO最終状態取得がOriginalUriになる

MongoClusterの作成・更新は長時間実行操作、いわゆるLROとして扱われます。今回の生成後コードでは、CreateOrUpdate と CreateOrUpdateAsync の操作生成時に OperationFinalStateVia.OriginalUri が使われています。(GitHub)

通常のSDK利用では、次のように WaitUntil.Completed を使っていれば大きな変更を意識しないケースが多いでしょう。

ArmOperation<MongoClusterResource> operation =
    await collection.CreateOrUpdateAsync(
        WaitUntil.Completed,
        mongoClusterName,
        data);

ただし、次のような実装では確認が必要です。

実装パターン確認ポイント
独自にLROのHTTPレスポンスを検査しているAzure-AsyncOperation や Location ヘッダー前提の処理になっていないか
テストでレスポンスURLを固定しているモックの最終状態取得URLが実コードと合っているか
SDKの内部レスポンスをログ・監査に使っている作成完了後に取得されるリソース表現が想定どおりか
失敗時リトライを独自実装しているWaitUntil.Started と Completed の使い分けが崩れていないか

LROの違いは、正常系では気づきにくく、異常系やモックテストで初めて問題になることがあります。SDK更新後は、作成、更新、キャンセル、タイムアウト、再実行のテストを一度走らせておくと安全です。

誰が対応すべきか

今回のAzure SDK更新は、すべてのAzure利用者に影響するものではありません。優先して確認すべきなのは、Azure Cosmos DB for MongoDB vCoreのMongoClusterを、.NET SDKや自動化スクリプトから管理しているチームです。

対象者・チーム対応優先度理由
.NETで Azure.ResourceManager.MongoCluster を使っている開発者高APIバージョン、モデル、LRO処理の変更が直接関係する
MongoClusterをCI/CDから作成・更新しているSRE、DevOps担当高Preview APIやネットワーク設定変更でデプロイ失敗・設定差分が起きる可能性がある
Private Endpoint、Firewall、Public Network Accessを管理しているインフラ担当高networkBypassMode がネットワーク制限の例外設定になり得る
SDKのモック、ModelFactory、スナップショットテストを使っているテスト担当中生成モデルやFactoryの引数追加でテスト修正が必要になる可能性がある
Java、Python、JavaScript、Goの管理SDK利用者中今回のPRは.NET向けだが、元のAPI仕様変更は複数言語のAPIView対象になっている
MongoDBアプリのデータ読み書きだけをしているアプリ開発者低管理プレーンSDKの変更であり、通常のMongoDB接続コードへの直接影響は限定的

NuGet上の公開済み Azure.ResourceManager.MongoCluster では、安定版 1.0.0 が表示されており、インストールコマンドや対象フレームワークも確認できます。PRの生成内容と、実際にプロジェクトで取得されるパッケージは必ず分けて確認してください。([NuGet][8])

移行前に確認する手順

現在使っているSDKバージョンを確認する

まず、プロジェクトがどのバージョンの Azure.ResourceManager.MongoCluster を使っているか確認します。

Windowsの場合:

dotnet list package | findstr Azure.ResourceManager.MongoCluster

macOS、Linux、WSLの場合:

dotnet list package | grep Azure.ResourceManager.MongoCluster

Directory.Packages.props でCentral Package Managementを使っている場合は、次のような定義も確認してください。

<PackageVersion Include="Azure.ResourceManager.MongoCluster" Version="1.0.0" />

この時点で確認すべきことは、単に「最新版かどうか」ではありません。以下の3点を見ます。

確認内容判断基準
バージョン固定の有無固定していない場合、将来の復元時に意図せず更新される可能性がある
安定版かPreview版かPreview APIを使う場合は検証環境から適用する
依存関係の更新範囲Azure.ResourceManager や Azure.Core の更新も同時に入るか確認する

APIバージョンを固定するか判断する

今回のように生成SDKの既定APIバージョンが変わる場合、もっとも安全なのは「アプリごとにどのAPIバージョンを使うか」を明示的に決めることです。

Azure.ResourceManagerの ArmClientOptions.SetApiVersion は、指定したリソースタイプに対して利用するAPIバージョンを設定するメソッドです。Microsoft Learnでは、利用可能なAPIバージョンは対象プロバイダー名前空間の情報から確認できると説明されています。(Microsoft Learn)

たとえば、既存挙動を維持したい検証では次のようにAPIバージョンを固定できます。

var options = new ArmClientOptions();

options.SetApiVersion(
    MongoClusterResource.ResourceType,
    "2025-09-01");

var armClient = new ArmClient(
    credential,
    subscriptionId,
    options);

一方、新しいPreview APIの検証を行う場合は、検証環境で 2026-02-01-preview を指定し、作成・更新・削除・再取得まで一連の動作を確認します。

var options = new ArmClientOptions();

options.SetApiVersion(
    MongoClusterResource.ResourceType,
    "2026-02-01-preview");

var armClient = new ArmClient(
    credential,
    subscriptionId,
    options);

本番では、次の条件を満たしてからPreview APIの利用を検討してください。

条件確認内容
サービス側の対応対象サブスクリプション、リージョン、リソースプロバイダーでAPIが利用できる
SDK側の対応利用中パッケージに該当モデルとAPIバージョンが含まれている
運用側の承認Preview API利用が社内ルール、監査、変更管理に合っている
ロールバック手順旧APIバージョンや旧パッケージへ戻せる
テスト結果作成、更新、削除、GET、List、LRO完了待ちが通る

networkBypassModeの扱いをセキュリティ担当と確認する

networkBypassMode は、開発者だけで決めるより、インフラ・セキュリティ担当と一緒に判断した方がよい項目です。

確認の流れは次のとおりです。

手順やること完了条件
現状把握既存MongoClusterのPublic Network Access、Firewall rule、Private Endpointを確認どの経路で管理・接続しているか説明できる
変更要否判断AzureCosmosDB のバイパスが本当に必要か確認必要なユースケースと承認者が明確
実装PATCHまたはCreate時に値を明示するか、未指定のままにするか決めるコードレビューで意図が分かる
検証設定後にGETで実際の値を確認期待値と実リソース状態が一致
監査変更履歴、デプロイログ、承認記録を残す後から「誰が何のために変更したか」追跡できる

失敗しやすいのは、環境ごとの違いを無視して同じ設定を横展開するケースです。開発環境では問題なくても、本番環境ではPrivate Endpoint前提、特定サブネット限定、Azure Policy適用中といった制約があることがあります。

テストコードとModelFactory利用を確認する

今回のPRでは、ArmMongoClusterModelFactory も更新対象に含まれています。PRのレビュー概要では、Model Factoryのメソッドが新しいプロパティに合わせて拡張され、互換用のshimも追加されると説明されています。(GitHub)

通常のアプリコードより、次のようなテストコードで影響が出やすくなります。

テストの種類起きやすい問題対応
ModelFactoryでリソースを生成する単体テスト引数や生成結果の差分Factory呼び出しと期待値を更新
JSONスナップショットテストnetworkBypassMode の有無で差分新プロパティを意図的に含めるか除外する
LROモックOriginalUri 前提の最終状態取得に合わないレスポンスURL、ステータス、完了後GETのモックを見直す
APIバージョン検証期待URLが 2025-09-01 のまま明示的に固定するか、新バージョンへ期待値を更新

特に、MongoClusterNetworkBypassMode は文字列から暗黙変換できる拡張可能なenum風の型として生成されています。将来、値が増える可能性を考えると、None と AzureCosmosDB だけを前提にした完全一致の分岐より、未知の値をログ出力して安全側に倒す実装が向いています。(GitHub)

string mode = cluster.Data.Properties.NetworkBypassMode?.ToString();

switch (mode)
{
    case "None":
        // バイパスなし
        break;

    case "AzureCosmosDB":
        // Azure Cosmos DBサービスのバイパス許可
        break;

    case null:
        // 未設定。既定値や既存値を確認
        break;

    default:
        // 将来追加された値の可能性。監査ログに記録して確認
        logger.LogWarning("Unknown network bypass mode: {Mode}", mode);
        break;
}

よくある疑問

すぐにSDKを更新する必要はあるか

本番で安定運用している環境では、すぐ更新するよりも、まず検証環境で確認するのが安全です。今回の情報はSDK生成PRに基づくものであり、NuGet公開版、Microsoft LearnのAPIリファレンス、実際のサービス提供状態が同時に切り替わるとは限りません。

対応の優先順位は次のように考えると判断しやすくなります。

状況推奨対応
MongoClusterを.NET SDKで自動作成・更新している検証環境でPR内容と将来のSDK更新影響を確認
APIバージョンを固定していない固定するか、新バージョン移行計画を作る
ネットワーク制限を厳格に管理しているnetworkBypassMode の扱いをセキュリティ担当と確認
MongoDBアプリからデータアクセスしているだけ直接対応は不要な可能性が高い
JavaやPythonなど他言語SDKを使っている各言語SDKの生成PRやリリースノートを別途確認

既存コードは壊れるのか

新規プロパティの追加自体は、多くの場合すぐにコンパイルエラーを起こすものではありません。注意すべきなのは、既定APIバージョンの変更、LROの最終状態取得、テスト期待値の差分です。

たとえば、SDKの通常メソッドだけを使い、APIバージョンも明示していない場合、将来のパッケージ更新でRESTリクエストの api-version が変わる可能性があります。これにより、サービス側のPreview API対応状況によっては、検証環境と本番環境で結果が変わることがあります。

networkBypassModeは設定した方がよいのか

原則として、必要性が明確でないなら設定しない、または None を明示する方が安全です。AzureCosmosDB は、Azure Cosmos DBサービスにネットワーク制限のバイパスを許可する意味を持つため、単なる利便性設定として扱うべきではありません。

判断基準は次のように整理できます。

判断軸None が向くケースAzureCosmosDB を検討するケース
セキュリティ方針ネットワーク例外を最小化したいサービス連携に必要な例外を承認済み
監査例外設定を避けたい変更理由と承認記録を残せる
接続設計Private Endpoint、Firewall中心Azure Cosmos DBサービス連携上の要件がある
運用既存設定を維持したい設定変更後の監視・検証体制がある

Microsoft Learnの表示とPR内容が違う場合はどちらを信じるべきか

用途によって見るべき場所が違います。実装に使うなら、手元で参照しているNuGetパッケージとMicrosoft LearnのAPIリファレンスを優先します。将来の変更を先読みするなら、GitHub PRとAzure REST API仕様を確認します。

目的優先して見る場所
今すぐ実装するNuGet、Microsoft Learn、手元のIntelliSense
将来の変更を把握するAzure SDK for .NETのPR、azure-rest-api-specsのPR
API仕様の意図を確認するTypeSpec、Swagger、APIView
本番適用を判断する公式リリースノート、サービスドキュメント、社内運用基準

実務での対応チェックリスト

今回のAzure SDK更新に対して、現場では次の順に確認すると無駄がありません。

チェック内容対応済みの判断
SDK利用有無Azure.ResourceManager.MongoCluster を使っているかプロジェクト内検索で確認済み
パッケージバージョンNuGetの現在バージョンと固定状況dotnet list package で確認済み
APIバージョン2025-09-01 を維持するか、2026-02-01-preview を検証するか方針をコード・設定に反映済み
ネットワーク設定networkBypassMode を設定する必要があるかセキュリティ担当と合意済み
LROテストCreateOrUpdateの完了待ち、失敗時、再実行を確認CIで通過済み
モック・FactoryModelFactoryやJSONスナップショットの差分テスト期待値を更新済み
ロールバック旧パッケージ、旧APIバージョンに戻せるか手順と担当者が明確
監視SDK更新後のエラー、HTTPステータス、設定差分を監視ログ・アラートが設定済み

この更新は、単に「Azure SDKのドキュメントが変わった」というより、MongoCluster管理SDKが新しいPreview API仕様へ追随するための準備と捉えるのが適切です。まずは手元のパッケージバージョンとAPIバージョン固定の有無を確認し、networkBypassMode を使う可能性がある環境では、ネットワーク設計とセキュリティレビューを先に済ませてください。そのうえで検証環境にSDK更新を適用し、作成・更新・削除・再取得・LRO完了待ちの一連の動作を確認するのが、もっとも安全な進め方です。

[8]: https://www.nuget.org/packages/Azure.ResourceManager.MongoCluster/1.0.0 “
NuGet Gallery
| Azure.ResourceManager.MongoCluster 1.0.0
“

Azure
.NET Cosmos DB ARM Azure SDK Azure.ResourceManager.MongoCluster

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次