MENU

Azure REST APIのisolation key削除対応｜wrong header変更点と確認手順

Azure

Azure REST APIの「remove isolation key field that had wrong header」は、Azure AI Foundry系のData Plane API仕様から、誤ったヘッダーに紐づいていたisolation_key関連フィールドを削除する更新です。結論から言うと、Hosted Agent SessionsやAzure.AI.Projects系のクライアントでx-session-isolation-keyを送っている実装、またはAPI仕様からSDKを生成しているチームは確認が必要です。単なるドキュメント修正ではなく、PR上ではクライアントに影響し得るbreaking changeとして説明されています。(GitHub)

今回のポイントは、「isolation keyを使わなくなる」ではありません。誤ったヘッダー名に紐づいたフィールドが仕様から外され、実運用ではx-ms-user-isolation-keyやMicrosoft Entraによるスコープ分離の扱いを確認すべきという変更です。Microsoft LearnのHosted Agent Sessionsドキュメントは2026年5月5日に更新され、Header方式ではx-ms-user-isolation-keyを使うこと、Entra方式ではトークンから分離キーが導出されることが説明されています。(Microsoft Learn)

日程Fit。無料・登録不要。「いつ空いてる？」を、ひとつのリンクで。リンクを送って、○△×でかんたん日程調整。無料で日程を作る。
目次

Azure REST APIで何が変わったのか

GitHubのAzure REST API仕様リポジトリにあるPR #42827「remove isolation key field that had wrong header」では、Azure AI FoundryのData Plane API仕様に含まれるagents関連のTypeSpecファイルが変更されています。PRは2026年5月4日にfeature/foundry-releaseブランチへマージされ、変更量は2ファイルで9行削除です。(GitHub)

変更された主なファイルは次の2つです。

変更ファイル主な変更内容実務上の意味
models.tspEntraAuthorizationSchemeからisolation_key_sourceを削除Entra認可スキームのモデル定義に含まれていた分離キー関連フィールドが見直された
routes.tsp@header("x-session-isolation-key")に紐づくisolation_keyパラメーターを削除生成クライアントやREST呼び出しで、誤ったヘッダー名を前提にしないようにする必要がある

特に重要なのは、routes.tspで削除されたヘッダー名がx-session-isolation-keyだった点です。PRの説明では、クライアントがバックエンドの期待するヘッダーとは異なるヘッダーを送っている状態だったため、単純に正しいヘッダーへ差し替えるとアプリが静かに壊れる可能性がある、とされています。そのため、いったん誤ったヘッダーに紐づくフィールドを削除し、利用者が誤ったヘッダー送信をやめたうえで、正しいヘッダーに紐づく形で再導入する方針が示されています。(GitHub)

影響を受ける可能性が高い利用者

今回のAzure REST API更新は、Azure全体のREST API利用者すべてに影響するものではありません。影響範囲は、Azure AI FoundryのHosted Agent SessionsやAzure.AI.ProjectsのData Plane APIを使っているケースに寄ります。

利用状況影響度確認すべきこと
REST APIを直接呼び出してHosted Agent Sessionsを作成・削除している高x-session-isolation-keyを送っていないか確認する
azure-ai-projectsなどのSDKでセッション作成・削除を使っている中〜高SDK更新後にisolation_key引数や生成モデルが変わらないか確認する
TypeSpec/OpenAPIから社内SDKを生成している高最新仕様で再生成し、型定義・テスト・モックを更新する
API Gatewayやプロキシでヘッダー制御をしている中x-ms-user-isolation-keyをブロック・書き換えしていないか確認する
Azure Resource Managerの管理APIだけを使っている低今回のData Plane API変更とは直接関係しにくい

Hosted Agent Sessionsのドキュメントでは、セッション操作はプレビュー機能であり、RESTリクエストにはFoundry-Features: HostedAgents=V1Previewヘッダーが必要とされています。また、az restでFoundry Agent ServiceのData Planeエンドポイントを呼ぶ場合は、--resource "https://ai.azure.com"が必要です。 (Microsoft Learn)

isolation keyの役割を正しく理解する

isolation keyは、セッションを利用者やテナント単位で分離するためのスコープ値です。認証や認可そのものではありません。

Microsoft Learnでは、isolation keyは「partitioning value」であり、認証と認可はMicrosoft Entraトークンとプロジェクトのロール割り当てによって行われると説明されています。つまり、isolation keyを送っているから安全、という設計にはできません。(Microsoft Learn)

