MENU

Azure REST APIのMongoCluster更新：startIpAddress/endIpAddressのSDK名変更と対応

Azure

Azure REST API documentation update: Scope mongocluster clientName for startIpAddress/endIpAddress to csharp の結論は、REST APIのリクエスト項目名が変わったわけではなく、MongoCluster向けSDK生成時の名前変更をC#だけに限定したという点です。直接REST API、Bicep、ARMテンプレート、Terraform AzAPIで startIpAddress / endIpAddress を使っている場合、基本的にペイロード名を変更する必要はありません。一方で、Azure SDK for Javaなど生成SDKを使う開発者や、TypeSpecからクライアントを再生成しているチームは、メソッド名・プロパティ名が意図せず変わっていないか確認すべき更新です。GitHub上のPRは2026年5月5日に作成・更新され、5月6日にmainへマージされています。(GitHub)

目次

Azure REST API documentation update: Scope mongocluster clientName for startIpAddress/endIpAddress to csharp の要点

今回の変更は、Azure REST APIの仕様リポジトリである azure-rest-api-specs の MongoCluster 用 TypeSpec 設定に対する修正です。対象ファイルは specification/mongocluster/resource-manager/Microsoft.DocumentDB/MongoCluster/client.tsp で、変更量は2行の追加・2行の削除にとどまります。(GitHub)

変更前は、FirewallRuleProperties.startIpAddress と FirewallRuleProperties.endIpAddress に対する @@clientName が言語スコープなしで指定されていました。そのため、C#だけでなくJava、JavaScript、Python、Goなど他の言語向けSDK生成にも名前変更が適用される状態でした。PRの説明では、この未スコープの @@clientName により、Java SDKで startIpAddress が startIPAddress に変わる破壊的変更が発生していたと説明されています。(GitHub)

差分を簡略化すると、次のような修正です。

項目変更前変更後
startIpAddress のSDK向け名前変更startIPAddress を全言語に適用startIPAddress をC#のみに適用
endIpAddress のSDK向け名前変更endIPAddress を全言語に適用endIPAddress をC#のみに適用
REST APIのJSONプロパティ名startIpAddress / endIpAddress変更なしと考えてよい
主な目的C#向けの命名調整他言語SDKへの副作用を防ぐ

実際の差分では、@@clientName(FirewallRuleProperties.startIpAddress, "startIPAddress") が @@clientName(FirewallRuleProperties.startIpAddress, "startIPAddress", "csharp") に、endIpAddress も同様に "csharp" スコープ付きへ変更されています。(GitHub)

なぜC#だけに限定する必要があったのか

ポイントは、IP という略語の扱いです。C#ではプロパティ名として StartIPAddress / EndIPAddress のように、略語を大文字で表す命名が採用されることがあります。実際に Azure SDK for .NET の MongoClusterFirewallRuleProperties では、StartIPAddress と EndIPAddress がプロパティとして掲載されています。(Microsoft Learn)

一方、Java SDKでは既存のAPIとして startIpAddress()、withStartIpAddress(String startIpAddress)、endIpAddress()、withEndIpAddress(String endIpAddress) が掲載されています。Java側で突然 startIPAddress() のような名前に変わると、既存コードのコンパイルエラーにつながる可能性があります。(Microsoft Learn)

TypeSpec Azureのドキュメントでは、デコレーターの scope は対象言語エミッターを指定するためのパラメーターであり、指定しない場合はデフォルトで全言語エミッターに適用されると説明されています。つまり、今回の問題は「C#向けに意図した名前変更を、全言語向けの設定として書いてしまった」ことが原因です。(Azure)

影響範囲：誰が対応すべきか

今回のAzure REST API更新は、すべての利用者に移行作業を求めるタイプの変更ではありません。影響の有無は、REST APIを直接呼んでいるのか、SDKを使っているのか、さらにどの言語のSDKを使っているのかで分かれます。

