2026年5月1日に更新された Azure REST API documentation update「remove isolation key with wrong header」は、単なる表記修正ではありません。結論から言うと、x-session-isolation-key という誤ったヘッダーで公開・生成されていた isolation key 関連の項目を、仕様からいったん削除する変更です。PRの説明では、バックエンド側は x-user-isolation-key を見ている一方、クライアント側は x-session-isolation-key を送っていたため、isolation key が無視され、Entra isolation が使われていたとされています。すぐに正しいヘッダー名へ置き換えると顧客のダウンタイムにつながる可能性があるため、まずフィールドを削除し、後日正しい形で再導入する方針が示されています。(GitHub)
Azure REST APIや生成SDKを使っている開発者がまず確認すべきなのは、自分のコードが x-session-isolation-key、isolation_key、isolation_key_source に依存していないかです。特に Azure AI Foundry のデータプレーンAPI、Agentsのセッション作成・削除処理、TypeSpec/OpenAPIから自動生成したクライアントを使っている場合は、仕様変更の影響を受ける可能性があります。
Azure REST APIのisolation keyヘッダー削除で何が変わったか
今回のPR #42825 は、GitHub上では「remove isolation key with wrong header」というタイトルで、2026年5月1日に最終コミット「remove isolation key field that had wrong header」が追加され、同日にPRがClosedになっています。(GitHub)
変更の中心は、Azure REST APIの仕様上に存在していた isolation key 関連フィールドの削除です。最終コミットでは、主に次の2ファイルが変更されています。
| 変更対象 | 削除された内容 | 実務上の意味 |
|---|---|---|
src/agents/models.tsp | EntraAuthorizationScheme から isolation_key_source を削除 | 認可スキームの設定項目として isolation key source を扱わない方向になる |
src/agents/routes.tsp | @header("x-session-isolation-key") isolation_key: string; をセッション作成・削除系の定義から削除 | APIクライアントや生成SDKで、該当ヘッダー引数が消える可能性がある |
PRの差分では、models.tsp 側で EntraAuthorizationScheme から isolation_key_source が削除され、routes.tsp 側では「session-mutating operations」に使われていた x-session-isolation-key のヘッダー定義が、セッション作成と削除の箇所から削除されています。(GitHub)
重要なのは、これは「x-session-isolation-key を x-user-isolation-key に置き換えればよい」という単純な話ではない点です。PRの説明では、即時にヘッダー名を修正すると顧客のダウンタイムにつながる可能性があるため、まずフィールドを削除し、利用者側が更新時に対応できるようにしたうえで、後から正しいフィールドを再導入する方針が示されています。(GitHub)
対応が必要になりやすい利用者
今回のAzure REST API仕様変更で、すべてのAzure利用者が対応を迫られるわけではありません。影響が出やすいのは、Azure AI Foundry系のデータプレーンAPIや、その仕様から生成されたSDKを使っているケースです。
| 利用状況 | 対応優先度 | 確認すべきこと |
|---|---|---|
REST APIを直接呼び出し、x-session-isolation-key を送っている | 高 | ヘッダーが実際に有効だった前提で設計していないか |
| TypeSpec/OpenAPIからクライアントを自動生成している | 高 | 再生成後に isolation_key 引数が消え、ビルドやテストが壊れないか |
| Azure SDKのプレビュー版を使ってAgentsのセッション作成・削除をしている | 中〜高 | SDK更新後にメソッドシグネチャが変わらないか |
| ARMの管理プレーンAPIのみ使っている | 低 | 今回の差分はデータプレーン側であり、直接影響は限定的 |
| isolation keyを使っていない | 低 | 念のためコード検索だけ行えばよい |
特に注意したいのは、マルチユーザーアプリで「このヘッダーを付けているからセッション所有者の分離ができている」と考えていたケースです。PR説明では、誤ったヘッダー名により isolation key はバックエンドで無視され、Entra isolation が使われていたとされています。つまり、アプリケーション側の設計によっては、期待していた分離境界と実際の分離境界が一致していなかった可能性があります。(GitHub)
最初に実施すべきコード確認
まずは、コードベース全体で該当する文字列を検索してください。REST APIを直接呼んでいる場合だけでなく、HTTPクライアントの共通処理、SDKラッパー、テストコード、IaCテンプレート、API仕様から生成したファイルも対象にします。
grep -R "x-session-isolation-key\|isolation_key_source\|isolation_key" .PowerShellを使う場合は、次のように検索できます。
Get-ChildItem -Recurse -File |
Select-String -Pattern "x-session-isolation-key","isolation_key_source","isolation_key"検索で見つかった箇所は、単に削除するのではなく、次の観点で分類します。
| 見つかった箇所 | 判断基準 | 対応例 |
|---|---|---|
| HTTPリクエストヘッダーに直接追加している | Azure REST APIの該当エンドポイント向けか | SDK・公式仕様に合わせて削除または互換処理へ移す |
| SDKメソッドの引数として渡している | SDK更新後に引数が残るか | 新旧SDKの差分を確認し、ラッパー関数で吸収する |
| テストで必須ヘッダーとして検証している | 現行仕様でも必須といえるか | テスト期待値を更新する |
| 認可・分離の設計資料に書いている | 実際の分離方式と一致しているか | Entra ID、ユーザーID、セッション所有者管理の記述を見直す |
| OpenAPI/TypeSpec生成物に残っている | 生成元の仕様が古くないか | 生成元のバージョンを固定し、更新タイミングを管理する |
移行時にやってはいけない対応
今回の変更で失敗しやすいのは、「間違っていたヘッダー名を見つけたから、すぐ正しい名前に変える」という対応です。PRでは、バックエンドが x-user-isolation-key を見ていると説明されていますが、同時に、すぐにヘッダー名を修正するとダウンタイムにつながる可能性があるため、まずフィールドを削除するとされています。(GitHub)
そのため、次の対応は避けるべきです。
x-session-isolation-keyを独自判断でx-user-isolation-keyに一括置換する- SDK更新前後で動作確認せず、本番環境へ反映する
- 「ヘッダーが無視されていたなら不要」と決めつけ、認可設計の確認を省略する
- 仕様PRだけを根拠に、本番APIの挙動がすでに変わったと断定する
- プレビューAPIの変更を、GA APIと同じ安定性で扱う
特に本番アプリでは、ヘッダーの有無だけでなく「誰の認証情報でAPIを呼び出しているか」「セッションIDとユーザーIDの対応をどこで保証しているか」を確認してください。共有のアプリケーションIDで複数ユーザーのセッションを扱っている場合、Entra isolationだけで期待するユーザー単位の分離が満たされるとは限りません。
実務での移行・設定確認手順
Azure REST APIの仕様変更に対応する際は、いきなり実装修正に入るより、影響範囲を切り分けるほうが安全です。次の順で進めると、ビルドエラー、認可不備、SDK更新時の混乱を避けやすくなります。
| 手順 | 作業内容 | 完了条件 |
| -: | —————————————————— | ————————————– |
| 1 | x-session-isolation-key と isolation_key の利用箇所を検索する | 利用箇所をAPI呼び出し、SDK引数、テスト、設計資料に分類できている |
| 2 | 該当APIがセッション作成・削除系か確認する | 変更対象と関係する呼び出しだけを抽出できている |
| 3 | SDKまたは生成クライアントのバージョンを確認する | 仕様更新前後でメソッド引数や必須パラメータが変わるか分かっている |
| 4 | 認可・分離の設計を確認する | isolation keyに依存していた前提がないか説明できる |
| 5 | ステージング環境でセッション作成・削除をテストする | 正常系だけでなく、別ユーザーのセッション操作が拒否されることを確認できている |
| 6 | 本番反映時の監視項目を決める | 401、403、404、セッション削除失敗、ユーザー混線の疑いを検知できる |
テストでは、単に「APIが成功するか」だけを見ると不十分です。少なくとも、次のケースを用意してください。
ユーザーAが作成したセッションを、ユーザーAが削除できる
ユーザーAが作成したセッションを、ユーザーBが削除できない
存在しないセッションIDを指定したとき、期待どおりのエラーになる
SDK更新前後で、不要な isolation_key 引数が残っていない
ログに古い x-session-isolation-key が出続けていないこの確認により、「ヘッダーを消しても動いた」ではなく、「想定した所有者分離が保たれている」と判断できます。
SDK利用者が注意すべきポイント
Azure REST APIの仕様変更は、手書きのREST呼び出しだけでなく、SDK利用者にも影響します。TypeSpecやOpenAPIから生成されたSDKでは、仕様上のヘッダー定義が削除されると、メソッド引数やリクエストモデルから isolation_key が消える可能性があります。
たとえば、以前のコードが次のような形だった場合、SDK更新後にビルドエラーになることがあります。
# 例：古いSDKや独自生成クライアントで isolation_key を渡していた場合
client.create_session(
agent_name="support-agent",
isolation_key=user_id,
body=request_body
)更新後は、SDKの公式シグネチャに合わせて不要な引数を削除する必要があります。ただし、単純に削除して終わりではありません。user_id を isolation key として渡していたなら、その値が本来どの分離・監査・認可ロジックで使われるべきだったのかを確認してください。
安全な移行方針は、アプリケーション側に薄いラッパー関数を置き、SDKの変更を吸収することです。
def create_agent_session(client, agent_name: str, request_body: dict, user_id: str):
# user_id は監査ログやアプリ側の所有者チェックに使う
audit_user_access(user_id=user_id, agent_name=agent_name)
# SDKの現行仕様に合わせ、不要になった isolation_key は渡さない
return client.create_session(
agent_name=agent_name,
body=request_body
)このようにしておくと、後日正しいヘッダーやフィールドが再導入された場合も、呼び出し箇所を大量に修正せず、ラッパー内で対応しやすくなります。
PRの状態だけで本番反映を判断しない
今回のPRは、GitHub上ではClosedになっています。また、GitHub Actionsのコメントでは、このPRが main ブランチを対象としており、マージ後のAPIはAzure顧客に出荷されたものとみなされ、以後のインプレース変更はバージョニングや破壊的変更ポリシーの対象になる旨が示されています。一方で、同じコメントでは TypeSpec Validation が失敗していることも表示されています。(GitHub)
そのため、実務では次のように判断するのが安全です。
| 情報 | 判断 |
|---|---|
| PR本文 | 変更意図を理解するための一次情報 |
| 差分 | どのフィールド・ヘッダーが仕様上削除されたかを確認する材料 |
| PRのClosed状態 | 変更が検討されたことは分かるが、SDKや本番APIへの反映完了とは別に確認が必要 |
| TypeSpec Validation失敗 | その時点のPRだけで安定版仕様とみなすのは避ける |
| SDKリリースノート・公式ドキュメント | 実装反映の最終確認に使うべき情報 |
つまり、今回の変更は「コードを即日一括修正するニュース」ではなく、「isolation keyに依存した設計や生成クライアントを点検する合図」と捉えるべきです。
影響調査で見るべきログと監視項目
本番運用では、仕様変更後に見た目上エラーが増えなくても、認可やセッション所有者の扱いに問題が残ることがあります。次のログを確認してください。
| 確認対象 | 見るべきポイント |
|---|---|
| APIゲートウェイやプロキシログ | x-session-isolation-key が送信され続けていないか |
| アプリケーションログ | セッション作成者、操作ユーザー、セッションIDが対応しているか |
| 認可エラーログ | SDK更新後に401、403、404が増えていないか |
| 監査ログ | 別ユーザーのセッション削除や参照の試行が検出できるか |
| CIログ | 生成SDKの再生成後に isolation_key 関連の型エラーが出ていないか |
特に、旧ヘッダーを送っていてもバックエンドで無視されていた可能性があるため、「エラーが出ていなかったから安全」とは判断できません。エラーの有無ではなく、セッション所有者と認証主体の対応関係を確認することが重要です。
今回の変更への現実的な対応方針
今回のAzure REST API documentation updateでは、x-session-isolation-key という誤ったヘッダーに紐づく isolation key フィールドが仕様から削除されています。バックエンド側では別のヘッダーを見ていたため、従来のヘッダーは無視され、Entra isolationが使われていたと説明されています。(GitHub)
対応の優先順位は明確です。まずコードと生成物から該当文字列を検索し、次にSDKやREST呼び出しの影響を切り分け、最後に認可・セッション所有者の分離が実際に保たれているかをテストします。独自判断で x-user-isolation-key に置き換えるのではなく、公式仕様やSDKの更新に合わせて段階的に対応してください。
最初に取るべき行動は、次の3つです。
- コードベース全体で
x-session-isolation-key、isolation_key、isolation_key_sourceを検索する - Agentsのセッション作成・削除処理で使っていないか確認する
- マルチユーザー環境では、Entra認証とアプリ側のセッション所有者チェックで分離が成立しているかテストする
この3点を確認できれば、今回の仕様変更によるビルドエラーやSDK更新時の混乱だけでなく、見落としやすい認可設計のズレも早期に検出できます。
コメント