Microsoft Foundry / Azure OpenAI の2026年4月更新でまず押さえるべき結論は、v1 REST API referenceを「単なるエンドポイント一覧」ではなく、生成AIアプリを本番運用するための設計基準として見直すべきだという点です。特に developers、DevOps engineers、platform teams は、Chat Completions だけでなく、Responses、Evals、Realtime、Vector Stores、Batch、認証方式、ログ設計まで確認する必要があります。
Microsoft Learnの「What’s new for April 2026」では、Azure OpenAI in Microsoft Foundry Models v1 REST API reference が更新記事として掲載されています。一方で、リファレンス本体のページ下部には別の最終更新日が表示されるため、社内の変更管理では「2026年4月の更新対象」として扱い、実装前にMicrosoft Learn本文とOpenAPI specの両方を確認するのが安全です。(Microsoft Learn)
Microsoft Foundry / Azure OpenAIの2026年4月更新で見るべきポイント
今回の更新で重要なのは、Azure OpenAI in Microsoft Foundry Models v1 REST API referenceが、より広いAPI面を1つのv1リファレンスとして整理していることです。リファレンスでは API Version: v1 が示され、サーバー変数の endpoint には Azure OpenAI リソースのホスト名を使う形式が記載されています。認証も api-key ヘッダー、authorization ヘッダー、OAuthスコープ https://ai.azure.com/.default が整理されています。(Microsoft Learn)
つまり、アプリ側で見直すべき範囲は「APIのURLを変える」だけではありません。認証、モデル指定、パラメータ、レスポンス形式、評価、RAG、リアルタイム音声、監視ログまで含めて、AIアプリのプラットフォーム設計を棚卸しするタイミングです。
| 確認ポイント | 公式リファレンスで確認できる内容 | 実務でやるべきこと |
|---|---|---|
| v1エンドポイント | /openai/v1/... 形式のAPI群と api-version=v1 | base URL、API version、モデルIDを環境変数や設定ファイルで管理する |
| 認証 | api-key、authorization、OAuthスコープ | APIキー配布に頼りすぎていないか確認し、トークン認証の採用可否を検討する |
| Chat Completions | tools、tool_choice、response_format、reasoning_effort など | 旧パラメータや古いSDKラッパーを棚卸しする |
| Responses API | POST /openai/v1/responses | 新規開発では、マルチモーダル入力・ツール利用・状態管理との相性を確認する |
| Evals | 評価の作成、実行、結果取得 | CI/CDやリリース判定に評価を組み込む |
| Vector Stores | ファイル、チャンク、検索、期限管理 | RAG用データのライフサイクルと権限設計を決める |
| Realtime | WebRTCやリアルタイムセッション関連 | 音声AI、コールセンター、低遅延UXの検証対象にする |
| Batch | 非同期バッチ処理 | 大量処理、夜間処理、コスト最適化の候補にする |
| Fine-tuning | ジョブ、チェックポイント、プレビュー機能 | preview機能は本番依存を避け、feature flagで管理する |
v1 REST API referenceは「新機能一覧」ではなく実装基準として読む
Azure OpenAI in Microsoft Foundry Models v1 REST API referenceを読むときは、使えるAPIを眺めるよりも、既存システムとの差分を洗い出すことが重要です。
特に既存のAzure OpenAIアプリでは、次のような古い実装が残りやすくなります。
| 残りやすい実装 | 起きやすい問題 | 見直し方 |
|---|---|---|
| API versionをコードに直書き | 環境ごとの切り替えや検証が難しい | API_VERSION として設定化する |
max_tokens を使い続ける | reasoning系モデルで互換性問題が起きる可能性がある | max_completion_tokens への置き換えを検討する |
functions / function_call 前提 | 新しいtool呼び出し設計に追従しにくい | tools / tool_choice に移行する |
| JSON出力をプロンプトだけで制御 | 不正なJSONやパースエラーが起きやすい | response_format の json_schema を検討する |
| ユーザーIDを平文で送る | 個人情報・監査上の懸念が出る | ハッシュ化した安定IDを使う |
| リクエストIDを記録しない | 障害調査が遅くなる | apim-request-id をログに残す |
Chat Completionsでは、function_call と functions が tool_choice と tools に置き換わる方向で記載され、max_tokens も max_completion_tokens が推奨される形で整理されています。また、reasoning_effort、response_format、safety_identifier、user_security_context、verbosity など、本番運用で重要になるパラメータも確認できます。(Microsoft Learn)
開発者が最初に確認すべき実装ポイント
エンドポイントとAPI versionを設定化する
v1リファレンスでは、Azure OpenAIリソースのエンドポイントを使い、/openai/v1/... のAPIパスを呼び出します。api-version は明示しない場合に v1 とされますが、実務では環境差分や検証のために設定値として管理しておく方が安全です。(Microsoft Learn)
例として、Chat CompletionsをRESTで呼び出す場合は次のような形になります。
curl "https://<resource-name>.openai.azure.com/openai/v1/chat/completions?api-version=v1" \
-H "api-key: $AZURE_OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<model-or-deployment-id>",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "この文章を3つの要点にまとめてください。"
}
],
"max_completion_tokens": 500
}'ここで重要なのは、<resource-name>、api-version、model をコードに直書きしないことです。グローバル展開するサービスでは、リージョン、環境、モデルの切り替えが頻繁に発生します。設定化しておかないと、検証環境では動くのに本番環境では別のモデルやAPI versionを参照していた、という事故が起きやすくなります。
古いパラメータをgrepで棚卸しする
既存コードがある場合、まずはリファクタリング対象を機械的に洗い出します。
grep -R "max_tokens\|functions\|function_call\|\"user\"\|stop" ./src ./app ./services特に確認したいのは次の項目です。
| 検索対象 | 確認する理由 |
|---|---|
max_tokens | max_completion_tokens への移行対象になりやすい |
functions | tools への移行を検討する |
function_call | tool_choice への移行を検討する |
user | prompt_cache_key や safety_identifier との整理が必要になる |
stop | 一部のreasoningモデルでは使えない可能性がある |
seed も注意が必要です。リファレンスでは決定的な出力をベストエフォートで狙う機能として説明されていますが、完全な再現性が保証されるわけではありません。テストコードで「同じseedなら必ず同じ文字列になる」と決め打ちすると、モデル側の変更でテストが不安定になります。(Microsoft Learn)
JSON出力はプロンプトではなくスキーマで縛る
業務アプリでは、生成AIの出力をそのまま画面に出すより、JSONとして後続処理に渡すケースが増えています。このとき「必ずJSONで返してください」とプロンプトに書くだけでは不十分です。
Chat Completionsの response_format では、json_schema を使ってStructured Outputsを指定できます。古いJSON modeよりも、スキーマに沿った出力を要求できる点が実務上のメリットです。(Microsoft Learn)
たとえば、問い合わせ分類を行うなら、次のような設計にします。
{
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "support_ticket_classification",
"schema": {
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": ["billing", "technical", "account", "other"]
},
"priority": {
"type": "string",
"enum": ["low", "medium", "high"]
},
"summary": {
"type": "string"
}
},
"required": ["category", "priority", "summary"],
"additionalProperties": false
}
}
}
}実務では、スキーマをAPI仕様書やバックエンドの型定義と合わせて管理します。フロントエンド、バックエンド、AI処理の出力形式がずれていると、AIの精度以前にアプリケーションエラーが増えます。
Responses APIは新規開発で優先的に検討したい
今回のv1 REST API referenceでは、POST /openai/v1/responses がモデル応答を作成するAPIとして記載されています。Request Bodyには、テキスト、画像、ファイル入力、会話状態、ツール呼び出し、Structured Outputsに関係する項目が並んでいます。(Microsoft Learn)
既存の単純なチャットボットなら、Chat Completionsをすぐに捨てる必要はありません。ただし、新規開発で次のような要件がある場合は、Responses APIを設計候補に入れる価値があります。
| 要件 | Chat Completionsで十分なケース | Responses APIを検討したいケース |
|---|---|---|
| 単発のQ&A | FAQ回答、要約、翻訳 | なし |
| ツール利用 | 関数呼び出しが少ない | 複数ツール、状態、前回応答との連携が必要 |
| マルチモーダル | テキスト中心 | 画像、ファイル、会話状態をまとめて扱う |
| 出力制御 | 簡単なJSON | スキーマ化された出力を継続的に使う |
| 評価 | 手動テスト中心 | Evalsと組み合わせて品質を継続監視する |
判断基準は、「今の機能」ではなく「半年後に必要になる運用」です。チャットUIから始めたアプリでも、後からファイル検索、評価、監査ログ、ツール連携が必要になることは珍しくありません。最初からAPI選定の理由を記録しておくと、後の移行判断がしやすくなります。
EvalsをCI/CDに組み込むとAI機能の品質管理がしやすい
Evalsは、モデル出力を継続的に評価するための重要なAPI群です。v1 REST API referenceでは、GET /openai/v1/evals、POST /openai/v1/evals などが記載され、評価はtesting criteriaとdatasourceを使って作成できると説明されています。(Microsoft Learn)
AIアプリでは、通常の単体テストだけでは品質を保証しにくい問題があります。モデル、プロンプト、RAGデータ、ツール定義が少し変わるだけで、出力の品質や安全性が変わるためです。
実務では、次のような評価ゲートを作ると効果的です。
| タイミング | Evalsで確認すること | 合格基準の例 |
|---|---|---|
| プロンプト変更時 | 回答の正確性、形式、禁止表現 | 主要テストケースの合格率が一定以上 |
| モデル変更時 | 既存タスクの品質低下 | 旧モデルとの差分が許容範囲内 |
| RAGデータ更新時 | 検索結果に基づく回答 | 根拠のない回答が増えていない |
| 本番リリース前 | 業務シナリオ全体 | 重大カテゴリの失敗がゼロ |
| 障害対応後 | 再発防止ケース | 既知の失敗ケースを再現しない |
DevOps engineersにとっては、Evalsを「AI版の回帰テスト」として扱うのが分かりやすいです。モデルの出力は完全に固定できないため、文字列完全一致ではなく、分類結果、スキーマ適合、根拠の有無、危険な出力の有無など、評価軸を分けて設計します。
Vector StoresはRAG基盤の運用設計まで含めて見る
Vector Storesは、RAGやfile searchの基盤として重要です。v1 REST API referenceでは、Vector Storeの作成、一覧、取得、更新、削除、ファイル追加、検索などが整理され、作成時には file_ids、chunking_strategy、expires_after などを指定できます。(Microsoft Learn)
RAGの失敗は、モデルの性能よりもデータ運用の設計不足で起きることが多いです。たとえば、古いマニュアルが残っている、部署ごとのアクセス権が反映されていない、同じ文書が重複している、チャンクサイズが不適切で回答に必要な文脈が欠ける、といった問題です。
Vector Storesを使う場合は、次の観点を先に決めます。
| 設計項目 | 決めるべきこと |
|---|---|
| ファイルの責任者 | 誰が追加・削除・更新するか |
| 更新頻度 | 毎日、毎週、リリース時など |
| 有効期限 | expires_after を使うか、手動削除するか |
| チャンク戦略 | 自動に任せるか、文書構造に合わせて調整するか |
| 検索品質 | score_threshold や検索結果数をどう調整するか |
| 権限 | ユーザーが参照できる文書だけを検索対象にする方法 |
| 監査 | どの文書が回答に使われたか追跡できるか |
Vector Storeの検索APIでは、検索クエリ、最大結果数、フィルター、ランキングオプション、クエリ書き換えなどが指定できます。検索精度を上げるには、モデルのプロンプト調整だけでなく、検索条件と文書属性の設計が重要です。(Microsoft Learn)
Realtime APIは音声AIの本番化を見据えた確認が必要
Realtime APIでは、WebRTCを使ったリアルタイム呼び出しやセッション設定が記載されています。POST /openai/v1/realtime/calls は、WebRTCのSDP offerを受け取り、peer connectionを完了するためのSDP answerを返す用途として説明されています。(Microsoft Learn)
Realtimeを使う場合、通常のチャットAPIとは確認ポイントが変わります。
| 観点 | 通常のテキストAPI | Realtime API |
|---|---|---|
| 遅延 | 数秒でも許容されることが多い | 数百ミリ秒単位の体感が重要 |
| 障害対応 | 再送やリトライが比較的容易 | 通話中断、音声途切れ、切断処理が重要 |
| ログ | テキストの入出力中心 | 音声、イベント、セッション状態も見る |
| セキュリティ | APIキーやトークン管理 | クライアントシークレット、セッション期限、ネットワーク設計が重要 |
| UX | 入力後に応答 | 割り込み、沈黙検知、話速、音声品質が重要 |
音声AIをコールセンターや接客に使う場合、モデルの精度だけでなく、切断時のフォールバック、有人対応への引き継ぎ、録音・監査、個人情報の扱いまで設計する必要があります。Realtime APIはプロトタイプでは魅力的ですが、本番投入ではDevOpsとセキュリティチームを早めに巻き込むべき領域です。
BatchとEmbeddingsはコスト最適化と大量処理で効く
Batch APIは、アップロード済みファイルを使ってバッチを作成・実行するAPIです。リファレンスでは POST /openai/v1/batches が記載され、処理ウィンドウは 24h、対象エンドポイントにはChat CompletionsやEmbeddingsが示されています。(Microsoft Learn)
Embeddings APIは、入力テキストをベクトルに変換するAPIです。dimensions、encoding_format、input、model などの項目が記載され、RAGや類似検索の前処理で使われます。(Microsoft Learn)
即時応答が不要な処理は、リアルタイムAPIで処理するよりBatchを検討した方が運用しやすい場合があります。
| 活用シーン | 向いているAPI | 理由 |
|---|---|---|
| FAQ候補の大量要約 | Batch | 即時性より処理量が重要 |
| 文書のEmbedding作成 | Embeddings + Batch | RAG用インデックス作成に向く |
| 夜間の分類処理 | Batch | 業務時間外にまとめて処理できる |
| ユーザーとの対話 | Chat Completions / Responses | 即時応答が必要 |
| 音声対話 | Realtime | 低遅延が必要 |
コスト管理では、リアルタイム処理とバッチ処理を分けることが重要です。すべてを同期APIで処理すると、ユーザー体験は単純になりますが、ピーク時の負荷や失敗時の再実行が難しくなります。
Fine-tuning関連はpreview表記に注意する
Fine-tuning関連では、ジョブの作成、一覧、取得、キャンセル、チェックポイント、pause/resumeなどが整理されています。特にチェックポイントコピーについては、コピー先アカウントやリージョンへのコピーAPIが記載されていますが、Microsoft Learn上ではpreviewであり変更される可能性があると明記されています。また、aoai-copy-ft-checkpoints ヘッダーに preview を指定する必要があります。(Microsoft Learn)
preview機能を使う場合は、次のルールを決めておくと安全です。
| ルール | 理由 |
|---|---|
| 本番の必須経路にしない | 仕様変更の影響を受けやすい |
| feature flagで有効化する | すぐに無効化できる |
| 代替手順を用意する | preview停止や変更に備える |
| APIレスポンスを固定前提にしない | スキーマ変更の可能性がある |
| ドキュメント更新を監視する | previewは変更頻度が高い |
Platform teamsは、preview機能を「使ってよい機能」ではなく「検証対象」として管理するのが現実的です。開発チームが便利だからと本番ワークフローに組み込むと、後から運用負荷が増えます。
Models APIはモデル棚卸しとガバナンスに使える
GET /openai/v1/models は、利用可能なモデルを一覧し、所有者や可用性などの基本情報を提供するAPIとして記載されています。モデル個別の取得や削除APIもあります。(Microsoft Learn)
複数チームでAzure OpenAIを使っている組織では、モデル管理が属人化しがちです。どのアプリがどのモデルを使っているか、いつ切り替えたか、どのリージョンで利用しているかが分からないと、障害対応やコスト管理が難しくなります。
モデル棚卸しでは、最低限次の情報を台帳化します。
| 管理項目 | 例 |
|---|---|
| アプリ名 | 社内FAQボット、問い合わせ分類API |
| 利用モデル | gpt-4o、o3 など |
| 用途 | 要約、分類、RAG、コード生成 |
| API種別 | Chat Completions、Responses、Embeddings |
| 利用リージョン | East US、Japan Eastなど |
| 所有チーム | Platform、Support、Product |
| 評価セット | Evals ID、テストケース名 |
| 切り替え履歴 | モデル変更日、変更理由 |
モデル選定は、開発者だけで決めるより、platform teamsが標準候補を定める方が運用しやすくなります。個別最適でモデルを選ぶと、コスト、レイテンシ、セキュリティレビュー、評価基準がバラバラになります。
読み間違えやすい注意点
v1 REST API referenceは範囲が広いため、コンポーネント定義と実際に利用可能なAPIを混同しないことが重要です。たとえば、リファレンス内にはWeb search関連のコンポーネントが見えますが、Microsoft Learn上では web_search はAzure OpenAIではまだ利用できない旨が記載されています。(Microsoft Learn)
| 注意点 | 誤解 | 正しい見方 |
|---|---|---|
| コンポーネント名だけで判断する | スキーマにあるなら使えると思う | 実際のエンドポイント、注記、対応モデルを確認する |
| OpenAI向けコードをそのまま移植する | パスとパラメータが似ていれば動くと思う | Azureのendpoint、認証、対応機能を確認する |
| previewを正式機能として扱う | ドキュメントに載っているなら本番OKと思う | preview表記と必要ヘッダーを確認する |
seed を完全再現と考える | テストが毎回同じになると思う | ベストエフォートとして扱い、厳密一致テストを避ける |
user に個人情報を入れる | 追跡しやすいからメールアドレスを使う | ハッシュ化した安定IDを使う |
apim-request-id を捨てる | アプリログだけで十分と思う | 障害調査用に保存する |
特にグローバルサービスでは、リージョンや利用可能モデルの差、データ保護要件、監査要件が国や顧客ごとに変わります。APIリファレンスの項目だけを見て実装するのではなく、自社の利用可能リージョン、契約、セキュリティポリシーと合わせて判断してください。
DevOps engineersとplatform teams向けの実装手順
v1 REST API referenceの更新を受けて、既存アプリを一気に移行する必要はありません。まずは影響調査、次に小さな検証、最後に本番反映の順で進めるのが安全です。
| 手順 | 作業内容 | 成果物 |
|---|---|---|
| 影響範囲の棚卸し | 利用中のAPI、モデル、SDK、API versionを一覧化 | AI API利用台帳 |
| パラメータ確認 | max_tokens、functions、function_call、user などを検索 | 修正対象リスト |
| 認証確認 | API key運用、token運用、権限管理を確認 | 認証方式の方針 |
| ログ確認 | apim-request-id、モデル名、API種別、エラーコードを保存 | ログ設計書 |
| Evals作成 | 主要ユースケースの評価セットを作る | 回帰評価セット |
| ステージング検証 | v1 APIで実行し、出力・レイテンシ・コストを比較 | 検証レポート |
| 段階的リリース | feature flagやカナリアリリースで反映 | ロールバック可能なリリース |
| 継続監視 | ドキュメント更新、モデル変更、失敗ケースを監視 | 運用チェックリスト |
この手順のポイントは、API呼び出しの成功だけで合格にしないことです。AIアプリでは、レスポンスが返っても、回答品質、形式、根拠、安全性、コスト、レイテンシが期待を満たしていない場合があります。
実装前チェックリスト
- [ ] Azure OpenAIのendpointを設定値として管理している
- [ ]
api-version=v1をどこで指定するか決めている - [ ] 利用モデルを環境別に切り替えられる
- [ ]
max_tokens、functions、function_callの残存を確認した - [ ] JSON出力が必要な処理で
response_formatを検討した - [ ] ユーザー識別子を平文で送っていない
- [ ]
safety_identifierの設計を決めている - [ ]
apim-request-idをログに保存している - [ ] Evalsで主要ユースケースを評価できる
- [ ] Vector Storesの文書更新・削除ルールを決めている
- [ ] Realtimeを使う場合、切断・遅延・監査の設計をしている
- [ ] preview機能を本番必須経路にしていない
- [ ] OpenAPI specの更新を定期的に確認する担当を決めている
よくある質問
v1 REST API referenceに載っているAPIへすぐ移行すべきですか
すぐに全面移行する必要はありません。既存アプリが安定している場合は、まず利用中のAPI、パラメータ、認証方式、ログ設計を棚卸ししてください。そのうえで、新規機能や大きな改修からv1 APIの設計に合わせるのが現実的です。
Chat CompletionsとResponses APIはどちらを使うべきですか
単純なチャット、要約、分類で既存実装が安定しているならChat Completionsで十分な場合があります。一方、ファイル、画像、ツール、会話状態、Structured Outputs、評価との連携を前提にする新規開発では、Responses APIを優先的に検討する価値があります。
api-version は省略してもよいですか
リファレンスでは、明示しない場合は v1 とされています。ただし、本番運用ではAPI versionを設定値として管理し、ステージング環境で検証してから反映する方が安全です。環境ごとの差分を追跡しやすくなるためです。
OpenAI向けのSDKコードをそのままAzure OpenAIで使えますか
そのまま動くとは限りません。APIの構造が似ていても、Azure側のendpoint、認証、利用可能なモデル、対応機能、ネットワーク制約が異なります。移植する場合は、まず最小リクエストで接続確認し、その後にtools、response_format、stream、Evalsなどの機能を段階的に検証してください。
Web searchや画像・動画関連のスキーマが見えたら使えると考えてよいですか
いいえ。コンポーネント定義に見える項目と、Azure OpenAIで実際に利用できる機能は同じではありません。リファレンス上でもWeb searchはAzure OpenAIではまだ利用できない旨が記載されています。実装判断では、エンドポイント、注記、対応モデル、リージョン、preview表記を必ず確認してください。(Microsoft Learn)
まず着手すべきこと
Microsoft Foundry / Azure OpenAIの2026年4月更新ポイントは、v1 REST API referenceを起点に、AIアプリの実装と運用を標準化することです。最初にやるべきことは、新機能を試すことではなく、既存コードのAPI呼び出し、パラメータ、認証、ログ、評価、RAGデータを棚卸しすることです。
開発者は max_tokens や functions などの古い実装を確認し、DevOps engineersはEvalsとログ設計をCI/CDに組み込み、platform teamsは認証、モデル台帳、Vector Stores、preview機能の利用ルールを整備してください。v1 REST API referenceを「API仕様」ではなく「生成AI基盤の運用標準」として読むことで、将来のモデル変更や機能拡張にも耐えやすい設計になります。
コメント