実務では、次のように考えると判断しやすくなります。

観点isolation keyMicrosoft Entra / RBAC
主な役割セッションのスコープ分離呼び出し元の認証・認可
例ユーザーAのセッションとユーザーBのセッションを分けるそのユーザーがプロジェクトを操作できるか判断する
失敗しやすい点認可の代わりに使ってしまうisolation keyなしでマルチテナント分離できると誤解する

たとえばSaaSアプリで、同じAzure AI Foundryプロジェクト上に複数テナントのエージェントセッションを作る場合、isolation keyはテナントやエンドユーザーのスコープ分離に使えます。ただし、「そのユーザーが本当にそのテナントに属しているか」はアプリケーション側で検証する必要があります。

正しいヘッダーはx-ms-user-isolation-key

今回の変更で注意すべきヘッダーは、x-session-isolation-keyではなくx-ms-user-isolation-keyです。

Hosted Agent Sessionsのドキュメントでは、isolation keyの設定方法はエージェントエンドポイントの認可スキームによって異なるとされています。Entra方式では、プラットフォームがMicrosoft Entraトークンからisolation keyを導出し、x-ms-user-isolation-keyヘッダーは受け付けられるものの無視されます。一方、Header方式では、プラットフォームがx-ms-user-isolation-keyヘッダーからisolation keyを読み取り、ヘッダーがないリクエストは失敗します。(Microsoft Learn)

誤った実装例

次のようにx-session-isolation-keyを送る実装は、今回の仕様変更で見直すべき対象です。

az rest --method POST \
  --url "${BASE_URL}/agents/${AGENT_NAME}/endpoint/sessions?api-version=${API_VERSION}" \
  --resource "${RESOURCE}" \
  --headers "x-session-isolation-key=user-123" "Foundry-Features=HostedAgents=V1Preview" \
  --body '{}'

このヘッダー名は、PRで削除対象になった誤ったヘッダーに該当します。仕様から削除されるため、今後のSDK生成やドキュメント反映後に、クライアント側の型や引数が変わる可能性があります。

Header方式での確認例

Header方式のエンドポイントでisolation keyを明示する場合は、x-ms-user-isolation-keyを使います。

az rest --method POST \
  --url "${BASE_URL}/agents/${AGENT_NAME}/endpoint/sessions?api-version=${API_VERSION}" \
  --resource "${RESOURCE}" \
  --headers "x-ms-user-isolation-key=user-123" "Foundry-Features=HostedAgents=V1Preview" \
  --body '{}'

削除時も同じ考え方です。

az rest --method DELETE \
  --url "${BASE_URL}/agents/${AGENT_NAME}/endpoint/sessions/${SESSION_ID}?api-version=${API_VERSION}" \
  --resource "${RESOURCE}" \
  --headers "x-ms-user-isolation-key=user-123" "Foundry-Features=HostedAgents=V1Preview"

Microsoft Learnのセッション作成・削除例でも、REST APIのヘッダーとしてx-ms-user-isolation-keyが使われています。(Microsoft Learn)

Entra方式とHeader方式で対応が変わる

今回の変更で混乱しやすいのは、「isolation keyを送るべきかどうか」が認可スキームによって変わる点です。

認可スキームisolation keyの決まり方クライアント側の対応
EntraMicrosoft Entraトークンから導出ヘッダーで無理に指定しない。呼び出し元IDと権限設計を確認する
Headerx-ms-user-isolation-keyヘッダーから読み取るすべてのセッション関連リクエストに安定したキーを送る
BotServiceRbacなど他方式仕様・ドキュメントに従うSDKやREST APIの最新リファレンスを確認する

Header方式では、セッション作成時だけでなく、セッション削除、呼び出し、ファイル操作など、セッションに関連する操作で一貫したキーを使う必要があります。Microsoft Learnでは、isolation keyはセッション関連エンドポイント全体に一貫して適用されると説明されています。(Microsoft Learn)

たとえば、作成時にuser-123を使い、削除時にtenant-aを送ると、同じセッションを操作できない可能性があります。マルチテナントアプリでは、キーの生成ルールを「その場で適当に作る」のではなく、アプリケーションのユーザーIDまたはテナントIDに基づいて固定することが重要です。

