MENU

Azure REST API 2025-11-01のGA更新まとめ：extensions（CompileFile）の確認ポイント

Azure

Azure REST API documentation update: Create GA API version 2025-11-01 for extensions (CompileFile) は、Microsoft.PortalServices の extensions 向けに、安定版として扱う API バージョン 2025-11-01 を追加する仕様更新です。まず確認すべきことは、api-version を固定しているコード、AutoRest やSDK生成設定、CompileFile のリクエスト・レスポンス検証の3点です。特に 2024-04-01-preview を使っている自動化スクリプトやクライアントは、移行候補として 2025-11-01 を把握しておく必要があります。

ただし、公開PR #42875 は Create GA API version 2025-11-01 for extensions (CompileFile) という内容で、表示上は Draft のPRです。2026年5月5日に Add stable 2025-11-01 CompileFile API - generated from public TypeSpec の更新が入っていますが、本番利用ではPRのマージ状況、Microsoft Learn側の公開状況、対象サブスクリプションでのAPI受け入れ状況を必ず確認してください。(GitHub)

目次

Azure REST APIの2025-11-01更新でまず確認すべきこと

今回の変更は、一般的なAzureリソース全体に影響する大規模変更ではありません。影響の中心は、Azure Portal 関連の Microsoft.PortalServices、その中でも extensions の CompileFile API を直接または生成SDK経由で扱っているチームです。

Azure REST API の仕様は、Azure REST API Specifications リポジトリが主要な参照元として扱われています。今回のPRでは、specification/portalservices/resource-manager/Microsoft.PortalServices/extensions/stable/2025-11-01/extensions.json が追加され、readme.md に package-2025-11-01 タグも追加されています。(GitHub)

確認項目今回のポイント対応の優先度
APIバージョン2025-11-01 が stable 配下に追加高
対象エンドポイントMicrosoft.PortalServices の compilefile高
SDK生成package-2025-11-01 タグが追加中〜高
既存preview利用2024-04-01-preview からの移行候補中
RBAC・監査ARMのコントロールプレーンとして扱う中
本番切替Draft/マージ状況の確認が必要高

何が変わったのか

今回のAzure REST API更新では、extensions向けに 2025-11-01 のGA API versionを作成するための仕様ファイル、サンプル、TypeSpec側のバージョン定義、AutoRest設定が追加されています。

PRのファイル変更を見ると、主に次の内容が追加されています。

追加・変更箇所内容
stable/2025-11-01/extensions.json2025-11-01 のOpenAPI仕様
examples/PortalTenant_Compilefile.jsonCompileFileのリクエスト例
examples/Operations_List.jsonプロバイダー操作一覧の例
main.tspv2025_11_01: "2025-11-01" の追加
readme.mdpackage-2025-11-01 タグと入力ファイル設定の追加

readme.md では、既定タグが package-2024-04-01-preview から package-2025-11-01 に変更され、stable/2025-11-01/extensions.json を入力ファイルとして参照する設定が追加されています。また、CompileFileの柔軟なペイロードや同期POSTの200応答に関する抑制理由も記載されています。(GitHub)

CompileFile APIの仕様で見るべきポイント

CompileFile は、インラインコンテンツを使ってファイルをコンパイルするためのAPIです。仕様上は次のようなARMコントロールプレーンのPOST操作として定義されています。

POST https://management.azure.com/providers/Microsoft.PortalServices/compilefile?api-version=2025-11-01
Authorization: Bearer <access-token>
Content-Type: application/json

リクエスト本文は PortalTenantCompileFileProperties として定義され、contents が必須です。必要に応じて stringSource や files を含められます。レスポンスは成功時にHTTP 200を返し、結果本文は PortalTenantCompileFileResult として定義されています。(GitHub)

実装時に注意したいのは、CompileFile が長時間実行操作のような 202 Accepted + ポーリング前提ではなく、仕様上は同期的なPOSTで 200 と結果本文を返す点です。readme.md 側でも、PostResponseCodes の抑制理由として「同期POSTアクションが200で結果本文を返す既存API契約」であることが説明されています。(GitHub)

リクエスト本文のイメージ

実際のペイロードは利用シナリオに依存しますが、仕様上の構造は次のように考えると理解しやすくなります。