利用形態影響度確認すべきこと
直接REST APIを呼び出すアプリ低JSONのキーを startIpAddress / endIpAddress のままにする
ARMテンプレート、Bicep、Terraform AzAPI低テンプレート上のプロパティ名を不用意に startIPAddress へ変えない
C# SDK利用者中SDKモデルでは StartIPAddress / EndIPAddress を使う前提で確認する
Java SDK利用者高startIpAddress() / withStartIpAddress() など既存のcamelCase名が維持されるか確認する
JavaScript、Python、Go SDK利用者中自動生成された名前が不要に IPAddress 表記へ変わっていないか確認する
TypeSpecから社内SDKを生成しているチーム高最新のspec反映後に再生成し、差分レビューとコンパイルテストを行う

特に注意したいのは、REST APIの項目名とSDKのプロパティ名を同一視しないことです。Azure Resource Managerテンプレートのリファレンスでは、MongoClusterのファイアウォール規則プロパティとして startIpAddress と endIpAddress が示され、どちらもIPv4形式の文字列として扱われています。(Microsoft Learn)

REST APIやIaCで確認すべきプロパティ名

直接REST API、ARMテンプレート、Bicep、Terraform AzAPIで確認すべき名前は、基本的に次の形です。

{
  "properties": {
    "startIpAddress": "203.0.113.10",
    "endIpAddress": "203.0.113.10"
  }
}

ここで重要なのは、startIPAddress や endIPAddress ではなく、Ip の部分だけ先頭大文字になった startIpAddress / endIpAddress を使うことです。Microsoft Learnのテンプレートリファレンスでも、FirewallRuleProperties の名前として startIpAddress と endIpAddress が掲載されています。(Microsoft Learn)

ファイアウォール規則では、開始IPアドレスと終了IPアドレスの両方をIPv4形式で指定します。単一のIPアドレスだけを許可したい場合は、開始と終了に同じ値を入れる構成が一般的です。ただし、実際の許可範囲はネットワーク設計や組織のセキュリティポリシーに従って決めてください。

SDK利用者が見るべきコード上の違い

SDKを使っている場合、REST APIのJSON名ではなく、各言語のSDKで公開されているメソッド名・プロパティ名を見る必要があります。

C#では StartIPAddress / EndIPAddress を前提に確認する

C#向けには、今回の @@clientName が引き続き適用されます。つまり、SDKモデル側では StartIPAddress / EndIPAddress のような名前が想定されます。Microsoft Learnの .NET APIリファレンスでも、MongoClusterFirewallRuleProperties に StartIPAddress と EndIPAddress が掲載されています。(Microsoft Learn)

確認すべき観点は次の通りです。

// 概念例：実際の生成SDKのバージョンに合わせて確認
properties.StartIPAddress = "203.0.113.10";
properties.EndIPAddress = "203.0.113.10";

C#コードでは StartIpAddress に直す必要がある、という変更ではありません。今回の修正はむしろ、C#向けの IPAddress 表記を他言語に波及させないためのものです。

Javaでは startIpAddress() / withStartIpAddress() を確認する

Java SDKを使っている場合は、startIPAddress() のような名前に依存していないか確認してください。Microsoft LearnのJavaリファレンスでは、FirewallRuleProperties のメソッドとして startIpAddress()、withStartIpAddress(String startIpAddress)、endIpAddress()、withEndIpAddress(String endIpAddress) が掲載されています。(Microsoft Learn)

確認例は次の通りです。

// 確認したい形
new FirewallRuleProperties()
    .withStartIpAddress("203.0.113.10")
    .withEndIpAddress("203.0.113.10");

もし一時的な生成物やプレビュー版SDKで withStartIPAddress のような名前を使っていた場合は、今後の再生成やSDK更新で再び名前が戻る可能性があります。CIでコンパイルエラーが出た場合は、SDKバージョン、生成元のspec commit、メソッド名の差分をセットで確認すると原因を切り分けやすくなります。