まず確認すべきコードと設定

今回のAzure REST API仕様変更を受けて、最初に行うべき作業は影響箇所の棚卸しです。特に、次の文字列でコード、IaC、API Gateway設定、テストコード、社内ドキュメントを検索してください。

x-session-isolation-key
x-ms-user-isolation-key
isolation_key
isolation_key_source
EntraAuthorizationScheme
create_session
delete_session
HostedAgents=V1Preview

確認の優先順位は次の通りです。

優先度確認対象見つかった場合の対応
高x-session-isolation-key誤ったヘッダーとして削除・置換を検討する
高REST APIのセッション作成・削除Header方式かEntra方式かを確認する
高SDK生成コード最新仕様で再生成し、型エラーを確認する
中API Gatewayの許可ヘッダーx-ms-user-isolation-keyを落としていないか確認する
中テスト・モック古いヘッダー名を前提にしていないか確認する
中社内手順書開発者が古いヘッダーをコピーしないよう修正する

特にAPI Gatewayやリバースプロキシを挟んでいる構成では、ヘッダーの許可リストに注意が必要です。クライアント側でx-ms-user-isolation-keyを正しく送っていても、途中のプロキシで削除されると、Header方式のエンドポイントではセッション操作が失敗する可能性があります。

SDK利用者が注意すべき点

SDKを使っている場合、REST APIのヘッダーを直接書いていないため影響が見えにくくなります。しかし、Azure REST API仕様の変更は生成SDKに反映される可能性があるため、SDK更新時には必ずビルドと統合テストを行ってください。

Microsoft LearnのHosted Agent Sessionsドキュメントでは、Python SDKのcreate_sessionとdelete_sessionでisolation_keyキーワードが必要とされています。ただし、サーバーがそれを強制するのは、エージェントエンドポイントがHeaderからキーを読むよう設定されている場合のみです。(Microsoft Learn)

一方で、PRではEntraAuthorizationSchemeからisolation_key_sourceが削除されています。2026年5月6日時点では、一部のSDKリファレンスにisolation_key_sourceが掲載されているページも確認できます。これは、仕様変更、SDK生成、ドキュメント反映のタイミングに差が出るためです。(Microsoft Learn)

SDK利用者は、次のように対応すると安全です。

状況推奨対応
本番直前でSDKを更新する予定がない現在のSDKバージョンを固定し、変更を急がない
SDKを更新する予定がある更新前後でcreate_session、delete_session、エンドポイント設定のテストを実行する
EntraAuthorizationScheme(isolation_key_source=...)を書いているSDK更新後に引数が残るか確認し、不要になった場合は削除する
社内SDKをTypeSpec/OpenAPIから生成している最新仕様で再生成し、削除されたフィールドを参照している箇所を修正する

SDKの型エラーだけで判断せず、実際にセッション作成、一覧取得、削除、別ユーザー・別キーでのアクセス不可確認まで行うことが重要です。

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

今回の変更に対しては、いきなり全コードを書き換えるより、影響確認、テスト、段階的な修正の順で進めるのが安全です。

現在の認可スキームを確認する

まず、対象のエージェントエンドポイントがEntra方式なのか、Header方式なのかを確認します。

Entra方式であれば、isolation keyはMicrosoft Entraトークンから導出されます。この場合、クライアントがx-ms-user-isolation-keyを送ってもスコープ変更には使われません。

Header方式であれば、x-ms-user-isolation-keyが必須です。エンドユーザー単位、テナント単位、組織単位など、どの粒度で分離するかをアプリ側で決め、同じ利用者には同じキーを送るようにします。

古いヘッダーを削除する

x-session-isolation-keyを送っている箇所があれば、削除またはx-ms-user-isolation-keyへの置換を検討します。

ただし、単純置換では不十分です。Entra方式ではx-ms-user-isolation-keyを送っても無視されるため、アプリが「このヘッダーでユーザーを切り替えられる」と期待している場合、設計そのものを見直す必要があります。

セッション操作を一通りテストする

最低限、次のテストを実行してください。

テスト確認内容
セッション作成正しいヘッダーまたはEntraトークンで作成できるか
セッション取得作成したセッションを同じスコープで取得できるか
セッション削除作成時と同じスコープで削除できるか
異なるキーでの操作Header方式で別キーから操作できないか
異なるユーザーでの操作Entra方式で別ユーザーから意図せず操作できないか
ファイル操作セッション配下のファイル操作が同じスコープで動くか