{
  "contents": {
    "$schema": "../../Definitions/dx.schema.json#",
    "stringSource": "Resources/MyStrings.resjson",
    "view": {
      "kind": "Markdown",
      "export": true,
      "properties": {
        "content": {
          "property": "markdownContent"
        }
      }
    }
  },
  "stringSource": {
    "markdownContent": "# This is an example of a markdown view!"
  },
  "files": {
    "myFile.json": {
      "contentField": true
    }
  }
}

このAPIは、ペイロードの内容が固定スキーマだけで完結しない可能性があります。contents、stringSource、files は柔軟なオブジェクトとして扱われるため、クライアント側で過度に厳しいバリデーションを入れている場合は、正当な入力まで弾いてしまう可能性があります。

影響を受けやすいチーム

今回のAzure REST API更新で対応を検討すべきなのは、次のようなチームです。

対象確認すべき理由
CompileFile を直接RESTで呼び出している開発者api-version の切り替え候補になる
AutoRestでSDKやクライアントを生成しているチームpackage-2025-11-01 の追加により生成対象が変わる可能性がある
Azure Portal extensionsを扱う内製ツール担当者ペイロード構造やテストデータの確認が必要
Azure RBAC・監査ログを管理する運用担当者ARMコントロールプレーンの操作として権限・監査の確認が必要
CIでOpenAPI差分チェックをしているチームstable配下の新バージョン追加でチェック結果が変わる可能性がある

一方で、仮想マシン、ストレージ、App Serviceなど通常のAzureリソースを管理しているだけの利用者には、直接の影響は限定的です。Microsoft.PortalServices の extensions や CompileFile を使っていない場合、すぐに設定変更が必要になる可能性は高くありません。

コントロールプレーンAPIとして確認すべきこと

今回のAPIは、Azure Resource Manager経由のコントロールプレーンAPIとして扱います。Microsoft Learnでは、コントロールプレーンはサブスクリプション内のリソース管理に使われ、要求はAzure Resource ManagerのURLに送信されると説明されています。また、コントロールプレーン要求にはAzure RBAC、Azure Policy、管理ロック、アクティビティログなどの管理機能が関係します。(Microsoft Learn)

そのため、単にHTTPリクエストが通るかだけでなく、次の観点も確認してください。

観点確認内容よくある失敗
認証Microsoft Entra IDのアクセストークンを使えるかローカルでは通るがCIのサービスプリンシパルで失敗する
権限対象操作に必要なRBAC権限があるか管理者アカウントだけでテストして権限不足を見逃す
ポリシーAzure Policyで拒否されないか検証環境と本番環境でポリシーが違う
監査Activity Logや独自ログで追跡できるかAPI移行後に監査ルールが旧バージョン前提のまま
エンドポイントmanagement.azure.com 向け通信が許可されているかプロキシやファイアウォールで本番のみ失敗する

previewから2025-11-01へ移行する場合の進め方

2024-04-01-preview を利用している場合、いきなり本番コードの api-version を置き換えるのではなく、段階的に確認するのが安全です。Azure REST APIでは、要求URIのクエリ文字列に api-version を含めるため、コード、設定ファイル、生成クライアント、テストデータのどこかに旧バージョンが固定されていることがあります。(Microsoft Learn)

現在の利用箇所を洗い出す

まず、リポジトリ全体で次の文字列を検索します。

Microsoft.PortalServices
compilefile
2024-04-01-preview
package-2024-04-01-preview
PortalTenant_Compilefile

特に見落としやすいのは、アプリ本体ではなくCI/CD、OpenAPI生成スクリプト、Postmanコレクション、E2Eテスト、監視ルールです。運用スクリプトだけ旧APIバージョンのまま残ると、移行後に一部ジョブだけ失敗する原因になります。

生成SDKやAutoRest設定を更新する

AutoRestや類似ツールでクライアントを生成している場合は、readme.md のタグ指定を確認します。今回のPRでは package-2025-11-01 が追加され、入力ファイルとして stable/2025-11-01/extensions.json が参照されます。(GitHub)

例として、生成コマンドやCI設定に次のような指定がある場合は見直し対象です。

autorest specification/portalservices/resource-manager/Microsoft.PortalServices/extensions/readme.md --tag=package-2024-04-01-preview

移行検証では、次のように新しいタグで生成できるかを確認します。

autorest specification/portalservices/resource-manager/Microsoft.PortalServices/extensions/readme.md --tag=package-2025-11-01

生成後は、型名やメソッド名だけでなく、レスポンス処理、エラー型、任意オブジェクトの扱いが変わっていないかを確認してください。

契約テストを先に用意する

本番切替前に、最低限次のテストを用意しておくと安全です。