移行・設定確認の実務手順

今回の変更で失敗しやすいのは、「REST APIのJSONキーまで変えなければならない」と誤解してしまうケースです。まずは利用形態を切り分け、その後にSDKの表面だけを確認すると無駄な修正を避けられます。

手順確認内容判断基準
1MongoClusterのファイアウォール規則を使っているかMicrosoft.DocumentDB/mongoClusters/firewallRules を利用している場合は確認対象
2REST/IaCかSDKかを切り分けるREST/IaCならJSON名、SDKなら言語別API名を見る
3REST/IaCのプロパティ名を確認するstartIpAddress / endIpAddress のままなら基本的に問題なし
4C#コードを確認するStartIPAddress / EndIPAddress を使っているか
5Javaコードを確認するstartIpAddress() / withStartIpAddress() など既存のcamelCase名を使っているか
6SDK更新後にCIを回すコンパイルエラー、シリアライズ結果、サンプルコードの差分を見る
7社内生成SDKがある場合は再生成するPR #42878反映後のspecから生成し、API差分をレビューする

社内でAzure REST API仕様から独自SDKやラッパーを生成している場合は、client.tsp の差分だけで判断せず、生成後の公開APIも確認してください。GitHub PR上では、APIViewがTypeSpec、Go、JavaScript、Python、Java向けのAPIレビューを作成したことが示されており、SDK表面に影響し得る変更として扱われています。(GitHub)

よくある誤解と注意点

startIpAddress を startIPAddress に置換してはいけない

REST APIやテンプレートで使うJSONキーは、SDKのC#プロパティ名とは別物です。C#の StartIPAddress を見て、ARMテンプレートやRESTリクエストまで startIPAddress に置換すると、期待したスキーマと一致しない可能性があります。

Javaの命名をC#に合わせる必要はない

今回の修正は、C#と他言語の命名差を許容するためのものです。JavaではJavaらしいcamelCaseのメソッド名を維持する方向で考えるのが自然です。PRの説明でも、C#だけにスコープすることで他言語は元のcamelCaseプロパティ名を維持するとされています。(GitHub)

SDKのプレビュー版を使っている場合は特に注意する

MongoCluster関連のSDKやAPIバージョンは、プレビュー版が含まれる場合があります。プレビュー版では、正式リリース前にモデル名、メソッド名、サンプルが変わることがあります。依存関係を更新する前に、ロックファイル、CHANGELOG、生成元のspec commit、コンパイル結果を確認してください。

ファイアウォール設定そのものの安全性も見直す

今回の更新は命名スコープの修正ですが、対象はファイアウォール規則です。コード修正のついでに、許可IP範囲が広すぎないか、不要な一時IPが残っていないか、環境ごとに設定が分離されているかも確認しておくと実務上の価値が高くなります。

まとめ：次に取るべき行動

今回のAzure REST API documentation updateは、MongoClusterの startIpAddress / endIpAddress に関するSDK生成上の命名修正です。REST APIのペイロード名を変更する更新ではなく、C#向けの StartIPAddress / EndIPAddress 表記をC#だけに限定し、Javaなど他言語SDKへの意図しない破壊的変更を避けるための対応です。

まずは、自分の利用形態を確認してください。REST API、Bicep、ARMテンプレート、Terraform AzAPIを使っているなら、startIpAddress / endIpAddress のままかを確認します。C# SDKを使っているなら StartIPAddress / EndIPAddress、Java SDKを使っているなら startIpAddress() / withStartIpAddress() など、言語ごとの公開API名を確認します。

最後に、SDKや生成クライアントを更新するチームは、コンパイルテストだけでなく、シリアライズされるJSONキーが startIpAddress / endIpAddress のままになっているかまで確認してください。ここまで見れば、今回の更新による影響を安全に切り分けられます。

Azure
Azure SDK Azure REST API TypeSpec MongoCluster

この記事を書いた人

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

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

関連記事

コメント

コメントする

目次