Azure REST API documentation update: Nirovins/fix tsp は、Azure REST API全体の大規模な仕様変更ではなく、主に Azure AI Foundry / Azure.AI.Projects 系の data-plane API仕様 に関する更新です。特に確認すべきポイントは、Agent Endpoint関連の認証スキームに isolation_key_source が追加され、ユーザー単位の分離キーを Entra または Header 由来として表現できるようになった点です。
この更新を受けて、Azure.AI.Projects、Azure AI Foundry、AgentEndpointsのプレビュー機能、OpenAPI/TypeSpecからのSDK生成、自社のAPIクライアント生成を使っている管理者・開発者は、仕様差分、生成コード、バリデーション、展開手順を確認しておくべきです。一方、通常のARM管理操作だけをAzure REST APIで呼び出している場合、直接の影響は限定的と考えられます。
Azure REST API documentation update: Nirovins/fix tsp の位置づけ
Azure REST API documentation update: Nirovins/fix tsp は、GitHubの Azure/azure-rest-api-specs リポジトリにある Pull Request #43316 に基づく更新です。azure-rest-api-specs は、Microsoft AzureのREST API仕様の正本にあたるリポジトリとして説明されています。(GitHub)
対象PRは Nirovins/fix tsp という名称で、nirovins/fix_tsp ブランチから feature/foundry-release ブランチへマージされています。GitHub上では2026年5月19日にマージ済みとなっているため、2026年5月20日に公開・更新された情報として扱う場合でも、元PRの日付と実際のドキュメント反映日は分けて確認すると安全です。(GitHub)
また、このPRの説明欄には詳細な変更理由ではなく、PRテンプレート選択用の文言が残っています。そのため、変更内容はPR本文だけで判断せず、Files changed、ラベル、APIView、SDK検証結果をあわせて読む必要があります。(GitHub)
今回の更新で何が変わったのか
今回の変更は、Azure REST APIの全サービスに横断的に影響するものではありません。PR上のラベルは data-plane、TypeSpec、Authored with TypeSpec であり、対象ファイルも specification/ai-foundry/data-plane/Foundry 配下に集中しています。(GitHub)
| 確認項目 | 変更内容 | 実務上の意味 |
|---|---|---|
| 対象領域 | Azure AI Foundry / Azure.AI.Projects 系の data-plane API仕様 | ARM管理API全体の変更ではない |
| 仕様形式 | TypeSpec、OpenAPI JSON、OpenAPI YAMLに変更 | SDK生成、APIドキュメント、クライアント生成に影響する可能性 |
| 主な追加プロパティ | isolation_key_source | 認可スキームでユーザー単位の分離キーの取得元を表現 |
| 追加されたスキーマ | IsolationKeySource、EntraIsolationKeySource、HeaderIsolationKeySource、IsolationKeySourceKind | kind による判別付きモデルとして扱う必要がある |
| 対象プレビュー | AgentEndpoints=V1Preview | Agent Endpointプレビュー機能を使う環境で優先確認 |
| SDK影響 | APIViewでTypeSpecとPythonのAPIレベル変更が検出 | SDK利用者・生成コード利用者は差分確認が必要 |
| C#向け変更 | Routinesサブクライアントのクライアント名指定が追加 | C# SDK生成時のクラス名・メソッド名に影響する可能性 |
Files changedでは、client.csharp.tsp、openapi3/v1 のJSON/YAML、openapi3/virtual-public-preview のJSON/YAML、src/sdk-extensions-openai/client.tsp が対象として表示されています。表示されている差分では、isolation_key_source と関連スキーマの追加、C#向けの Routines / Routine のクライアント名指定が確認できます。(GitHub)
最重要ポイントは isolation_key_source の追加
今回の更新で最も実務影響を確認すべきなのは、認可スキームに追加された isolation_key_source です。差分上では、このプロパティは「このスキームで認可されたリクエストについて、ユーザーごとの分離キーをどこから取得するか」を示すものとして説明され、未指定時はEntraベースの分離が既定になるとされています。(GitHub)
isolation_key_source で表現される考え方
isolation_key_source は、同じAPIや同じエージェントエンドポイントを使っていても、リクエストをユーザー単位でどのように分離するかに関係する設定です。たとえば、認証済みユーザーのEntra ID情報を分離キーの根拠にするのか、ヘッダー由来の値を使う設計にするのか、といった違いをAPI仕様上で表せるようになります。
ただし、PR差分だけでは具体的なヘッダー名、運用ルール、すべてのリクエスト例までは確認できません。実装時は、更新後のMicrosoft Learn、生成済みSDKのリファレンス、サービス側のリリースノートをあわせて確認してください。
追加された選択肢
差分上では、IsolationKeySourceKind に Entra と Header が含まれています。また、IsolationKeySource は kind を判別プロパティとし、EntraIsolationKeySource と HeaderIsolationKeySource へマッピングされます。(GitHub)
概念的には、次のような指定を扱うことになります。
{
"isolation_key_source": {
"kind": "Entra"
}
}または、仕様上の選択肢として次のような Header 由来の指定が追加されています。
{
"isolation_key_source": {
"kind": "Header"
}
}ここで注意したいのは、isolation_key_source を指定する場合は kind が必須である点です。一方、プロパティ自体を省略した場合はEntraベースの既定動作になる説明が追加されています。つまり、既存のリクエストがすぐに必須項目不足になるとは限りませんが、明示指定する実装やSDK生成ではモデル差分が発生します。
影響を受けやすい利用者
この更新の影響は、Azure REST APIをどの範囲で使っているかによって変わります。
| 利用状況 | 影響度 | 確認すべきこと |
|---|---|---|
| Azure.AI.Projects / Azure AI Foundryのdata-plane APIを使っている | 高 | Agent Endpoint関連のリクエスト、認証方式、生成SDKの差分 |
AgentEndpoints=V1Preview に関係する機能を検証している | 高 | isolation_key_source の既定値、明示指定時の挙動 |
| OpenAPI JSON/YAMLから自社クライアントを生成している | 中〜高 | 追加スキーマ、discriminator、enumの扱い |
Python SDK azure-ai-projects を使っている、または生成している | 中〜高 | APIViewで検出されたAPIレベル変更の確認 |
C# SDK生成や Azure.AI.Projects の命名に依存している | 中 | Routines サブクライアントの命名差分 |
| ARMの管理APIだけを呼び出している | 低 | 今回のdata-plane変更とは別扱いでよい |
| Azure REST APIをcurlやaz restで一般的に使うだけ | 低 | 対象サービスを使っていなければ直接対応は少ない |
Azure SDKの仕様一覧でも、Azure.AI.Projects はdata-plane TypeSpecとして掲載されており、stableとpreviewの両方の仕様が確認できます。Azure AI系のAPIをTypeSpec/OpenAPI経由で追っているチームは、今回のような差分がSDKやドキュメントへ波及しやすい点を意識しておくべきです。(Azure)
管理者が確認すべき設定・運用ポイント
管理者が最初に確認すべきなのは、「自社環境でこの仕様変更の対象になる機能を使っているか」です。特に、Azure AI FoundryのAgent Endpointプレビュー、Azure.AI.Projects、独自のAPIゲートウェイ、社内SDK配布を組み合わせている環境では、単なるドキュメント更新として流さないほうがよいでしょう。
Agent Endpointプレビュー機能の利用有無
今回追加されたスキーマには AgentEndpoints=V1Preview のメタ情報が付いています。したがって、本番環境で正式機能だけを使っている場合よりも、プレビュー機能を検証・先行導入している環境のほうが影響を受けやすいと考えるべきです。(GitHub)
確認する項目は次の通りです。
| 確認項目 | 管理者の判断基準 |
|---|---|
| Agent Endpointプレビューを有効にしているか | 有効なら仕様差分の確認対象に含める |
| Entra IDベースの認証を前提にしているか | 既定値がEntraベースである点を確認する |
| API Managementやプロキシでヘッダーを加工しているか | Header 由来の分離を使う場合、ヘッダーの受け渡し設計を慎重に確認する |
| 監査ログでユーザー単位の追跡をしているか | 分離キーの根拠がログ、監査、インシデント対応に影響しないか確認する |
| SDKを社内標準として固定しているか | 生成SDKやモデル名の変更を開発チームへ通知する |
Entra IDと分離キーの関係を整理する
isolation_key_source は、認証そのものを置き換える設定ではありません。ポイントは、認可されたリクエストをユーザー単位で分離する際のキーの取得元です。
管理者は、次の3点を整理しておくと展開時の混乱を避けられます。
- どのEntra IDテナント、アプリ登録、サービスプリンシパルでAPIを呼び出しているか
- ユーザー委任とアプリケーション権限のどちらで呼び出しているか
- API Gateway、プロキシ、バックエンドサービスがユーザー識別情報をどのように伝搬しているか
特に、ヘッダーを使う設計では、ヘッダーの改ざん防止、ログへの記録、不要な個人情報の混入、プロキシでの削除・上書きに注意が必要です。PR差分だけでは具体的なヘッダー仕様が読み取れないため、サービス側ドキュメントが更新されるまでは独自解釈で本番展開しないほうが安全です。
開発者が確認すべきTypeSpec・OpenAPI・SDKのポイント
TypeSpecは、API仕様、クライアントコード、サーバー側コードなどを生成するためのAPI設計言語です。Microsoft Learnでは、TypeSpecを使うことでOpenAPI仕様やクライアントコードを生成でき、既存のAPIツールチェーンとも連携できると説明されています。(Microsoft Learn)
今回の更新ではTypeSpecとOpenAPI生成物の両方に差分があるため、開発者は「REST APIのURLが変わったか」だけでなく、「生成モデルが変わったか」「バリデーションが変わったか」を確認する必要があります。
OpenAPIからクライアントを生成している場合
OpenAPI JSON/YAMLから自社クライアントを生成している場合、次の点を確認してください。
| チェック項目 | 確認方法 | 失敗しやすいポイント |
|---|---|---|
IsolationKeySource がモデルとして生成されるか | 生成後のモデル一覧を確認 | discriminator付きモデルが単純なobjectとして扱われる |
kind のenumが反映されるか | Entra / Header の型定義を確認 | 未知のenum扱いになりビルドが失敗する |
isolation_key_source が任意項目として扱われるか | 既存リクエストのシリアライズ結果を確認 | 生成ツールが必須項目と誤認する |
| 既定値の扱い | プロパティ省略時のリクエストをテスト | クライアント側で不要な空オブジェクトを送る |
| virtual-public-previewの差分 | preview向け生成物を比較 | stable相当のv1だけ確認してpreview側を見落とす |
OpenAPIの差分では、v1 と virtual-public-preview の両方に同様の isolation_key_source 関連変更が見えます。stable系だけ、またはpreview系だけを確認して終わらせると、環境差で不具合を見逃す可能性があります。(GitHub)
SDKを使っている場合
SDK利用者は、REST APIのJSON差分だけでなく、SDKリリース状況と生成コードの差分を確認してください。PRでは、APIViewがAPIレベル変更を検出し、TypeSpecの Azure.AI.Projects とPythonの azure-ai-projects に対するAPIレビューが作成されています。(GitHub)
確認すべきポイントは次の通りです。
| 対象 | 確認ポイント |
|---|---|
| Python SDK | azure-ai-projects のモデル追加、引数追加、型変更、プレビューAPIの扱い |
| C# SDK | AIProjectRoutines、ProjectsRoutine のような生成名が既存コードやサンプルと衝突しないか |
| CI/CD | SDK自動生成ジョブ、型チェック、単体テスト、API互換性チェックが通るか |
| ドキュメント | 社内サンプルコードで古いモデル名や古いリクエスト例を使っていないか |
なお、PR上では SDK Validation Status の失敗がコメントされています。ただし、その時点ではマージをブロックするものではないとも記載されています。これは「SDKが必ず壊れる」という意味ではありませんが、SDKを本番展開する前に自社側でも生成結果とテスト結果を確認すべきサインです。(GitHub)
移行・展開前に行うべき実務手順
今回の更新は、既存API呼び出しを即座に全面移行させるタイプの変更ではありません。とはいえ、Azure AI FoundryやAzure.AI.Projectsを使っているチームでは、次の順序で確認すると安全です。
| 手順 | やること | 完了条件 |
|---|---|---|
| 影響範囲の棚卸し | Azure.AI.Projects、Foundry、Agent Endpoint、生成SDKの利用有無を確認 | 対象サービス・環境・担当チームが一覧化されている |
| 仕様差分の確認 | PR #43316のFiles changedでTypeSpec/OpenAPI差分を見る | isolation_key_source とRoutines命名差分を把握している |
| SDK・クライアント再生成 | 使用中の生成ツールで最新仕様を取り込む | ビルド、型チェック、単体テストが通る |
| 契約テストの追加 | isolation_key_source 省略時、Entra 指定時、必要に応じて Header 指定時を確認 | 既定動作と明示指定時の挙動が記録されている |
| ステージング検証 | 開発環境または検証環境でAPI呼び出しを確認 | 4xx/5xx、認証エラー、シリアライズ差分がない |
| 本番展開 | SDK更新、設定変更、ドキュメント更新を段階的に反映 | ロールバック手順と監視項目が用意されている |
契約テストで見るべき観点
契約テストでは、成功レスポンスだけを見るのでは不十分です。今回のように仕様モデルが追加された更新では、次の観点を含めると実務で役立ちます。
| テスト観点 | 具体例 |
|---|---|
| 省略時の挙動 | isolation_key_source を送らない既存リクエストが従来通り通るか |
| 明示指定時の挙動 | kind: "Entra" を指定した場合に期待通り処理されるか |
| 未知値の扱い | kind に未対応値が入った場合、クライアントとサーバーが適切にエラーにするか |
| シリアライズ | 空の isolation_key_source や kind なしのオブジェクトを送らないか |
| ログ・監査 | ユーザー単位の分離に関する情報が運用上追跡できるか |
特に、OpenAPI生成ツールによってはdiscriminatorやanyOfの扱いが異なります。生成コードの見た目だけで判断せず、実際にリクエストJSONを出力して確認してください。
よくある誤解と注意点
Azure REST API全体の破壊的変更ではない
今回のPRはAzure REST API仕様リポジトリの更新ですが、対象は ai-foundry/data-plane/Foundry 配下です。ARMの管理APIや、すべてのAzure REST API利用者に一律で移行作業が必要になる更新ではありません。PRテンプレートにもData Plane API、Control Plane API、SDK configurationの選択肢が表示されていますが、このPRには data-plane ラベルが付与されています。(GitHub)
Header が追加されたからといって、すぐに任意ヘッダーで使えるとは限らない
HeaderIsolationKeySource というスキーマは追加されていますが、PR差分だけでは具体的なヘッダー名、許可条件、セキュリティ要件までは確認できません。API Gatewayや独自プロキシでヘッダーを付与している環境では、公式ドキュメントやSDKサンプルが更新された後に、具体的な実装ルールを確認してから適用してください。
プレビュー機能の仕様は変わりやすい
差分に AgentEndpoints=V1Preview が含まれていることから、プレビュー機能を利用している環境では仕様変更が入りやすいと考えるべきです。プレビューAPIを本番相当の業務に使う場合は、SDKバージョン固定、仕様差分監視、ロールバック手順をあらかじめ整えておく必要があります。
SDK検証の状態を見落とさない
PRはマージされていますが、コメントでは一部チェック失敗が表示されていました。特にSDK生成に依存するチームは、PRがマージされた事実だけで判断せず、対象SDKの実際のリリース、APIレビュー、生成コードの互換性を確認してください。(GitHub)
実務での判断基準
今回の更新に対して、すぐに設定変更すべきかどうかは次の基準で判断できます。
| 状況 | 判断 |
|---|---|
| Azure.AI.ProjectsやAzure AI Foundryを使っていない | すぐに対応する必要は低い |
| Azure AI Foundryを使っているがAgent Endpointプレビューは使っていない | SDK更新時に差分確認する程度でよい |
| Agent Endpointプレビューを検証している | isolation_key_source の仕様を確認し、契約テストを追加する |
| OpenAPIから自社SDKを生成している | 生成モデルとdiscriminator対応を必ず確認する |
Python azure-ai-projects を使っている | APIViewの変更を前提に、SDK更新時の破壊的差分を確認する |
| C#クライアント名に依存するコードを書いている | Routines関連の生成名差分を確認する |
次に取るべき行動
Azure REST API documentation update: Nirovins/fix tsp を確認する際は、まず「自社がAzure AI Foundry / Azure.AI.Projects / Agent Endpointプレビューを使っているか」を確認してください。該当しない場合は大きな対応は不要ですが、該当する場合は isolation_key_source の追加、Entra / Header の分岐、OpenAPI生成コード、SDKレビューを確認する必要があります。
特に、API仕様から自動生成したクライアントを社内配布しているチームは、今回の変更を単なるドキュメント更新として扱わず、ステージング環境で生成コード、リクエストJSON、契約テストを確認してから展開してください。プレビュー機能を使っている場合は、仕様変更を前提にした監視とロールバック手順もあわせて用意しておくと、後続のAzure REST API更新にも対応しやすくなります。
コメント