テスト確認内容
正常系contents を含むリクエストで200応答が返るか
必須項目不足contents なしで期待どおりエラーになるか
柔軟なペイロードstringSource や files に任意構造を入れて扱えるか
権限不足権限のないIDで期待どおり拒否されるか
ログAPI実行が監査・トレースできるか

このテストを先に作ることで、api-version の変更が単なる文字列置換で済むのか、クライアント側のバリデーションやログ処理まで修正が必要なのかを判断できます。

「GA API version」とあっても本番切替で注意すべき点

PRタイトルにはGA API versionとありますが、実務では「stable配下の仕様が追加された」ことと「自分の環境で即座に安全に使える」ことを分けて考える必要があります。

PRページでは、マージ先が main の場合、マージ後のAPIはAzure顧客に出荷されたものと見なされ、以後のインプレース変更はバージョニングや破壊的変更ポリシーの対象になる旨が案内されています。また、顧客向けにリリースする意図がある場合は PublishToCustomers ラベルの追加が求められる説明もあります。(GitHub)

つまり、対応方針は次のように分けるのが現実的です。

状態推奨アクション
PRがDraftまたは未マージ仕様差分の把握、検証準備、影響調査までに留める
PRがマージ済みSDK生成、検証環境での疎通、契約テストを実施する
Microsoft Learnや実APIで利用確認済み段階的に本番移行を進める
エラーや差分があるpreview継続、Issue/PRコメント確認、サポート経路で確認する

実装・運用で失敗しやすいポイント

documentation updateだから影響なしと判断する

REST API仕様の更新は、ドキュメントだけでなくSDK生成、型定義、CIの差分チェック、APIバージョン管理に影響します。特にAzure REST APIを直接呼び出すスクリプトでは、api-version が設定ファイルではなくコード内に直書きされていることがあります。

preview版の削除を急ぎすぎる

2025-11-01 が移行候補になっても、既存の 2024-04-01-preview をすぐ削除するのは避けた方が安全です。検証環境で同じペイロード、同じ認証主体、同じネットワーク条件で通ることを確認してから段階的に切り替えましょう。

CompileFileを長時間実行操作として扱う

今回の仕様では、CompileFileは同期POSTとして200応答を返す扱いです。Azureの一部APIに慣れていると、POST操作を 202 Accepted とポーリング前提で実装してしまうことがあります。クライアント側でLRO前提の処理を入れている場合は、200 の結果本文を正しく処理できるか確認してください。

ペイロードを厳密に固定しすぎる

CompileFileの contents、stringSource、files は柔軟なオブジェクトとして定義されています。JSON Schemaや独自バリデーションでキーを固定しすぎると、仕様上許容される内容をアプリ側で拒否する可能性があります。入力値の検証は必要ですが、「危険な値を防ぐ検証」と「仕様上の柔軟性を潰す検証」は分けて設計してください。

まず実行すべき確認チェックリスト

今回のAzure REST API更新に関係する可能性がある場合は、次の順番で確認すると無駄がありません。

| 順番 | 作業 | 判断基準 |
| -: | ————————————————— | ——————— |
| 1 | Microsoft.PortalServices と compilefile の利用有無を検索 | 見つからなければ直接影響は低い |
| 2 | 2024-04-01-preview の固定箇所を洗い出す | REST呼び出し、SDK生成、テストを確認 |
| 3 | PRのマージ状況と公開ドキュメントを確認 | Draftや未公開なら本番切替は待つ |
| 4 | 2025-11-01 で検証環境の疎通を試す | 同じ認証主体・同じネットワークで試す |
| 5 | 200応答、エラー応答、ログ出力を確認 | 本番監視で追える状態にする |
| 6 | 段階的に切り替える | ロールバック手順を残す |

今回の更新で最も重要なのは、2025-11-01 という新しいAPIバージョンの存在を把握しつつ、PRや実APIの公開状況を確認してから移行することです。CompileFile を使っているチームは、まずリポジトリ内の 2024-04-01-preview、compilefile、package-2024-04-01-preview を検索し、生成SDKと契約テストの更新範囲を見積もりましょう。直接使っていないチームでも、Azure REST API仕様をCIやSDK生成に取り込んでいる場合は、package-2025-11-01 の追加で自動生成結果が変わらないかを確認しておくと安心です。

Azure
APIバージョン Azure Resource Manager Azure REST API Microsoft.PortalServices

この記事を書いた人

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

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

関連記事

コメント

コメントする

目次