Azure REST APIで「Azure REST API documentation update: MPG migration – mongocluster」を確認している人が最初に押さえるべき結論は、この更新がMongoClusterのRESTエンドポイントを直接大きく変えるものというより、Azure SDK生成設定、とくにTypeSpecとMongoCluster向けSDK表面の整理に関わる変更だという点です。PR #39360は2026年1月8日にmainへマージ済みですが、2026年5月5日にstartIpAddress / endIpAddressの命名スコープに関するレビューが入り、関連修正PR #42878へつながっています。REST APIを直接呼ぶだけなら影響は限定的と考えられますが、Azure SDK、CIでのSDK自動生成、MongoClusterのファイアウォール規則やPrivate Link関連コードを使っている場合は確認が必要です。(GitHub)
Azure REST APIのMPG migration – mongoclusterで確認すべき変更点
今回の更新対象は、Azure REST API仕様の正本として使われるAzure/azure-rest-api-specsリポジトリ内のMongoCluster関連設定です。同リポジトリはMicrosoft AzureのREST API仕様の canonical source と説明されており、仕様完了後にSDKやAPIリファレンス文書を生成する流れにも関係します。(GitHub)
PR #39360の説明では「API specificationではなくSDK configurationのみを変更する」趣旨が示されています。ただし、SDK Automationの仕組みでは、TypeSpecプロジェクトのtspconfig.yamlに設定された各言語エミッターをもとにSDK生成が行われ、生成後の変更検出では破壊的変更ラベルが付くことがあります。今回もAPIViewでTypeSpec、Python、JavaScript、JavaのAPIレビューが作成され、JavaScript SDKのbreaking changeラベルが付与されました。(GitHub)
主な変更は次の2ファイルです。
| 変更ファイル | 変更内容 | 実務上の見方 |
|---|---|---|
client.tsp | MongoCluster向けの@@clientName、操作名、モデル名、SubResource、@@alternateTypeなどを追加・調整 | C# SDKを中心に、生成されるクラス名・プロパティ名・操作名が変わる可能性を確認する |
tspconfig.yaml | C#向けの生成設定を新しい管理プレーン向けエミッター構成へ寄せる変更 | REST呼び出しよりもSDK生成・SDKパッケージ更新時の差分確認が重要 |
| 関連PR #42878 | startIpAddress / endIpAddressの@@clientNameをC#にスコープ限定 | Javaなど他言語SDKで不要なプロパティ名変更が起きないか確認する |
client.tspでは、FirewallRuleProperties.startIpAddressとFirewallRuleProperties.endIpAddressに対するクライアント名指定、Private Link関連の名前付け、Azure.ResourceManager.Models.SubResourceを使ったprivateEndpointの代替型指定などが確認できます。現在のmain上では、IPアドレス関連の命名指定は"csharp"にスコープされています。(GitHub)
影響を受けやすいのはREST直呼びよりSDK利用者
この更新で最も注意すべきなのは、api-version付きのRESTリクエストそのものよりも、生成されたAzure SDKの型名・プロパティ名・操作名です。
Azure REST APIを直接curl、PowerShell、独自HTTPクライアント、Terraform外部連携などで呼んでいる場合、確認すべきポイントはURI、HTTPメソッド、JSONプロパティ、api-versionです。一方、Azure SDKを使っている場合は、コード上のクラス名、メソッド名、プロパティ名、パッケージ更新時のコンパイルエラーが主な確認対象になります。
| 利用形態 | 影響度 | 確認すること |
|---|---|---|
| REST APIを直接呼んでいる | 低〜中 | api-version、リクエスト/レスポンスJSON、MongoClusterとFirewall Ruleのプロパティ名 |
| .NET / C# SDKを使っている | 中〜高 | Azure.ResourceManager.MongoClusterの型名、Private Link、Firewall Rule、SubResource周辺 |
| Java / JavaScript / Python / Go SDKを使っている | 中 | PR #42878後の生成差分、startIpAddress / endIpAddressが意図せず変わっていないか |
Azure CLIでaz cosmosdb mongoclusterを使っている | 中 | CLI拡張機能のバージョン、プレビュー機能であること、ファイアウォール規則操作 |
| CIでAzure SDKを自動生成している | 高 | tspconfig.yaml、生成ログ、breaking changeラベル、APIレビュー結果 |
Azure CLIのaz cosmosdb mongoclusterはMicrosoft Learn上でプレビューのコマンドグループとして案内されており、Mongo Clusterの作成、削除、一覧、取得、更新、ファイアウォール規則操作などを扱います。プレビュー機能を本番運用の自動化に使っている場合は、CLI拡張機能やSDK更新の影響を受けやすいため、バージョン固定と検証環境での再実行が現実的な対策です。(Microsoft Learn)
2026年5月5日のポイントはIPアドレスプロパティのスコープ修正
2026年5月5日に特に確認すべき点は、PR #39360で追加されたstartIpAddress / endIpAddressの命名指定が、当初は全言語に影響し得る形だったことです。関連PR #42878では、この未スコープの@@clientNameによりJava SDKで破壊的変更が起きるため、C#のみに限定する修正が行われたと説明されています。(GitHub)
これは小さな命名修正に見えますが、SDK利用者にとっては重要です。たとえばJavaやJavaScriptのコードで、これまでstartIpAddressというcamelCaseのプロパティ名を前提にしていた場合、生成設定の誤りでstartIPAddressのような形に変わると、コンパイルエラーやシリアライズ差分の原因になります。
実務では、次のように切り分けると確認が早くなります。
| 確認対象 | 見るべき差分 | 問題が出やすい場面 |
|---|---|---|
| ファイアウォール規則 | startIpAddress / endIpAddressのSDKプロパティ名 | IP制限を自動作成するバッチ、IaC補助スクリプト |
| C# SDK | StartIPAddressのようなC#向け命名 | 既存コードから新SDKへ更新するタイミング |
| Java / JS / Python / Go SDK | camelCaseが維持されているか | SDK再生成後のコンパイル、型定義チェック |
| JSONペイロード | REST上のプロパティ名が変わっていないか | SDKを使わずHTTPで直接送信している処理 |
重要なのは、「C#で読みやすい名前」と「REST JSON上のプロパティ名」と「他言語SDKのプロパティ名」を混同しないことです。SDK生成設定の変更は、言語ごとの開発体験を整えるために入ることがありますが、スコープを誤ると別言語の利用者に不要な破壊的変更を与える可能性があります。
MongoCluster利用者が確認すべき範囲
今回の更新で確認すべき範囲は、MongoClusterリソースを作成しているかどうかだけでは判断できません。ファイアウォール規則、Private Link、レプリカ、接続文字列、ユーザー操作など、SDK側で生成される操作名やモデル名に触れているかを見ます。
Microsoft LearnのPython SDKリファレンスでは、MongoCluster向け管理APIがAzure Cosmos DB for MongoDB vCoreのクラスターやファイアウォール規則などのCRUD機能を提供すると説明されています。また、Pythonクライアントの既定APIバージョンは2025-09-01として示されています。(Microsoft Learn)
.NET側でも、MongoClusterResource.Updateのリファレンスにリクエストパス/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/mongoClusters/{mongoClusterName}と既定APIバージョン2025-09-01が掲載されています。SDK利用者は、RESTのパスだけでなく、更新処理に渡すパッチ型や長時間実行操作の扱いも合わせて確認する必要があります。(Microsoft Learn)
まず検索すべきコード上の文字列
社内コードやGitHub Enterprise、Azure DevOps Reposで次の文字列を検索してください。
Microsoft.DocumentDB/mongoClusters
MongoCluster
mongocluster
azure-mgmt-mongocluster
@azure/arm-mongocluster
Azure.ResourceManager.MongoCluster
azure-resourcemanager-mongocluster
startIpAddress
endIpAddress
PrivateEndpointConnection
PrivateLink検索結果がREST呼び出しだけなら、まずapi-versionとJSONプロパティを確認します。SDKコードが見つかった場合は、パッケージ更新前後で型名・プロパティ名・メソッド名の差分を確認します。
移行・設定確認の手順
MongoCluster関連のAzure SDKやREST APIを運用で使っている場合は、次の順で確認すると手戻りを減らせます。
| 手順 | 作業 | 判断基準 |
| -: | —————— | ————————————————— |
| 1 | 利用形態を分類する | REST直呼び、SDK、CLI、IaC、CI生成のどれかを分ける |
| 2 | 対象コードを検索する | MongoCluster、startIpAddress、PrivateLinkなどがあるか |
| 3 | SDKパッケージの更新有無を確認する | package lock、NuGet、npm、Maven、pip、Go modulesを確認 |
| 4 | 生成差分を読む | 型名、操作名、プロパティ名、changelog、breaking changeを確認 |
| 5 | 検証環境で主要操作を実行する | 作成、取得、更新、削除、ファイアウォール規則、Private Linkを試す |
| 6 | 本番反映前にバージョン固定する | SDK、CLI拡張機能、APIバージョンを明示する |
特にCIでSDKを再生成しているチームは、tspconfig.yamlの変更を「設定だけ」と軽く見ないほうが安全です。SDK Automationでは、TypeSpecプロジェクトの変更ファイルから関連プロジェクトを特定し、言語ごとのSDK生成・ビルド・changelog・breaking change検出を行う流れがあります。つまり、REST仕様ファイルの大きな変更がなくても、生成されるSDK表面には差分が出る可能性があります。(GitHub)
よくある失敗と回避策
RESTのJSON名とSDKのプロパティ名を同じものとして扱う
RESTではJSONプロパティ名が重要ですが、SDKでは言語ごとの命名規則に合わせてプロパティ名が変換されることがあります。今回のstartIpAddress / endIpAddressの件は、この違いが問題化しやすい典型例です。
回避策は、RESTペイロードの契約テストとSDKのコンパイルテストを分けることです。RESTのテストでは送受信JSONを確認し、SDKのテストでは各言語の型定義に合わせて確認します。
すべての言語で同じ影響があると思い込む
PR #42878では、IPアドレス関連の命名修正をC#に限定する意図が明示されています。C#では望ましい名前でも、JavaやJavaScriptでは破壊的変更になる場合があります。(GitHub)
複数言語のSDKを使っている組織では、「.NETで問題ないから全体も問題ない」と判断せず、言語ごとにサンプルビルドを走らせてください。
プレビューCLIを本番自動化で無条件に更新する
az cosmosdb mongoclusterはプレビューのコマンドグループです。プレビューのCLI拡張機能は便利ですが、更新により出力やオプションの扱いが変わる可能性があります。運用スクリプトでは、CLI拡張機能のバージョン、--output json、--query、エラー時の戻り値を固定的に確認するほうが安全です。(Microsoft Learn)
対応が必要な人・不要な人の判断基準
すぐ対応すべきなのは、MongoCluster向けAzure SDKを更新する予定がある人、またはSDK自動生成パイプラインを持っている人です。特にファイアウォール規則やPrivate Link関連の処理をコード化している場合は、プロパティ名とモデル名の差分を確認してください。
一方、Azure PortalだけでMongoClusterを操作している人、または既存のRESTリクエストを固定のapi-versionで呼び続けているだけの人は、緊急度は高くありません。ただし、今後SDKやCLIを更新するタイミングで影響が出る可能性があるため、変更メモとして残しておく価値はあります。
まとめ：次にやるべきこと
Azure REST APIの「MPG migration – mongocluster」は、REST APIのURLやMongoClusterリソースそのものを大きく置き換える更新というより、MongoCluster向けSDK生成設定を整理する変更として見るのが実務的です。ただし、SDK表面では命名差分やbreaking changeが発生し得るため、SDK利用者は軽視できません。
次に行うべきことは明確です。まず自分の環境でMongoCluster、startIpAddress、endIpAddress、PrivateLinkを検索し、REST直呼びかSDK利用かを分けてください。SDKを使っている場合は、言語ごとにパッケージ更新前後のビルドを実行し、ファイアウォール規則とPrivate Link周辺の型・プロパティ名を重点的に確認します。CIでSDK生成をしている場合は、tspconfig.yamlのC#エミッター設定とAPIViewのbreaking change結果まで見ることで、移行時の事故を防ぎやすくなります。
コメント