Azure REST APIで2026年5月5日に更新が確認された「Add AiIntegration to API version 2026-03-15」は、Azure App Service系のREST API仕様に aiIntegration プロパティを追加する変更です。結論から言うと、Azure App ServiceやFunction AppをREST API、IaC、SDK、自動化スクリプトで管理しているチームは、APIバージョン 2026-03-15 を使う前に、aiIntegration の扱いとSDK生成への影響を確認しておくべきです。
特に注意したいのは、この変更が単なる説明文の追加ではなく、OpenAPI / TypeSpec上のモデル追加として入っている点です。PR上ではGo SDKとJavaScript SDKで破壊的変更のラベルが付いており、Swagger BreakingChangeチェックの失敗も示されています。まだPR段階の情報であるため本番仕様として断定はできませんが、Azure App ServiceのAI連携やMCP関連機能をREST APIで管理する流れを見据えた変更として、早めに影響範囲を洗い出しておく価値があります。(GitHub)
Azure REST APIの「Add AiIntegration to API version 2026-03-15」とは
今回の更新は、Azure REST API仕様を管理する Azure/azure-rest-api-specs リポジトリのPull Request「Add AiIntegration to API version 2026-03-15」によるものです。対象は Microsoft.Web/AppService の仕様で、PRでは models.tsp と stable/2026-03-15/openapi.json の2ファイルに変更が加えられています。(GitHub)
追加の中心は、App Serviceのサイト構成に関するモデルへ aiIntegration を追加することです。TypeSpec側では SiteProperties と SitePatchResourceProperties に aiIntegration?: AiIntegration が追加され、OpenAPI側でも AiIntegration、McpSettings、McpServerConfig、SiteAuthInfo といった定義が追加されています。(GitHub)
この変更は、Azure App Service上のアプリに対してAI連携設定をREST API仕様上で表現できるようにするものと読めます。現時点で重要なのは、「すぐに全ユーザーが設定変更を迫られる」というより、API仕様・SDK・IaC・自動化処理でApp Serviceのリソース定義を扱う人が確認すべき変更だという点です。
何が変わったのか
今回の変更では、App Serviceのサイト設定にAI連携用の構成が追加されています。PRコメントにも「Add AiIntegration property to Site.」とあり、サイトリソースに対して AiIntegration プロパティを追加する意図が示されています。(GitHub)
主な追加要素は次のとおりです。
| 追加要素 | 概要 | 確認すべきポイント |
|---|---|---|
aiIntegration | アプリのAI連携設定 | App Serviceの作成・更新・PATCH処理に含まれる可能性 |
AiIntegration | AI連携設定の親モデル | apiSpecPath、mcp、siteAuth を保持 |
apiSpecPath | /home 配下から見たAPI仕様ファイルの相対パス | ファイル配置やデプロイ方式との整合性 |
mcp | MCP構成 | MCPサーバー一覧の更新方法に注意 |
siteAuth | MCPエンドポイント向けの外部認証設定 | EasyAuthを使わない場合のJWT/OIDC設定確認 |
McpServerConfig | 個別MCPサーバー設定 | name、endpoint、toolList、有効・無効状態 |
SiteAuthInfo | 外部認証情報 | jwksUri、issuer、audience、OIDC metadata、scopes |
OpenAPIの差分では、AiIntegration は「AI integration configuration for the app.」として定義され、apiSpecPath は /home からの相対パス、siteAuth はEasyAuthが有効でない場合に使うMCPエンドポイント向け外部認証設定として説明されています。(GitHub)
影響を受ける可能性が高い人
今回のAzure REST API documentation updateで特に確認が必要なのは、Azure App Serviceを手作業ではなくコードやAPIで管理しているチームです。
Azure REST APIを直接呼び出している開発者
自社ツール、運用スクリプト、管理画面などからAzure REST APIを直接呼び出している場合、2026-03-15 のAPIバージョンを採用すると、レスポンスやリソース定義に aiIntegration が含まれる可能性があります。
特に、レスポンスJSONを厳密な型でパースしている場合は注意が必要です。多くのJSONパーサーでは未知のプロパティを無視できますが、独自バリデーションで「定義外の項目をエラーにする」設計にしていると、想定外の失敗につながることがあります。
確認すべきポイントは次の3つです。
api-version=2026-03-15を使う予定があるか- App Serviceの作成・更新・取得レスポンスを厳密に検証していないか
- PATCHやPUT時に既存プロパティを上書きする実装になっていないか
SDKを利用している開発者
PR上では、APIレベルの変更に対してGo、Java、JavaScript、TypeSpecのAPIViewが作成されています。また、Go SDKとJavaScript SDKについては破壊的変更を示すラベルも付与されています。(GitHub)
そのため、Azure SDKを使ってApp Serviceを管理している場合は、SDK更新時に次の点を確認してください。
| 利用言語・領域 | 確認内容 |
|---|---|
| Go | 生成されたApp Service SDKのモデル名・構造体・フィールド変更 |
| JavaScript / TypeScript | @azure/arm-appservice の型定義変更、strict modeでの影響 |
| Java | 生成モデルに AiIntegration 関連クラスが追加されるか |
| TypeSpec | Microsoft.Web のモデル定義変更が既存生成物に与える影響 |
破壊的変更ラベルが付いているからといって、すべての利用者のコードが必ず壊れるわけではありません。しかし、SDKの自動生成コードに依存しているCI、型チェック、スナップショットテスト、APIクライアントのラッパー実装では差分確認が必要です。
IaCや構成管理でApp Serviceを扱う運用担当者
Bicep、ARMテンプレート、Terraform、Pulumi、独自の構成管理ツールなどでApp Serviceを管理している場合も、aiIntegration をどう扱うかを確認しておくべきです。
現時点でこのPRはREST API仕様の変更です。すぐにすべてのIaCツールで同じプロパティが利用可能になるとは限りません。ただし、今後プロバイダーやSDKが追従すると、状態差分や未対応プロパティの扱いが問題になることがあります。
たとえば、実環境側に aiIntegration が存在するのに、IaC側ではまだ認識できない場合、次のような運用上のズレが起こり得ます。
- 管理画面や別ツールで入れたAI連携設定がIaCに反映されない
- 差分検出で未知の項目として扱われる
- PUT更新時に未指定プロパティが消える可能性を考慮する必要がある
- チーム内で「ポータル設定」と「コード管理設定」が分かれる
App Serviceをコード管理している組織では、API仕様の更新を見た段階で「どの設定をIaCで管理するか」を決めておくと、後の混乱を防ぎやすくなります。
AiIntegration の中身を実務目線で見る
AiIntegration は、単に「AIをオンにする」だけのフラグではありません。差分を見る限り、API仕様ファイル、MCP設定、認証情報をまとめて扱う構成になっています。(GitHub)
apiSpecPath はAPI仕様ファイルの配置確認が必要
apiSpecPath は、サイトファイル内の /home から見たAPI仕様ファイルへの相対パスです。(GitHub)
実務では、次のような確認が必要になります。
| 確認項目 | 具体例 |
|---|---|
| ファイル配置 | /home/site/wwwroot/openapi.json に配置するのか、別ディレクトリに置くのか |
| デプロイ方式 | ZIPデプロイ、コンテナー、GitHub Actions、Azure DevOpsで同じパスになるか |
| 環境差分 | 開発・検証・本番でファイル名や配置先が変わらないか |
| 更新タイミング | アプリ更新時にAPI仕様ファイルも確実に更新されるか |
失敗しやすいのは、アプリ本体のデプロイには成功しているのに、AI連携が参照するAPI仕様ファイルだけ古い、または存在しないケースです。将来的にこの設定を使う場合は、アプリのCI/CDにAPI仕様ファイルの生成・配置・検証を組み込むのが安全です。
mcp.servers は配列全体の置き換えに注意
McpSettings の servers には、MCPサーバー設定の配列が入ります。PRの説明では、この配列は更新時に全体が置き換えられ、個別サーバーを独立してPATCHできないこと、空配列はMCPの無効化または削除を示すことが明記されています。(GitHub)
これは実務上かなり重要です。
たとえば、現在2つのMCPサーバーが設定されている状態で、1つだけ変更したい場合でも、更新リクエストには原則として残したいサーバーも含めて送る必要があります。1件だけ送ると、もう1件が消える可能性を考慮しなければなりません。
更新時の考え方
| やりたいこと | 安全な考え方 |
|---|---|
| 既存サーバーの説明だけ変更する | 既存の servers 全体を取得し、変更対象だけ編集して全体を送る |
| 1つのサーバーを追加する | 現在の配列に新規サーバーを追加して全体を送る |
| 1つのサーバーを無効化する | 対象の enabled を false にし、他のサーバーも含めて送る |
| MCP設定を削除・無効化する | 空配列が無効化・削除を意味する点を理解して使う |
「PATCHだから一部だけ変わるだろう」と考えると危険です。mcp.servers は配列単位の置き換えとして扱う前提で、更新前に現在値を取得する処理を入れるべきです。
McpServerConfig では名前・エンドポイント・ツール一覧を管理する
McpServerConfig には、個別MCPサーバーの name、description、enabled、endpoint、toolList が含まれます。enabled は既定で true とされています。(GitHub)
設計時には、次のような命名・運用ルールを決めておくと管理しやすくなります。
| 項目 | 推奨される確認 |
|---|---|
name | 環境名や用途が分かる一意の名前にする |
description | 何のためのMCPサーバーかを運用者が読んで分かる内容にする |
enabled | 一時停止と削除を区別して使う |
endpoint | アプリのルーティング、認証、ネットワーク制限と矛盾しないか確認する |
toolList | 公開してよいツールだけを明示する |
特に toolList は、AIエージェントや外部クライアントから利用できる操作範囲に関わる可能性があります。便利だからといって広く公開するのではなく、用途ごとに必要最小限のツールに絞るのが基本です。
siteAuth はEasyAuthを使わない場合の認証確認が重要
SiteAuthInfo は、MCPエンドポイント向けの外部認証設定です。PR上では、EasyAuthが有効でない場合に使う外部認証設定として説明されています。項目には jwksUri、issuer、audience、wellKnownOpenIdConfiguration、scopes が含まれます。(GitHub)
この領域は、設定ミスがセキュリティ事故や接続失敗につながりやすい部分です。
| 項目 | 意味 | 失敗しやすいポイント |
|---|---|---|
jwksUri | JWT署名検証用のJWKS URL | URL誤り、鍵ローテーションへの未対応 |
issuer | 期待する iss クレーム | テナントや発行者URLの不一致 |
audience | 期待する aud クレーム | クライアントIDやAPI識別子の取り違え |
wellKnownOpenIdConfiguration | OIDCメタデータURL | 環境ごとのURL差分 |
scopes | OAuthスコープ | 必要以上に広い権限設定 |
認証設定は「つながればよい」ではなく、「想定した発行者・対象者・スコープだけを許可しているか」を確認する必要があります。特にMCPのようにツール実行と結びつく可能性がある構成では、認可範囲を広げすぎないことが重要です。
既存環境への影響範囲
今回の変更は、App Serviceの既存アプリが突然壊れるというより、APIバージョン 2026-03-15 を採用したときに構成モデルやSDK型に影響が出る可能性がある変更です。
PRは2026年5月5日時点でAPI変更チェックが行われ、App Service関連のGo、Java、JavaScript、TypeSpecのAPIレビューが作成されています。レビュー状況としては一部承認が確認できる一方、PRページ上ではオープン状態として表示されています。(GitHub)
影響を整理すると、次のようになります。
| 対象 | 影響の可能性 | 今すぐやること |
|---|---|---|
| Azure PortalだけでApp Serviceを管理している人 | 低 | 仕様確定後に機能提供状況を確認 |
| Azure REST APIを直接使う人 | 中〜高 | 2026-03-15 採用予定とJSON処理を確認 |
| SDKでApp Serviceを管理する人 | 中〜高 | SDK更新時の型変更・生成差分を確認 |
| IaCでApp Serviceを管理する人 | 中 | プロバイダー追従後の差分管理方針を確認 |
| MCPやAI連携を検討している人 | 高 | 認証、API仕様ファイル、ツール公開範囲を設計 |
重要なのは、aiIntegration を使う予定がないチームでも、App Serviceの更新処理が既存構成を丸ごと送信する設計になっている場合です。PUTやPATCHの実装次第では、新しいプロパティを保持するか、無視するか、消してしまうかが問題になる可能性があります。
移行・設定確認で見るべきチェックリスト
API仕様変更を見たときは、単に「新しいプロパティが増えた」で終わらせず、自分たちの管理方法に照らして確認することが大切です。
APIバージョンの採用状況を確認する
まず、自社コードやIaC、SDKがどのAPIバージョンを使っているかを確認します。
確認対象の例は次のとおりです。
- REST API呼び出しURLの
api-version - SDKのパッケージバージョン
- ARMテンプレートやBicepのリソースAPIバージョン
- TerraformやPulumiなどのプロバイダー更新履歴
- CI/CD内のAzure管理スクリプト
- 独自ツールのApp Service更新処理
2026-03-15 をまだ使っていない場合、すぐに影響が出る可能性は限定的です。ただし、将来的にAPIバージョンを上げる予定があるなら、移行テストの観点に aiIntegration を含めておくと安全です。
App Serviceの更新処理を確認する
次に、App Serviceの設定更新がどのように実装されているかを確認します。
特に注意したいのは、取得したリソース定義を加工してそのまま更新する処理です。新しいプロパティが追加された場合、古いクライアントがその項目を落として送信すると、環境によっては設定が失われる可能性があります。
安全な設計は、変更したい項目だけを明確に扱い、未知のプロパティを不用意に消さないことです。配列全体が置き換わる mcp.servers のような項目では、更新前に現在値を取得し、必要な要素を保持したうえで送信する手順が重要になります。
SDK更新時は型チェックと生成差分を確認する
SDKを使っている場合、パッケージ更新時に次の確認を行います。
| 確認項目 | 見るべき内容 |
|---|---|
| コンパイル・型チェック | 新しいモデル追加で既存コードが失敗しないか |
| 生成コード差分 | AiIntegration、McpSettings、SiteAuthInfo が追加されているか |
| シリアライズ処理 | 未設定時に不要な空オブジェクトを送っていないか |
| テストデータ | スナップショットやモックJSONに差分が出ないか |
| ラッパー実装 | 自社独自のApp Serviceモデルに新項目を追加する必要があるか |
GoやJavaScriptの破壊的変更ラベルが付いているため、これらの言語でApp Service SDKを使っている場合は特に注意が必要です。(GitHub)
設定例を考えるときのポイント
現時点ではPR段階の仕様変更であり、実際の利用可否やAzure Portalでの表示、SDKの正式リリース状況は確認が必要です。そのため、ここでは確定した手順としてではなく、設定を検討する際の考え方として整理します。
たとえば、App Service上のアプリでMCPエンドポイントを公開し、API仕様ファイルを参照させたい場合、設定設計では次の順番で考えると安全です。
| 手順 | 確認内容 |
|---|---|
| API仕様ファイルを決める | OpenAPIなどの仕様ファイルをどこに置くか |
| MCPサーバーを定義する | 名前、説明、エンドポイント、公開ツールを決める |
| 認証方式を決める | EasyAuthを使うか、外部認証設定を使うか |
| 権限範囲を絞る | 必要なスコープと対象audienceを明確にする |
| 更新方法を決める | REST API、SDK、IaCのどれで管理するか |
| テストする | 認証失敗、ファイル未配置、空配列更新を検証する |
この順番を守ると、「エンドポイントは作ったがAPI仕様ファイルが参照できない」「認証は通るが想定外のツールまで公開される」「更新時にMCPサーバー一覧が消える」といった失敗を避けやすくなります。
注意すべき失敗パターン
今回の変更で実務上起こりやすい失敗は、主に4つです。
空配列でMCP設定を消してしまう
mcp.servers の空配列は、MCPを無効化または削除する意味を持つと説明されています。(GitHub)
そのため、初期化処理やフォーム送信で servers: [] を意図せず送ってしまうと、既存のMCP設定を失う可能性があります。UIや管理ツールを作る場合は、未変更と空配列を明確に区別してください。
enabled の既定値を誤解する
McpServerConfig の enabled は既定で true とされています。(GitHub)
つまり、無効状態で登録したい場合は、明示的に false を設定する必要があります。検証環境で一時的に作ったMCPサーバーが、意図せず有効状態になる運用は避けるべきです。
認証設定を環境ごとに分けていない
issuer、audience、jwksUri、OIDCメタデータURLは、テナントや環境によって変わることがあります。開発環境の値を本番に流用すると、接続失敗だけでなく、誤った発行者を信頼する設定ミスにつながります。
環境ごとに設定値を分離し、シークレットや認証関連の値はCI/CD上で安全に注入する設計が必要です。
API仕様ファイルの更新をアプリ更新と分離してしまう
apiSpecPath が参照するファイルが古いままだと、AI連携やMCP側が実際のアプリ仕様とずれる可能性があります。
API仕様ファイルを手動で配置するのではなく、アプリのビルドやデプロイの中で自動生成・自動配置する仕組みにしておくと、運用ミスを減らせます。
今回の更新を確認する実務フロー
Azure REST APIの仕様更新に対応するときは、次の流れで確認すると抜け漏れを防ぎやすくなります。
| 順番 | 作業 | 判断基準 |
|---|---|---|
| 1 | PRの状態を確認 | マージ済みか、まだPR段階か |
| 2 | 対象APIバージョンを確認 | 2026-03-15 を使う予定があるか |
| 3 | 対象リソースを確認 | App Service / Function App管理に関係するか |
| 4 | SDK影響を確認 | 使用言語のSDKに破壊的変更が出ていないか |
| 5 | 更新処理を確認 | PUT/PATCHで未知プロパティを落とさないか |
| 6 | 認証設定を確認 | EasyAuth利用有無、OIDC/JWT設定が明確か |
| 7 | CI/CDに反映 | API仕様ファイル配置、テスト、差分検出を組み込む |
このフローで確認すれば、仕様変更そのものを追いかけるだけでなく、自社環境で実際に影響が出る場所まで絞り込めます。
すぐ対応すべきケースと、様子見でよいケース
すべてのAzure利用者が今すぐ対応する必要はありません。対応優先度は、Azure REST APIやSDKへの依存度で判断します。
| 状況 | 優先度 | 理由 |
|---|---|---|
| App ServiceをREST APIで自動管理している | 高 | APIバージョン更新時にモデル差分の影響を受けやすい |
| GoまたはJavaScript SDKでApp Serviceを管理している | 高 | PR上で破壊的変更ラベルが付いている |
| MCPやAI連携機能を検証予定 | 高 | AiIntegration の中心的な利用者になる可能性がある |
| IaCでApp Serviceを厳密に管理している | 中 | 将来のプロバイダー追従時に差分管理が必要 |
| Azure Portal中心で手動管理している | 低 | 現時点ではREST API仕様変更の影響が限定的 |
| App Serviceを使っていない | 低 | 対象サービス外 |
高優先度に該当する場合は、PRとAPI仕様の状態を継続的に確認し、検証環境でSDKやREST APIの差分を試す準備を進めてください。低優先度の場合でも、将来的にAI連携やMCPを使う可能性があるなら、変更内容だけは把握しておくと判断が早くなります。
まとめ：Azure REST APIのAiIntegration追加は、App Service自動管理チームほど早めに確認したい変更
「Azure REST API documentation update: Add AiIntegration to API version 2026-03-15」は、Azure App ServiceのREST API仕様にAI連携設定を追加する変更です。中心となるのは aiIntegration プロパティで、API仕様ファイルのパス、MCPサーバー設定、外部認証設定を扱う構成になっています。
特に確認すべきポイントは次の3つです。
api-version=2026-03-15を使う予定があるか- App Serviceの更新処理で
aiIntegrationやmcp.serversを正しく保持できるか - SDK更新時にGo、JavaScript、Java、TypeSpecの生成差分を確認しているか
現時点ではPR段階の情報であり、正式な提供状況や各SDK・IaCツールへの反映は継続確認が必要です。ただし、App ServiceをREST APIやSDKで管理しているチームにとっては、後から慌てて対応するより、今のうちにAPIバージョン、更新処理、認証設定、CI/CDでのAPI仕様ファイル配置を点検しておく方が安全です。
まずは自社環境で使っているAzure REST APIのバージョンとApp Service管理方法を確認し、2026-03-15 へ移行する可能性がある場合は、検証環境で aiIntegration を含むリソース定義の取得・更新・差分検出をテストしてください。
コメント