Hosted Agent Sessionsでは、セッションIDの扱いにも注意が必要です。Invocationsエンドポイントでは、セッションIDはagent_session_idクエリパラメーターから読み取られ、ボディやx-agent-session-idのようなヘッダーに入れてもルーティングには影響しないと説明されています。(Microsoft Learn)

失敗しやすいポイント

isolation keyを認可の代わりに使ってしまう

isolation keyはセッション分離のための値であり、認可ではありません。たとえば、ユーザーが任意のx-ms-user-isolation-keyを指定できる画面やAPIを作ると、Header方式では別ユーザーや別テナントのキーを推測されるリスクがあります。

アプリケーション側で、ログインユーザーとisolation keyの対応を必ず管理してください。エンドユーザーから受け取った文字列をそのままヘッダーに入れる設計は避けるべきです。

セッション作成時だけキーを送る

Header方式では、作成時だけでなく、削除、呼び出し、ファイル操作などでも同じスコープを使う必要があります。作成時は成功するのに削除できない、ファイルが見えない、といったトラブルは、キーの不一致が原因になりやすいです。

SDKの引数名だけを見て安心する

SDKにisolation_key引数が残っていても、内部でどのヘッダーに変換されるか、サーバーがどの認可スキームで解釈するかは別問題です。今回のPRは「誤ったヘッダーに紐づくフィールドを削除する」変更であるため、SDK更新後の実通信をテストで確認する必要があります。

ドキュメントの反映タイミング差を見落とす

PR、Microsoft Learn、SDKリファレンス、生成SDKは同時に更新されるとは限りません。今回のようなプレビュー機能では、仕様変更が先に入り、SDKや言語別リファレンスが後から追いつくケースがあります。

そのため、移行判断では次の3点をセットで見るのが安全です。

確認対象見るべき内容
GitHub PR仕様上、何が削除・追加されたか
Microsoft LearnのHow-to実際のREST呼び出し例でどのヘッダーを使っているか
SDKリファレンス・リリースノート利用中のSDKバージョンで引数やモデルがどうなっているか

チーム内で決めておきたい運用ルール

マルチユーザー、マルチテナントのアプリでHosted Agent Sessionsを使う場合、isolation keyの設計は後回しにしない方がよい領域です。今回の変更を機に、次のルールを明文化しておくと運用トラブルを減らせます。

決めること推奨例
分離単位個人単位、テナント単位、組織単位のどれにするか決める
キー生成元アプリ内のユーザーIDやテナントIDから生成する
キーの扱いユーザー入力値を直接使わない
ログ出力必要最小限にし、個人情報や推測可能な値を避ける
テスト別ユーザー・別テナントから操作できないことを自動テストに入れる
SDK更新本番反映前にセッション作成・削除・ファイル操作の統合テストを実行する

特にログには注意が必要です。isolation key自体がパスワードではないとしても、ユーザーIDやテナントIDに近い値を含む場合があります。監査やトラブルシュートに必要な範囲を超えて出力しないようにしましょう。

今回の変更で取るべき次の行動

今回のAzure REST API仕様更新は、誤ったヘッダー名に基づくisolation_key関連フィールドを削除するものです。対象は主にAzure AI FoundryのHosted Agent SessionsやAzure.AI.Projects系のData Plane API利用者で、特にx-session-isolation-keyを送っている実装は優先的に見直す必要があります。

対応の順序は次の通りです。

  1. コードと設定からx-session-isolation-keyを検索する
  2. 対象エンドポイントがEntra方式かHeader方式か確認する
  3. Header方式ではx-ms-user-isolation-keyを一貫して送る
  4. Entra方式ではヘッダーではなくトークン由来のスコープ分離を前提にする
  5. SDK更新時は型チェックだけでなく、セッション作成・削除・別スコープ操作の統合テストを行う

今回の変更は、ヘッダー名の修正に見えて、実際にはセッション分離とクライアント生成に関わる重要な更新です。古いヘッダーを残したままにせず、認可スキーム、SDK、プロキシ、テストをまとめて確認することで、プレビュー機能の仕様変更にも耐えやすい構成にできます。

Azure
SDK Azure AI Foundry Azure REST API API仕様変更

この記事を書いた人

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

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

関連記事

コメント

コメントする

目次