Azure REST APIの「Azure REST API documentation update: [Python] Mitigate breaking changes for azure-mgmt-cdn」は、Azure CDNの管理用Python SDKである azure-mgmt-cdn のTypeSpec移行に伴う破壊的変更を、できるだけ既存利用者に影響しない形へ抑えるための仕様更新です。結論から言うと、Azure CDNそのものの配信設定や既存リソースが自動で変わる更新ではありません。主に影響を受けるのは、Pythonで azure-mgmt-cdn を使ってCDN、Azure Front Door、WAF、ルール、オリジン、カスタムドメインなどを自動管理している開発者・運用担当者です。
今回の更新は、Azure REST API仕様の公式リポジトリである Azure/azure-rest-api-specs に対するPull Request #43333として、2026年5月20日にmainブランチへマージされました。対象ファイルは specification/cdn/resource-manager/Microsoft.Cdn/Cdn/client.tsp で、差分はTypeSpecのクライアント名・列挙値名・CreateOrUpdate扱いを調整する内容です。(GitHub)
Azure REST APIの「[Python] Mitigate breaking changes for azure-mgmt-cdn」で何が変わるのか
今回のAzure REST API documentation updateは、REST APIのエンドポイント仕様そのものを大きく変更するというより、TypeSpecから生成されるPython SDKの公開API名を既存の利用者に近づけるための調整です。
PRでは、Python SDK向けのカスタマイズとして、次のような意図が明記されています。
| 変更点 | 目的 | 影響しやすい箇所 |
|---|---|---|
Microsoft.Cdn のPythonクライアント名を CdnManagementClient に維持 | TypeSpec移行後も従来のクライアント名を使えるようにする | from azure.mgmt.cdn import CdnManagementClient を使うコード |
| HTTPステータスコード系の列挙値名をPython向けに維持 | 既存コードのEnum参照が壊れにくいようにする | WAFポリシーの default_custom_block_response_status_code 周辺 |
CustomDomains.create をARMのCreateOrUpdate操作として扱う | SDK生成時にCreateOrUpdate系メソッドが生成されるようにする | カスタムドメイン作成・更新の自動化処理 |
PRの差分では、Python SDK向けに @@clientName(Microsoft.Cdn, "CdnManagementClient", "python") が追加され、PolicySettingsDefaultCustomBlockResponseStatusCode の 200、403、405、406、429 に対して、TWO_HUNDRED、FOUR_HUNDRED_THREE などのPython向け名称が指定されています。さらに CustomDomains.create はARMのCreateOrUpdate操作としてマークされています。(GitHub)
今回の更新は「Azure CDNの設定変更」ではなく「SDK生成仕様の互換性対策」
まず押さえておきたいのは、今回の変更がAzure CDNやAzure Front Doorのリソース設定を直接変更するものではない点です。
対象はAzure REST API仕様リポジトリ内のTypeSpec定義です。azure-rest-api-specs はAzure REST API仕様の公式なソースとして扱われるリポジトリであり、ここで定義された仕様はSDK生成やREST APIドキュメント、サンプル生成などに関係します。(GitHub)
そのため、管理者がAzure PortalでCDNプロファイルやエンドポイントを確認しても、今回の更新だけで設定値が変わることはありません。一方で、Python SDKを使って次のような処理をしている場合は確認が必要です。
- CDNプロファイルやエンドポイントの作成・更新をPythonで自動化している
- Azure Front Door Standard/Premium関連のドメイン、ルート、オリジンをSDKから操作している
- WAFポリシーやカスタムブロック応答コードをPythonコードで設定している
- CI/CDで
azure-mgmt-cdnを自動アップグレードしている - SDKのモデルを
as_dict()、属性アクセス、Enum名、メソッド名に依存して扱っている
特に、SDKのメジャー・マイナー更新を固定せずに pip install -U azure-mgmt-cdn のような運用をしている環境では、将来のリリース反映時にテストなしで本番ジョブが壊れる可能性があります。
影響範囲：確認すべき利用者と影響が小さい利用者
今回のAzure REST API documentation updateで最も確認が必要なのは、Pythonの azure-mgmt-cdn を実務で使っているチームです。Azure SDKの最新一覧では、2026年5月時点の管理ライブラリ一覧に azure-mgmt-cdn が「Resource Management – Content Delivery Network」として掲載されています。(Azure)
| 利用状況 | 影響度 | 確認ポイント |
|---|---|---|
Pythonで azure-mgmt-cdn を使っている | 高 | クライアント名、Enum名、モデル構造、メソッド引数 |
| Terraform、Bicep、ARMテンプレートのみで管理している | 低 | 直接影響は限定的。ただし社内ツールがPython SDKを使っていないか確認 |
| REST APIをHTTPクライアントで直接呼んでいる | 低〜中 | SDK名の変更影響は少ないが、APIバージョンや仕様変更は別途確認 |
| JavaScript、Go、C#のCDN SDKも利用している | 中 | PR上では他言語のBreakingChangeラベルも付与されているため、各SDKの変更履歴を確認 |
| Azure Portalだけで手動運用している | 低 | 今回のSDK互換性対策による直接影響はほぼない |
PR #43333には BreakingChange-Python-Sdk のほか、JavaScript、Go向けのBreakingChange関連ラベルも付与され、Python向けの破壊的変更緩和だけでなく、SDK生成全体の互換性確認が行われたことが分かります。(GitHub)
背景：azure-mgmt-cdnのTypeSpec移行で起きやすい破壊的変更
今回のPRを理解するには、azure-mgmt-cdn のTypeSpec移行が背景にあることを押さえる必要があります。関連するAzure SDK for Python側のPRでは、azure-mgmt-cdn のTypeSpec移行が扱われ、APIバージョン 2025-06-01 をベースに生成されたこと、移行に伴う破壊的変更の分類が整理されています。(GitHub)
SDK側の変更履歴案では、13.2.0 において新しいハイブリッドモデルの導入、CdnManagementClient への send_request メソッド追加、複数モデルのプロパティ階層変更、LogAnalyticsOperations の一部引数のキーワード専用化などが記載されています。(GitHub)
主な注意点は次の通りです。
モデルのプロパティが properties 配下へ移るケースがある
TypeSpec移行後のSDKでは、REST APIの構造に合わせて、従来フラットに見えていたプロパティが properties オブジェクト配下へ移ることがあります。
たとえば、SDK側の変更履歴案では Endpoint、Origin、OriginGroup、Route、Rule、Secret、SecurityPolicy など多くのモデルで、インスタンス変数が properties 配下へ移る変更が列挙されています。(GitHub)
実務では、次のようなコードが影響を受けやすくなります。
# 旧来のアクセス例
endpoint = client.endpoints.get(resource_group, profile_name, endpoint_name)
print(endpoint.host_name)移行後は、実際のSDKバージョンとモデル定義に応じて、次のようなアクセスが必要になる可能性があります。
# REST API階層に近いアクセス例
endpoint = client.endpoints.get(resource_group, profile_name, endpoint_name)
print(endpoint.properties.host_name)Azure SDK for Pythonのハイブリッドモデル移行ガイドでも、複数階層のフラット化されたプロパティは、実際のREST API構造に沿ったネスト形式へ置き換える必要があると説明されています。(GitHub)
as_dict() や辞書形式のキーが変わる可能性がある
Python SDKの新しいハイブリッドモデルでは、モデルが辞書的な性質も持つため、as_dict() の扱いや出力キーに注意が必要です。移行ガイドでは、as_dict(keep_readonly=True) から as_dict(exclude_readonly=False) への変更や、出力キーが snake_case ではなくREST APIに近い camelCase になる点が示されています。(GitHub)
これは、次のようなコードに影響します。
data = endpoint.as_dict()
host = data["host_name"]移行後のモデルでは、次のようにキー名や階層の見直しが必要になる場合があります。
data = endpoint.as_dict()
host = data["properties"]["hostName"]ログ出力や差分比較、監査レポート生成で as_dict() の戻り値をそのまま使っているチームは、単体テストだけでなく、出力されるJSONの形も確認してください。
LogAnalyticsOperations の引数はキーワード指定が必要になる可能性がある
SDK側の変更履歴案では、LogAnalyticsOperations.get_log_analytics_metrics、get_log_analytics_rankings、get_waf_log_analytics_metrics、get_waf_log_analytics_rankings の各メソッドで、複数のパラメータが positional_or_keyword から keyword_only に変わるとされています。(GitHub)
つまり、位置引数で次々に渡していたコードは壊れやすくなります。
# 壊れやすい例：引数の意味が読み取りにくく、keyword-only化に弱い
client.log_analytics.get_log_analytics_metrics(
resource_group,
profile_name,
endpoint_name,
metrics,
date_time_begin,
date_time_end,
granularity
)安全なのは、意味のある引数をキーワードで明示する書き方です。
client.log_analytics.get_log_analytics_metrics(
resource_group_name=resource_group,
profile_name=profile_name,
endpoint_name=endpoint_name,
metrics=metrics,
date_time_begin=date_time_begin,
date_time_end=date_time_end,
granularity=granularity
)Python SDKの管理系APIは生成コードが更新されるとシグネチャが変わることがあるため、ログ分析系の処理は特にテスト対象に含めるべきです。
今回の緩和で維持される可能性が高いもの
PR #43333の狙いは、TypeSpec移行で発生し得る破壊的変更のうち、特にPython利用者にとって影響が大きい名前変更を抑えることです。具体的には、次の3点が重要です。
CdnManagementClient の名前を維持
Python SDKの利用者にとって最も分かりやすい影響は、管理クライアント名です。今回のTypeSpec定義では、Python向けに CdnManagementClient というクライアント名を維持する指定が追加されています。(GitHub)
既存コードで次のようなimportをしている場合、この名前が維持されることは大きな互換性対策になります。
from azure.mgmt.cdn import CdnManagementClientただし、クライアント名が維持されても、モデル構造やメソッド引数まで完全に従来通りになるとは限りません。今回の緩和は「すべての破壊的変更をなくす」ものではなく、「特定の名前変更を抑える」ものと理解するのが安全です。
WAFのカスタムブロック応答コードEnum名を維持
WAFポリシーでは、カスタムブロック応答コードとして 200、403、405、406、429 などが扱われます。Microsoft Learnの PolicySettings の説明でも、default_custom_block_response_status_code の既知値として 200、403、405、406、429 が示されています。(Microsoft Learn)
今回のPRでは、これらの値に対するPython向けEnum名として、次のような名称を指定しています。
| HTTPステータス | Python向けEnum名 |
|---|---|
| 200 | TWO_HUNDRED |
| 403 | FOUR_HUNDRED_THREE |
| 405 | FOUR_HUNDRED_FIVE |
| 406 | FOUR_HUNDRED_SIX |
| 429 | FOUR_HUNDRED_TWENTY_NINE |
WAFポリシーの自動生成やテンプレート適用でEnum名を直接参照している場合は、ここが壊れるとデプロイが失敗します。今回の緩和により、少なくともこれらのEnum名はPython SDK利用者に配慮した形で維持される方向です。
CustomDomains.createがCreateOrUpdateとして扱われる
もう一つの実務上のポイントは、CustomDomains.create がARMのCreateOrUpdate操作として扱われるように指定されたことです。PRのコメントでは、SDKジェネレーターがCreateOrUpdateメソッドを生成できるようにする意図が示されています。(GitHub)
カスタムドメイン管理では、作成と更新の境界が運用上あいまいになることがあります。たとえば、初回構築時は作成、証明書や関連設定の変更時は更新というように、同じ自動化フローで既存有無を気にせず処理したいケースがあります。
そのため、CreateOrUpdateとして生成されることは、IaCや運用スクリプトで扱いやすさに関係します。ただし、実際にどのメソッド名で公開されるかは、利用する azure-mgmt-cdn のバージョンと生成結果を確認してください。
管理者・開発者がまず確認すべきチェックリスト
今回の更新を受けて、PythonでAzure CDNやAzure Front Doorを管理しているチームは、次の順で確認すると効率的です。
| 確認項目 | 確認方法 | 問題があった場合の対応 |
|---|---|---|
azure-mgmt-cdn のバージョン | pip show azure-mgmt-cdn、requirements.txt、poetry.lock、pip-tools などを確認 | 本番で自動的に上がらないようバージョン固定 |
CdnManagementClient のimport | リポジトリ内を CdnManagementClient で検索 | importエラーが出ないかテスト |
| Enum名の参照 | PolicySettingsDefaultCustomBlockResponseStatusCode で検索 | 文字列・整数で代替できるか、Enum名が維持されているか確認 |
| モデルの直接属性アクセス | .host_name、.provisioning_state、.deployment_status などで検索 | .properties.host_name などへ移行候補を洗い出す |
as_dict() の利用 | as_dict、serialize、deserialize を検索 | camelCase、ネスト構造、移行ガイドの互換ヘルパーを確認 |
| Log Analytics系メソッド | get_log_analytics_、get_waf_log_analytics_ で検索 | 位置引数からキーワード引数へ変更 |
| CI/CDの依存解決 | pip install -U、未固定の azure-mgmt-cdn を確認 | ステージングで検証後に更新 |
最初に見るべきなのは、Azure上の設定画面ではなく、アプリケーションや運用ジョブの依存関係です。SDK更新の影響は、Azureリソースではなく「Pythonコードの実行時エラー」として表面化しやすいためです。
既存コードの移行で失敗しやすいポイント
依存バージョンを固定せず本番で突然更新される
最も避けたいのは、CI/CDや定期実行ジョブで依存関係が自動的に更新され、本番のCDN管理処理が突然失敗するケースです。
悪い例は次のような指定です。
azure-mgmt-cdnまたは、制約が緩すぎる指定です。
azure-mgmt-cdn>=13.0.0検証前に更新を防ぎたい場合は、現在動作しているバージョンを明示的に固定します。
azure-mgmt-cdn==13.1.1そのうえで、検証環境では次期バージョンを別ブランチで試し、単体テスト・結合テスト・実際のAzureサブスクリプションに対するドライランに近い確認を行います。なお、Azure SDKの一覧では2026年5月時点で azure-mgmt-cdn のPyPI安定版として 13.1.1 が表示されています。将来のリリース状況は変わるため、実際の更新時にはPyPIと公式リリース一覧を確認してください。(Azure)
属性名だけを置換してテストを省略する
endpoint.host_name を endpoint.properties.host_name に変えるだけで済むケースもありますが、すべてが単純置換で解決するとは限りません。
たとえば、as_dict() の戻り値を使っている場合、Python属性名ではなくREST API寄りの camelCase キーになる可能性があります。移行ガイドでも、直接辞書アクセスや as_dict() のキー形式が変わる点が示されています。(GitHub)
単純な文字列置換より、次の観点でテストを作るほうが安全です。
- 取得したCDNエンドポイントからホスト名を読めるか
- オリジン、ルート、ルール、WAFポリシーを取得して期待値と比較できるか
as_dict()の出力を保存している場合、JSON構造が既存の監査・差分処理に合うか- 更新系APIを呼び出すとき、リクエストに必要なフィールドが欠落しないか
ログ分析APIの位置引数に依存している
LogAnalyticsOperations のメソッドは、引数が多く、位置引数のままでは読みづらくなりがちです。SDK側の変更履歴案では、複数のログ分析系メソッドでパラメータがキーワード専用になる変更が示されています。(GitHub)
この機会に、ログ分析APIの呼び出しはすべてキーワード引数へ寄せるのがよいでしょう。引数の順序変更や追加にも強くなり、レビュー時にも意味が分かりやすくなります。
展開前に行うべき実務手順
本番環境でAzure CDNやAzure Front DoorをSDK管理している場合は、次の流れで進めるとリスクを抑えられます。
| 手順 | 作業内容 | 完了条件 |
| -: | —————————— | ——————————————————- |
| 1 | 現在の azure-mgmt-cdn バージョンを棚卸し | 本番・検証・CIで使うバージョンが分かっている |
| 2 | Pythonコード内のSDK利用箇所を検索 | クライアント、モデル、Enum、LogAnalytics、as_dict() の利用箇所が一覧化されている |
| 3 | 検証環境で次期SDKを導入 | import、取得、作成、更新、削除、ログ分析の基本操作が通る |
| 4 | モデル構造の差分を確認 | 主要モデルの .properties 移行やJSON出力差分を把握している |
| 5 | 位置引数をキーワード引数へ修正 | ログ分析系メソッドの呼び出しが明示的になっている |
| 6 | ロールバック手順を用意 | 旧バージョンへ戻す方法と依存ロックファイルがある |
| 7 | 本番反映 | 反映後にCDN管理ジョブ、監査ジョブ、デプロイジョブが正常終了する |
特に、CDNやFront Doorはエンドユーザー向け配信に関わるため、SDK更新そのものを軽く見ないほうがよいです。設定変更を伴わないSDK更新でも、管理ジョブが失敗すれば証明書更新、ルート更新、WAF設定変更などの運用に影響します。
具体的なコード確認例
クライアント生成
CdnManagementClient の名前は今回のPRでPython向けに維持される指定が追加されています。既存コードは基本的に次の形を確認します。
from azure.identity import DefaultAzureCredential
from azure.mgmt.cdn import CdnManagementClient
credential = DefaultAzureCredential()
client = CdnManagementClient(credential, subscription_id)Microsoft LearnのPython APIリファレンスでも、CdnManagementClient はCDN管理クライアントとして掲載されています。(Microsoft Learn)
Enum参照
WAFポリシーのカスタムブロック応答コードをEnumで指定している場合は、該当箇所を検索します。
from azure.mgmt.cdn.models import PolicySettingsDefaultCustomBlockResponseStatusCode
status_code = PolicySettingsDefaultCustomBlockResponseStatusCode.FOUR_HUNDRED_THREE今回のTypeSpec更新では、このようなPython向けEnum名を維持する指定が追加されています。ただし、実際の利用可否はインストールされているSDKバージョンで確認してください。(GitHub)
モデル階層
Endpoint や Origin のプロパティを読む処理は、移行時に壊れやすい箇所です。
endpoint = client.endpoints.get(
resource_group_name=resource_group,
profile_name=profile_name,
endpoint_name=endpoint_name
)
# 移行後に必要になる可能性があるアクセス
host_name = endpoint.properties.host_nameこのようなコードは、例外が出ないかだけでなく、取得値が従来と同じ意味を持つかまで確認します。
管理者向け：Azure環境側で確認すること
今回の変更はSDK生成仕様が中心ですが、管理者は次の観点で周辺影響を確認しておくと安全です。
- CDN、Front Door、WAFを更新する自動化ジョブの有無
- 定期実行される証明書更新・カスタムドメイン検証スクリプトの有無
- 監査ログや構成情報をPython SDKで収集しているか
- Azure DevOps、GitHub Actions、Jenkinsなどで依存ライブラリを自動更新していないか
- 本番サブスクリプションに対してSDKテストを直接実行していないか
- サービスプリンシパルやManaged Identityの権限が、検証環境でも本番と同等に再現されているか
SDK移行の検証では、認証や権限エラーとSDK互換性エラーが混ざりやすいです。まず既存バージョンで検証環境の操作が成功することを確認し、その後にSDKだけを更新して差分を見ると原因を切り分けやすくなります。
開発者向け：移行判断の基準
すぐにSDK更新へ進むべきか、いったん固定して様子を見るべきかは、次の基準で判断できます。
| 状況 | 推奨判断 |
|---|---|
| 本番運用ジョブでCDNやFront Doorを頻繁に更新している | まず現行バージョンを固定し、検証環境で移行テスト |
azure-mgmt-cdn を読み取り専用で使っている | 取得系モデルの .properties 移行と as_dict() 出力差分を確認 |
| WAFやLog AnalyticsをSDKで操作している | Enum名、キーワード引数、モデル階層を重点確認 |
| 新規プロジェクトでこれから使う | 新しいSDK構造に合わせて実装。古いフラット構造へ依存しない |
| 社内ライブラリでSDKをラップしている | ラッパー層で互換吸収し、アプリ側へ影響を出さない設計にする |
既存システムでは「動いているから更新しない」も一つの判断ですが、長期的にはTypeSpec移行後の構造へ合わせるほうが保守しやすくなります。特に、REST APIの実構造とSDKモデルの構造が近づくことで、Microsoft LearnのREST APIドキュメント、SDKコード、実際のレスポンスを突き合わせやすくなります。
今回の更新への実務的な対応まとめ
Azure REST APIの「Azure REST API documentation update: [Python] Mitigate breaking changes for azure-mgmt-cdn」は、azure-mgmt-cdn のTypeSpec移行に伴うPython SDKの破壊的変更を緩和するための仕様更新です。特に、CdnManagementClient のクライアント名維持、WAFカスタムブロック応答コードのEnum名維持、CustomDomains.create のCreateOrUpdate扱いが重要なポイントです。(GitHub)
ただし、今回の緩和によってすべての移行作業が不要になるわけではありません。SDK側のTypeSpec移行では、ハイブリッドモデル、properties 配下へのモデル構造変更、as_dict() の出力形式、Log Analytics系メソッドのキーワード専用化など、実装に影響し得る変更が示されています。(GitHub)
次に取るべき行動は明確です。まず azure-mgmt-cdn の利用箇所とバージョンを棚卸しし、依存バージョンを固定します。そのうえで、検証環境に次期SDKを導入し、クライアント生成、CDNエンドポイント取得、カスタムドメイン作成・更新、WAF設定、Log Analytics取得、as_dict() 出力の差分を確認してください。問題が出た箇所から、.properties への移行、キーワード引数化、Enum参照の見直しを進めるのが、安全で現実的な対応です。
コメント