Azure REST API documentation update: Merge feature/foundry-release into Main は、単なるドキュメント文言の修正ではありません。確認すべき中心は、Azure AI Foundry の data-plane REST API 仕様、OpenAPI、TypeSpec、SDK生成設定、プレビュー機能の Foundry-Features ヘッダーです。特に、Azure AI Foundry の Agents、Evaluators、Skills、Toolboxes、Data Generation Jobs、Session Files を REST API やSDKから直接使っている場合は、早めに差分を確認してください。
一方で、通常のAzure Resource Manager APIや、Azure AI Foundryを利用していない一般的なAzure REST API利用者への影響は限定的です。今回の更新は、Azure REST API全体の一律変更ではなく、主に specification/ai-foundry/data-plane/Foundry 配下の仕様整理として読むのが実務上の近道です。対象PRは「Merge feature/foundry-release into Main」とされていますが、確認時点ではPRページ上でOpen表示のため、実装へ反映する前にマージ状態と最新の公式ドキュメントも必ず確認しましょう。(GitHub)
Azure REST API documentation update: Merge feature/foundry-release into Main の概要
この更新は、Azure REST API仕様リポジトリのPR #42168に関するものです。PRページでは、feature/foundry-release ブランチから main へ81コミットを取り込む内容として表示されています。変更対象には、TypeSpecファイル、OpenAPI3のJSON/YAML、サンプルJSON、SDKクライアント向け設定、補助ドキュメントが含まれます。(GitHub)
ファイル種別を見ると、.json、.md、.tsp、.yaml が変更対象です。特に重要なのは、Azure AI Foundry のREST API仕様を定義するTypeSpecと、それをもとに出力されるOpenAPI3です。APIを直接呼び出しているチームだけでなく、OpenAPIから独自SDKや型定義を生成しているチームも影響を受ける可能性があります。(GitHub)
今回の変更は、次のように捉えると分かりやすいです。
| 観点 | 内容 | 実務上の確認ポイント |
|---|---|---|
| 対象サービス | 主にAzure AI Foundry data-plane | Foundry関連APIを使っているか確認する |
| 変更ファイル | TypeSpec、OpenAPI3、サンプル、SDK設定、補助ドキュメント | 手元のOpenAPI生成物やSDK生成結果と差分比較する |
| 重要な論点 | プレビュー機能ヘッダー、v1から除外された操作、SDKメソッド名 | 既存コード、CI、APIゲートウェイ設定を確認する |
| 注意点 | PRタイトルに「Merge」とあるが、確認時点ではOpen表示 | 本番反映前にマージ状態と公開ドキュメントを再確認する |
対応が必要な人と、すぐ確認すべき範囲
今回のAzure REST API documentation updateで最初に見るべきなのは、「自分たちがAzure AI FoundryのどのAPI面を使っているか」です。すべてのAzure利用者が同じ対応を求められるわけではありません。
| 利用状況 | 対応優先度 | 確認すべきこと |
|---|---|---|
| Azure AI FoundryのREST APIを直接呼び出している | 高 | パス、HTTPメソッド、APIバージョン、Foundry-Features ヘッダー |
| OpenAPIから独自クライアントを生成している | 高 | OpenAPI3の再生成差分、型名、削除・移動された操作 |
| Python、JavaScript、C#、Java SDKを使っている | 中〜高 | SDKメソッド名、プレビュー機能の有効化方法、非公開化された操作 |
| API Management、プロキシ、WAF経由で呼び出している | 中〜高 | Foundry-Features などのヘッダーが落ちていないか |
| Azure AI Foundryを使っていない | 低 | 通常は即時対応不要。ただし共通のAPI生成基盤がある場合は確認 |
| Azureポータル中心で操作している | 低〜中 | 自動化スクリプトやバックエンド連携だけ確認 |
特に、API Managementやリバースプロキシを通している環境では、アプリケーションコードだけを修正しても動かないことがあります。プレビュー機能に必要なヘッダーが途中で削除されると、認証情報が正しくてもAPI呼び出しが失敗します。
最も重要な変更点は Foundry-Features ヘッダー
今回の更新でまず読むべきなのは、Foundry-Features HTTPリクエストヘッダーに関する整理です。補助ドキュメントでは、プレビュー機能を有効化するために、どのAPIでヘッダーが必要になるかが整理されています。(GitHub)
ポイントは、プレビュー機能を含むAPIを使う場合、単にURLやAPIバージョンを合わせるだけでは不十分なケースがあることです。対象ルートでは、指定された値を Foundry-Features ヘッダーに入れて送信する必要があります。
GAルートでもプレビュー機能を使う場合はヘッダー確認が必要
補助ドキュメントでは、v1 GAルートの一部で、プレビュー機能を有効化するために任意の Foundry-Features ヘッダーを使うケースが示されています。たとえば、Agentsの作成・更新・バージョン作成では、Container Agents、Code Agents、Hosted Agents、Workflow Agents などのプレビュー機能が関係します。(GitHub)
| 操作例 | パス例 | 確認すべきヘッダー |
|---|---|---|
| Agent作成 | POST /agents | ContainerAgents=V1Preview、CodeAgents=V1Preview、HostedAgents=V1Preview など |
| Agent更新 | POST /agents/{agent_name} | 利用するプレビュー機能に応じて指定 |
| Agentバージョン作成 | POST /agents/{agent_name}/versions | Code AgentsやHosted Agents利用時に確認 |
| Evaluation Rules作成・更新 | PUT /evaluationrules/{id} | Evaluations=V1Preview |
ここでの注意点は、「GAルートだからプレビュー機能とは無関係」と決めつけないことです。作成・更新するリソースの中にプレビュー機能が含まれる場合、ヘッダーが必要になる可能性があります。
v1 Previewルートでは必須ヘッダーが増える
v1 Previewルートでは、Foundry-Features ヘッダーが必須として整理されています。対象には、Evaluators、Insights、Schedules、Evaluation Taxonomies、Red Team、Memory Stores、Agent Sessions、Agent Invocations、Agent Session Files、Skills、Toolboxes、Data Generation Jobs などが含まれます。(GitHub)
代表的な確認対象は次のとおりです。
| 機能領域 | パス例 | 必要なヘッダー値の例 |
|---|---|---|
| Evaluators | /evaluators、/evaluators/{name}/versions | Evaluations=V1Preview |
| Insights | /insights | Insights=V1Preview |
| Schedules | /schedules | Schedules=V1Preview |
| Memory Stores | /memory_stores | MemoryStores=V1Preview |
| Agent Sessions | /agents/{agent_name}/endpoint/sessions | AgentEndpoints=V1Preview |
| Agent Session Files | /agents/{agent_name}/endpoint/sessions/{session_id}/files | HostedAgents=V1Preview |
| Skills | /skills、/skills:import | Skills=V1Preview |
| Toolboxes | /toolboxes、/toolboxes/{name}/versions | Toolboxes=V1Preview |
| Code Agentsのコード取得 | /agents/{agent_name}/code:download | CodeAgents=V1Preview |
| Data Generation Jobs | /data_generation_jobs | DataGenerationJobs=V1Preview |
REST APIを直接呼ぶ場合は、以下のようにヘッダーを明示します。
curl -X GET "https://{your-foundry-endpoint}/data_generation_jobs" \
-H "Authorization: Bearer {access-token}" \
-H "Foundry-Features: DataGenerationJobs=V1Preview"Agent関連のプレビュー機能を使う場合は、機能に応じて値を変えます。
curl -X POST "https://{your-foundry-endpoint}/agents" \
-H "Authorization: Bearer {access-token}" \
-H "Content-Type: application/json" \
-H "Foundry-Features: CodeAgents=V1Preview" \
-d '{ ... }'本番環境では、ヘッダーを闇雲に全リクエストへ付けるのではなく、対象APIと機能ごとに付与するのが安全です。不要なプレビュー機能を有効化すると、将来の仕様変更の影響を受けやすくなります。
v1から除外された操作は移行チェックが必要
removed-v1-operations-report.md では、@removed(Versions.v1) が付いたインターフェースと操作が整理されています。Full Interfaces Removedとして、Evaluations、ManagedAgentIdentityBlueprints、AgentContainers が挙げられています。また、個別操作として Evaluators の startPendingUpload と getCredentials がv1から除外された操作として示されています。(GitHub)
この情報は、次のようなケースで重要です。
| 影響を受けやすいケース | 起きやすい問題 | 対応 |
|---|---|---|
| v1 APIとして該当操作を呼んでいる | 404、405、生成SDKからメソッドが消える | preview側または代替APIを確認 |
| OpenAPIからコード生成している | 以前あったメソッドや型が生成されない | 生成前後の差分をCIで比較 |
| テストコードで旧操作を固定している | 回帰テストが失敗する | テスト対象のAPIバージョンを明示 |
| API仕様を社内ドキュメントに転載している | 古い操作を案内してしまう | v1対象外の操作を注記する |
特に注意したいのは、「削除された」というより「v1から除外された」と読むべき点です。プレビュー仕様や別のルートで存在する可能性があるため、実装を消す前に、対象APIバージョンと公開面を確認してください。
SDK利用者はメソッド名と公開範囲の変更に注意
このPRでは、SDK生成に関わる client.tsp、client.csharp.tsp、client.java.tsp も更新されています。つまり、REST APIのパスだけでなく、SDKから見えるメソッド名や公開・非公開の扱いにも影響する可能性があります。(GitHub)
PythonとJavaScriptではData Generation Jobsの名前に注意
DataGenerationJobs では、Python向けに get_generation_job、list_generation_jobs、create_generation_job、cancel_generation_job、delete_generation_job が設定されています。JavaScript向けには getGenerationJob、listGenerationJobs、createGenerationJob、cancelGenerationJob、deleteGenerationJob が設定されています。(GitHub)
古いサンプルや社内ラッパーで、より汎用的な get、list、create のような名前を前提にしている場合は、SDK更新時にビルドエラーになる可能性があります。
| 言語 | 変更確認の観点 |
|---|---|
| Python | snake_caseのメソッド名、allow_preview オプション、プレビュー機能の有効化 |
| JavaScript | camelCaseのメソッド名、betaサブクライアントへの移動有無 |
| C# | Data Generation JobsやEvaluator Generation Jobsの公開範囲、内部化されたメソッド |
| Java | メソッド名、列挙値、日時型の扱い |
listSessionFiles から getSessionFiles へのリネームも確認
Agent Session Filesでは、listSessionFiles を getSessionFiles にリネームする設定が示されています。コメント上では、GET操作であり、レスポンスとしてファイル一覧を返すため、より正確な名前にする意図が説明されています。(GitHub)
この種の変更は、REST APIのURLが同じでも、SDK利用者には破壊的変更のように見えることがあります。特に、次のようなコードは確認が必要です。
# 旧サンプルや社内ラッパーでこのような名前を使っている場合は要確認
client.agent_session_files.list_session_files(...)SDK更新後は、生成された実際のメソッド名に合わせて呼び出しを見直してください。
Pythonでは allow_preview によるプレビュー有効化も確認
client.tsp では、Python向けクライアント初期化オプションとして allow_preview?: boolean が定義され、プレビュー機能を有効化するにはTrueを指定する旨の説明が含まれています。さらに、foundry_features 入力引数を公開メソッドから除外し、内部的に扱う方針も示されています。(GitHub)
実務では、REST API直呼びとSDK利用で確認ポイントが変わります。
| 利用方法 | 確認すべきこと |
|---|---|
| REST API直呼び | Foundry-Features ヘッダーを自分で付ける |
| Python SDK | クライアント初期化時の allow_preview の有無を確認 |
| JavaScript SDK | betaサブクライアントやメソッド名の変更を確認 |
| 自作SDK | OpenAPI差分からヘッダー、パス、モデルを再生成 |
SDKの実際の公開状態は、最終的なSDKリリースに依存します。PR上の生成設定だけで本番コードを書き換えるのではなく、利用中のSDKバージョンのリリースノートと実際の型定義を併せて確認してください。
新しく確認したい機能領域
PRのコミット履歴と変更ファイルから見ると、今回の更新ではAzure AI Foundryの複数領域がまとめて整理されています。特に目立つのは、Agent関連、Toolboxes、Skills、Data Generation Jobs、Evaluator Generation Jobs、コードベースAgent、セッションファイル、会話評価まわりです。(GitHub)
| 領域 | 変更の読み方 | 確認ポイント |
|---|---|---|
| Agents | Agent作成、更新、バージョン、コードベースAgentの仕様整理 | 旧メソッド名、beta移動、コードダウンロードAPI |
| Agent Sessions | セッション作成・取得・削除・一覧 | AgentEndpoints=V1Preview ヘッダー |
| Agent Session Files | セッション内ファイルのアップロード、ダウンロード、一覧、削除 | HostedAgents=V1Preview ヘッダーとSDK名 |
| Skills | 作成、パッケージ取り込み、取得、更新、削除 | Skills=V1Preview ヘッダー |
| Toolboxes | バージョン作成、取得、更新、削除 | Toolboxes=V1Preview ヘッダー |
| Data Generation Jobs | ジョブ作成、取得、一覧、キャンセル、削除 | SDKメソッド名と DataGenerationJobs=V1Preview |
| Evaluators | バージョン操作、生成ジョブ、アップロード関連の扱い | v1除外操作とプレビュー指定 |
| Evaluations | 会話・マルチターン評価関連 | サンプルJSONとOpenAPI差分 |
ここで重要なのは、機能追加だけでなく「公開面の整理」も含まれていることです。たとえば、ある操作が追加される一方で、v1から除外されたり、SDKの public surface からinternal扱いになったりします。APIの存在有無だけでなく、「どのAPIバージョンで」「どのSDKで」「プレビュー機能として」使えるのかを分けて確認しましょう。
移行・設定確認の進め方
今回のAzure REST API documentation updateを受けて、すぐに全コードを書き換える必要はありません。先に影響範囲を棚卸しし、変更が実際に使っているAPIへ及ぶかを確認するのが安全です。
まず利用中のエンドポイントを洗い出す
最初に、コードベース、IaC、APIテスト、CI設定、社内SDKから、Azure AI Foundry関連のパスを検索します。
grep -R "data_generation_jobs\|toolboxes\|skills\|evaluators\|memory_stores\|endpoint/sessions" ./src ./tests ./infraAPI Managementやプロキシを使っている場合は、ルーティング定義も検索対象に入れてください。
grep -R "Foundry-Features\|agents/\|evaluators\|toolboxes" ./apim ./gateway ./config検索結果を、次の3つに分けると判断しやすくなります。
| 分類 | 例 | 対応 |
|---|---|---|
| 既存の安定API | 通常のAgent取得、一覧など | 変更対象かだけ確認 |
| プレビュー機能 | Skills、Toolboxes、Data Generation Jobsなど | ヘッダーとSDK公開範囲を確認 |
| 廃止・除外候補 | v1から除外された操作 | 代替APIまたはpreview側を確認 |
OpenAPIを使っている場合は差分をCIで検出する
OpenAPIからクライアントを生成している場合は、手作業で仕様を読むだけでは不十分です。生成結果の差分をCIで見えるようにしてください。
実務では、以下の流れが有効です。
| 手順 | 作業 | 判断基準 |
|---|---|---|
| 1 | 現在利用中のOpenAPIを保存 | 既存生成物の基準を固定する |
| 2 | 更新後のOpenAPIで再生成 | 型・メソッド・パスの差分を見る |
| 3 | 差分を分類 | 破壊的変更、命名変更、追加機能に分ける |
| 4 | テスト実行 | 主要API呼び出し、認証、ヘッダー、リトライを確認 |
| 5 | 本番反映 | SDKや生成物のバージョンを固定して反映 |
差分確認では、追加されたAPIよりも「消えたメソッド」「型名が変わったモデル」「必須化されたヘッダー」を優先して見ます。追加機能は使わなければ影響が小さい一方、削除や必須条件の変更は既存処理を止める可能性があります。
APIゲートウェイではヘッダー透過を確認する
Foundry-Features は通常の認証ヘッダーではないため、ゲートウェイやWAFの設定によっては落とされることがあります。アプリケーション側で正しく指定していても、Azure AI Foundryに到達する前に削除されると、プレビュー機能のAPIは期待どおりに動きません。
確認すべき設定は次のとおりです。
| 設定箇所 | 確認内容 |
|---|---|
| API Management | Foundry-Features を削除・上書きしていないか |
| リバースプロキシ | 許可ヘッダー一覧に含まれているか |
| WAF | 未知のヘッダーとしてブロックしていないか |
| ログ設定 | ヘッダー値を不用意にログへ出していないか |
| 再試行処理 | POST系ジョブ作成で重複作成が起きないか |
プレビュー機能のヘッダーは、トラブル時の原因切り分けにも使います。API呼び出しログでは、ヘッダーの有無を確認できるようにしつつ、認証情報や機密データを残さない設計にしてください。
失敗しやすいポイント
今回の更新で起きやすい失敗は、「ドキュメント更新」という名前だけを見て軽視することです。実際にはOpenAPI、TypeSpec、SDK生成設定まで含まれるため、開発チームの自動生成やテストに影響します。
| 失敗例 | なぜ問題か | 回避策 |
|---|---|---|
| PRタイトルだけ見て本番反映する | 確認時点ではOpen表示で、後続コミットも入っている | マージ状態、最新コミット、公式ドキュメントを確認 |
Foundry-Features を付け忘れる | プレビューAPIが失敗する | 対象ルートごとにヘッダー要件を表で管理 |
| すべてのリクエストにプレビュー指定を付ける | 不要なプレビュー挙動に巻き込まれる | 必要なAPIだけに限定 |
| SDKメソッド名の変更を見落とす | ビルドエラーやランタイムエラーになる | SDK更新前後で型チェックを実行 |
| APIゲートウェイでヘッダーが落ちる | アプリ側修正だけでは解決しない | 実際にバックエンドへ届くリクエストを確認 |
| v1除外操作を使い続ける | 生成SDKから消える、APIが呼べない | 代替ルート、preview API、SDK公開面を確認 |
| サンプルJSONだけを見て判断する | サンプルは仕様全体を代表しない | OpenAPIとTypeSpecの両方を確認 |
特に、プレビュー機能を本番相当の環境で使っているチームは、リリース前の確認項目を明文化しておくべきです。プレビューAPIは、パスやモデルだけでなく、ヘッダー、SDK公開範囲、サンプルの形が短期間で変わることがあります。
チーム別の確認チェックリスト
REST APIを直接呼ぶバックエンド開発者
以下を確認してください。
- 呼び出しているパスが今回の対象領域に含まれるか
Foundry-Featuresが必要なルートか- API Managementやプロキシでヘッダーが通るか
- v1から除外された操作を使っていないか
- サンプルJSONと実際のリクエストボディに差分がないか
特に、/data_generation_jobs、/toolboxes、/skills、/memory_stores、/agents/{agent_name}/endpoint/sessions を使っている場合は優先度を上げて確認しましょう。
SDK利用者
SDKを使っている場合は、REST APIのURLよりも、メソッド名と公開範囲の変更を優先して確認します。
- SDKのバージョンを固定しているか
- 更新後に型チェックやビルドが通るか
- 旧メソッド名を使っていないか
- Pythonでは
allow_previewの扱いを確認したか - betaサブクライアントへ移動した操作がないか
- 社内ラッパーが古い名前を隠蔽していないか
SDKは、同じREST API仕様から生成されても、言語ごとにメソッド名や公開範囲が異なる場合があります。Python、JavaScript、C#、Javaを混在しているチームでは、言語ごとの移行メモを分けて作ると混乱を防げます。
SRE・運用担当者
運用側では、アプリケーションコードよりも、通信経路と監視を確認します。
Foundry-Featuresヘッダーがログで確認できるか- ヘッダー値を機密情報として扱う必要がないか
- 4xx増加時にヘッダー不足を切り分けられるか
- POST系ジョブ作成で再試行時の重複が起きないか
- 本番反映前にステージングで同じゲートウェイ経路を使って検証したか
API仕様変更の障害は、コード差分よりも「通信経路でヘッダーが消える」「古いSDKが一部環境に残る」といった運用面で起きることが多いです。
実装前に見るべき差分の優先順位
今回のように変更範囲が広いPRでは、すべての差分を同じ重みで読むと時間がかかります。優先順位を決めて確認しましょう。
| 優先度 | 確認対象 | 理由 |
|---|---|---|
| 1 | Foundry-Features ヘッダー必須ルート | 呼び出し失敗に直結する |
| 2 | v1から除外された操作 | 既存コードや生成SDKに影響しやすい |
| 3 | SDKメソッド名・公開範囲 | ビルドエラーや互換性問題につながる |
| 4 | OpenAPI3 v1とvirtual-public-preview | 独自SDK生成やAPIテストに影響する |
| 5 | サンプルJSON | リクエスト/レスポンス例の更新確認に使える |
| 6 | cspellや補助設定 | 直接影響は小さいが、CIには関係する可能性 |
まずは、自社で使っている機能領域に絞って、API呼び出し単位で棚卸しします。そのうえで、OpenAPI差分、SDK生成差分、ゲートウェイ設定の順に確認すると、無駄なく影響範囲を特定できます。
まとめ：次に取るべき行動
Azure REST API documentation update: Merge feature/foundry-release into Main は、Azure AI Foundryのdata-plane APIを使っている開発者にとって、確認すべき変更が多い更新です。特に重要なのは、Foundry-Features ヘッダー、v1から除外された操作、SDKメソッド名、OpenAPI3再生成の差分です。
まずは、自社コードでAzure AI Foundry関連のパスを検索し、/agents、/evaluators、/skills、/toolboxes、/data_generation_jobs、/memory_stores、/endpoint/sessions を使っているか確認してください。該当する場合は、ヘッダー要件とSDKの公開メソッド名を照合し、ステージング環境でAPIゲートウェイを含めた実通信テストを行うのが安全です。
PRがOpen表示の段階では、仕様がさらに変わる可能性があります。本番コードへ反映する前に、PRのマージ状態、最新コミット、公開済みのAzure REST APIドキュメント、利用中SDKのリリースノートを確認し、影響があるAPIだけを計画的に更新しましょう。
コメント