Azure AI Foundry REST API更新まとめ：Azure OpenAI in Microsoft Foundry Modelsの変更点と移行注意点

Azure AI FoundryでAzure OpenAIをREST APIから利用している場合、今回まず確認すべき結論は「既存のapi-version付きAPIをすぐ捨てる必要があるか」ではなく、「制御プレーン、データプレーン、v1 APIを混同せず、どのアプリがどのAPI面に依存しているかを棚卸しすること」です。

Microsoft Learnの「Azure OpenAI in Microsoft Foundry Models REST API reference」は、Azure OpenAIの推論REST APIを整理した公式リファレンスです。2026年5月20日前後に確認された更新では、Microsoft Learn上の最終更新表示は2026年5月19日となっており、安定版のデータプレーン推論仕様として2024-10-21、新しいv1 APIへの導線、認証方式、エンドポイント、管理APIとの役割分担を確認することが重要です。 (Microsoft Learn)

特に、社内Copilot、RAG、チャットボット、問い合わせ自動化、文書検索、画像生成、音声文字起こしなどをAzure AI Foundry上で構築している組織は、APIバージョン、認証、モデルデプロイ名、APIMやIaCの設定を一度見直すべきタイミングです。

Azure AI FoundryのREST API更新で押さえるべき全体像

今回の公式リファレンスで重要なのは、Azure OpenAIの操作が大きく3つのAPI面に分かれて整理されている点です。

API面	主な用途	管理者・開発者が見るべきポイント
Control plane	リソース作成、モデルデプロイ、上位のリソース管理	Azure Resource Manager、Bicep、Terraform、Azure CLIでの展開に影響
Data plane – authoring	モデルや関連リソースの作成・管理	ファインチューニング、ファイル、評価などの設計に影響
Data plane – inference	チャット、埋め込み、画像生成、音声処理などの実行	アプリケーションコード、REST呼び出し、SDK、APIMルーティングに影響

公式リファレンスでは、Control planeの最新プレビューとして2025-07-01-preview、最新GAとして2025-06-01が示されています。一方、データプレーンはv1 previewとv1が案内されており、API面ごとにプレビュー版とGA版の扱いが異なります。 (Microsoft Learn)

ここで失敗しやすいのは、「Azure OpenAIのAPIが変わった」と一括りにしてしまうことです。たとえば、Bicepでモデルデプロイを作成する処理と、アプリからchat/completionsを呼び出す処理では、見るべきリファレンスも影響範囲も違います。

今回の変更点を実務目線で整理

公式情報から読み取れる実務上のポイントは、次の5つです。

変更・確認ポイント	内容	実務への影響
API面の整理	Control plane、Data plane – authoring、Data plane – inferenceが明確に分けられている	管理系のIaCとアプリケーションの推論呼び出しを別々に点検する必要がある
安定版推論APIの確認	既存のGAデータプレーン推論仕様として`2024-10-21`が案内されている	本番環境で安定版を使っている場合、まずは現行APIバージョンの棚卸しが重要
v1 APIへの導線	v1 APIは、日付付き`api-version`への依存を減らす方向で設計されている	新規開発や最新機能の利用ではv1 APIを検討する価値がある
認証方式の再確認	APIキーとMicrosoft Entra IDの両方が利用可能	本番環境ではキー管理、RBAC、マネージドIDの設計を見直すべき
SDK・REST呼び出しの違い	v1 APIでは`/openai/v1/`を使う構成が示されている	既存URL、APIMのパス変換、環境変数、SDK初期化コードの修正が必要になる可能性がある

v1 APIについて、Microsoftは「日付付きapi-versionを毎月更新する必要を減らす」「OpenAIクライアントでAzure OpenAIを扱いやすくする」「一部の他プロバイダーモデル呼び出しにも対応する」といった方向性を示しています。 (Microsoft Learn)

ただし、これは「すべての既存システムを即時v1へ移行すべき」という意味ではありません。本番環境で2024-10-21などのGA APIを安定運用している場合は、まず依存箇所を洗い出し、ステージング環境でv1 APIの互換性を検証するのが安全です。

既存システムへの影響範囲

Azure AI FoundryのREST API更新で影響を受けやすいのは、次のようなシステムです。

社内向けCopilotやチャットボット
Azure AI Searchと連携したRAGアプリ
Embeddings APIを使った文書検索・類似検索
音声文字起こしや翻訳を組み込んだ業務アプリ
画像生成を組み込んだコンテンツ制作支援ツール
API Management経由でAzure OpenAIを公開している構成
Bicep、Terraform、Azure CLIでモデルデプロイを自動化している環境

特に注意すべきなのは、アプリケーションコードだけではありません。API Management、Key Vault、マネージドID、ネットワーク制御、ログ収集、課金監視、デプロイパイプラインまで含めて確認する必要があります。

旧形式のREST APIとv1 APIの違い

既存のREST APIでは、次のようにデプロイ名をパスに含め、api-versionをクエリパラメータで指定する形式が一般的です。

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2024-10-21

一方、v1 APIでは次のように/openai/v1/を含むベースURLを使い、リクエスト本文のmodelにモデルデプロイ名を指定する考え方になります。

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/chat/completions

v1 APIのリファレンスではAPI Versionがv1とされ、api-versionは明示的に指定しない場合にv1として扱われる形で説明されています。認証はAPIキーのapi-keyヘッダー、または認可トークンのauthorizationヘッダーを使う構成です。 (Microsoft Learn)

開発者がコードで確認すべき項目

確認箇所	旧形式でありがちな実装	v1 API検討時の確認ポイント
エンドポイント	`/openai/deployments/{deployment-id}/...`	`/openai/v1/...`に変更する必要があるか
APIバージョン	`?api-version=2024-10-21`などを固定	v1では日付付きAPIバージョン指定をどう扱うか
モデル指定	パス内の`deployment-id`	本文の`model`にデプロイ名を指定する設計か
SDK初期化	Azure OpenAI専用クライアントを使用	OpenAIクライアント利用へ寄せるか
認証	APIキーを直接指定	Microsoft Entra ID、マネージドID、トークン更新を検討
APIM	旧パスを前提にルーティング	`/openai/v1/`のパス変換、ポリシー、ヘッダー制御を確認

Pythonのv1 API例では、AzureOpenAI()ではなくOpenAI()クライアントを使い、base_urlに/openai/v1/を付与する構成が示されています。また、Microsoft Entra IDを使う場合はトークンプロバイダーをapi_key相当の引数に渡し、自動トークン更新を扱う例も示されています。 (Microsoft Learn)

管理者が確認すべき設定

認証はAPIキー前提のままにしない

公式リファレンスでは、Azure OpenAIの認証方法としてAPIキーとMicrosoft Entra IDが案内されています。APIキー方式ではapi-keyヘッダー、Microsoft Entra IDではAuthorization: Bearer ...形式のトークンを使います。 (Microsoft Learn)

本番環境では、次の観点で確認してください。

確認項目	推奨される確認内容
APIキーの保管場所	ソースコードや環境変数に平文で固定せず、Key Vaultなどで管理しているか
キーのローテーション	運用手順、影響範囲、切り戻し手順があるか
Microsoft Entra ID	アプリやマネージドIDに必要最小限のロールが割り当てられているか
APIM経由の認証	バックエンドキーをAPIMで安全に注入しているか
ログ出力	APIキー、トークン、プロンプト内の機密情報をログに出していないか

v1 APIの前提条件では、Microsoft Entra ID認証のためにCognitive Services OpenAI Userロールの割り当てが示されています。権限不足による401/403エラーは移行時に起きやすいため、ステージング環境で先に検証しておくと安全です。 (Microsoft Learn)

Control planeとData planeを分けて管理する

モデルデプロイやリソース作成をBicep、Terraform、Azure CLIで自動化している場合、Control planeのAPIバージョンを確認してください。アプリケーションが呼び出す推論APIの変更だけを見ていると、デプロイ自動化の失敗に気づけないことがあります。

たとえば、次のように役割を分けて管理すると、変更時の影響範囲を切り分けやすくなります。

管理対象	主担当	変更時に確認するもの
Azure OpenAIリソース作成	インフラ管理者	ARM、Bicep、Terraform、Azure CLI
モデルデプロイ	インフラ管理者、AI基盤担当	デプロイ名、モデル、リージョン、クォータ
REST API呼び出し	アプリ開発者	エンドポイント、認証、リクエスト本文、レスポンス処理
APIM公開	プラットフォーム管理者	パス変換、ヘッダー、レート制限、監査ログ
監視・課金	運用担当	トークン使用量、エラー率、レイテンシ、異常な利用

開発者が注意すべきAPI仕様

Chat completionsでは`tools`への移行を意識する

既存コードでfunctionsやfunction_callを使っている場合は注意が必要です。公式リファレンスでは、これらはtoolsやtool_choiceを優先する形で説明されており、functionsとfunction_callは非推奨として扱われています。 (Microsoft Learn)

すぐに壊れるとは限りませんが、新規実装や改修ではtoolsベースに寄せるのが無難です。特に、社内システム連携、検索、チケット作成、ワークフロー起動などをAIから呼び出す構成では、ツール定義のJSON Schema、権限、入力検証を改めて確認してください。

JSON modeやStructured Outputsは指示文まで含めて設計する

response_formatでJSON出力を指定できる機能は便利ですが、JSON modeを使う場合は、システムメッセージまたはユーザーメッセージでもJSONを出力するよう明示する必要があります。公式リファレンスでは、指示がない場合に空白が長く生成され、リクエストが止まったように見える可能性があると説明されています。 (Microsoft Learn)

実務では、次のような設計にしてください。

{
  "response_format": {
    "type": "json_object"
  },
  "messages": [
    {
      "role": "system",
      "content": "必ず有効なJSONオブジェクトのみを返してください。説明文やMarkdownは出力しないでください。"
    },
    {
      "role": "user",
      "content": "問い合わせ内容を category, priority, summary に分類してください。"
    }
  ]
}

ここで重要なのは、APIパラメータだけでなく、プロンプト側でも出力形式を制御することです。JSONを業務システムに渡す場合は、レスポンスをそのまま信頼せず、必ずサーバー側でスキーマ検証を行いましょう。

Embeddingsは次元数とインデックス設計に注意する

Embeddings APIは、検索、推薦、類似文書抽出、RAGの基盤になります。v1リファレンスでは/openai/v1/embeddingsが示され、入力テキストから埋め込みベクトルを作成するAPIとして説明されています。dimensionsはtext-embedding-3以降のモデルでサポートされる項目です。 (Microsoft Learn)

移行時に失敗しやすいのは、モデル変更に伴ってベクトル次元数が変わるケースです。Azure AI SearchやベクトルDBのインデックスは、次元数が違うとそのまま流用できない場合があります。

確認すべき項目は次の通りです。

確認項目	失敗例	対策
埋め込みモデル	旧モデルから新モデルへ変更	次元数、料金、対応リージョンを確認
ベクトル次元数	既存インデックスと不一致	新規インデックス作成や再インデックスを計画
チャンク分割	長すぎる文書をそのまま投入	文書単位、段落単位、見出し単位で分割ルールを決める
検索品質	移行後に回答精度が低下	検索上位件数、フィルター、再ランキングを検証
コスト	大量文書を一括再処理	バッチ単位で処理し、トークン使用量を監視

Responses APIは新規開発で優先的に検討する

v1 APIのライフサイクル記事では、Azure OpenAIモデルにはResponses APIの利用が推奨されています。また、v1 APIはDeepSeekやGrokなど、OpenAI v1のchat completions構文をサポートする他プロバイダーモデルの呼び出しにも対応する説明があります。 (Microsoft Learn)

既存のchat/completionsをすぐに置き換える必要があるとは限りません。ただし、新規のAIアプリや、マルチモーダル、ツール呼び出し、評価、将来の拡張性を重視するプロジェクトでは、最初からResponses APIを前提に設計した方が長期運用しやすくなります。

API Managementを使っている環境の注意点

Azure API Management経由でAzure OpenAIを公開している場合、APIのパス、ヘッダー、バックエンドURL、認証注入、レート制限を必ず確認してください。

特に、プレビューAPI仕様をAPIMへインポートしている環境では注意が必要です。公式のAPIライフサイクル記事では、2025-04-01-previewのAzure OpenAI仕様がOpenAPI 3.1を使用しており、Azure API Managementで完全にはサポートされていない既知の問題が示されています。 (Microsoft Learn)

APIMを使う場合の実務チェックは次の通りです。

確認項目	チェック内容
バックエンドURL	旧形式の`/openai/deployments/...`とv1の`/openai/v1/...`を混在させていないか
ヘッダー	`api-key`、`Authorization`、`Content-Type`を正しく処理しているか
レート制限	ユーザー単位、アプリ単位、モデル単位で制御できているか
ログ	機密情報、プロンプト、生成結果を必要以上に保存していないか
OpenAPI定義	プレビュー仕様をそのまま本番APIMへ取り込んでいないか
切り戻し	v1移行後に旧APIへ戻せるルートや設定を残しているか

APIMを単なる中継点としてではなく、認証、監査、流量制御、段階移行のための制御点として使うと、API変更時のリスクを下げられます。

Copilot開発への影響

今回の更新は、Microsoft 365 Copilotの管理画面が変わるという話ではありません。影響を受けるのは、Azure AI FoundryやAzure OpenAIを使って独自のCopilot、社内AIアシスタント、RAGアプリを構築しているケースです。

たとえば、次のような構成は確認対象です。

TeamsやWebアプリからAzure OpenAIを呼び出す社内チャットボット
Azure AI Searchと連携して社内文書を回答に使うRAG
顧客対応履歴を要約するCRM連携AI
問い合わせを分類してチケット化する業務Copilot
音声データを文字起こしし、要約や分類まで行うワークフロー

これらのシステムでは、ユーザーから見える画面は変わらなくても、裏側のREST API、モデルデプロイ、認証、ログ設計が変わる可能性があります。特に、業務部門が「AIの回答が遅くなった」「検索結果の根拠が変わった」と感じる場合、API移行だけでなく、モデル、検索インデックス、プロンプト、ツール呼び出しまで含めて確認する必要があります。

移行・展開時のおすすめ手順

Azure AI FoundryのREST APIを見直す場合は、いきなり本番コードを書き換えるのではなく、次の順番で進めると安全です。

手順	作業内容	目的
現状棚卸し	利用中のエンドポイント、APIバージョン、SDK、モデルデプロイ名を一覧化	影響範囲を明確にする
API方針決定	既存GA APIを継続するか、v1 APIを検証するかを決める	無理な一括移行を避ける
認証確認	APIキー、Entra ID、マネージドID、RBACを確認	移行時の401/403を防ぐ
ステージング検証	同じプロンプト、同じ入力データで比較テスト	出力品質、レイテンシ、コストを確認
レスポンス処理確認	JSON、ストリーミング、ツール呼び出し、エラー処理を検証	本番障害を防ぐ
APIM・監視更新	ルーティング、レート制限、ログ、アラートを調整	運用上の見落としを防ぐ
段階リリース	一部ユーザーや一部機能から切り替え	問題発生時に影響を限定する
切り戻し準備	旧APIへ戻す設定、環境変数、デプロイ手順を残す	予期しない不具合に備える

移行判断では、「新しいから移行する」ではなく、「どの機能を使うために移行するのか」を明確にしてください。理由が曖昧な移行は、コスト増、品質低下、運用負荷の増加につながりやすくなります。

よくある失敗と対策

URLだけv1に変えて、リクエスト本文を旧形式のまま送る

v1 APIでは、エンドポイント形式やモデル指定の考え方が変わります。URLだけを変更して、旧形式のdeployment-id前提のコードや環境変数を残すと、404や400エラーの原因になります。

対策として、環境変数を次のように分けて管理すると混乱を防げます。

AZURE_OPENAI_LEGACY_ENDPOINT=https://YOUR_RESOURCE_NAME.openai.azure.com
AZURE_OPENAI_V1_BASE_URL=https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/
AZURE_OPENAI_MODEL_DEPLOYMENT=gpt-4o-prod

プレビューAPIを本番で固定してしまう

プレビューAPIは新機能を試すには有効ですが、仕様変更のリスクがあります。プレビュー機能を本番で使う場合は、明確な理由、検証記録、切り戻し手順、監視項目をセットで用意してください。

特に、API Management、SDK、自動生成クライアント、社内共通ライブラリにプレビュー仕様を組み込む場合は、影響範囲が広がりやすくなります。

`max_tokens`と`max_completion_tokens`を混同する

新しい推論モデルやreasoning系モデルでは、従来のmax_tokensだけでは意図通りに制御できないケースがあります。公式リファレンスでは、チャット補完のリクエスト本文にmax_completion_tokensが含まれており、可視出力トークンと推論トークンを含む上限として説明されています。 (Microsoft Learn)

コストやレイテンシを制御したい場合は、モデルごとに対応パラメータを確認し、単に過去コードのmax_tokensを流用しないようにしましょう。

`n`や`best_of`で想定以上にトークンを消費する

Completions APIでは、nやbest_ofを増やすと複数候補を生成するため、トークン消費が急増します。公式リファレンスでも、これらのパラメータはトークンクォータを素早く消費する可能性があるため注意が促されています。 (Microsoft Learn)

本番アプリでは、候補数を増やす前に、次の順番で改善するのが現実的です。

プロンプトを改善する
JSON SchemaやStructured Outputsで出力を安定させる
温度やtop_pを調整する
評価データで品質を比較する
最後に候補数を増やすか判断する

まず実施すべきチェックリスト

Azure AI FoundryやAzure OpenAIを本番利用している管理者・開発者は、次のチェックから始めてください。

チェック項目	確認できたらOK
利用中のAPIバージョン	`2024-10-21`、`2025-04-01-preview`、v1などを一覧化している
API面の分類	Control planeとData planeを混同せず整理している
エンドポイント	旧形式とv1形式の違いを把握している
認証方式	APIキー、Entra ID、マネージドIDのどれを使うか明確
モデルデプロイ名	コード、環境変数、APIMで一貫している
SDKバージョン	v1 API利用時に必要なSDK構成を確認している
APIM	パス変換、ヘッダー、OpenAPI定義、ログを確認している
RAG構成	Azure AI Search、埋め込みモデル、インデックス次元数を確認している
監視	エラー率、レイテンシ、トークン使用量、コストを見ている
切り戻し	旧APIへ戻す手順がある

まとめ：最初にやるべきことは「移行」ではなく「棚卸し」

Azure AI Foundryの「Azure OpenAI in Microsoft Foundry Models REST API reference」更新で重要なのは、APIが増えたことそのものではなく、管理、開発、運用で見るべきAPI面がより明確になったことです。

既存の本番環境では、まず利用中のAPIバージョン、エンドポイント、認証方式、モデルデプロイ名、APIM設定を棚卸ししてください。そのうえで、新規開発や最新機能を使うプロジェクトではv1 APIやResponses APIを検証し、既存の安定稼働システムでは段階移行と切り戻しを前提に進めるのが現実的です。

管理者はControl plane、認証、権限、ネットワーク、監視を確認し、開発者はRESTエンドポイント、SDK初期化、レスポンス処理、ツール呼び出し、JSON出力、Embeddingsの次元数を確認しましょう。これらを先に整理しておけば、Azure AI Foundry上の社内CopilotやAIアプリを安全に更新できます。

この記事を書いた人

佐藤健司

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

Azure AI Foundry REST API更新まとめ：Azure OpenAI in Microsoft Foundry Modelsの変更点と移行注意点

Azure AI FoundryのREST API更新で押さえるべき全体像

今回の変更点を実務目線で整理

既存システムへの影響範囲

旧形式のREST APIとv1 APIの違い

開発者がコードで確認すべき項目

管理者が確認すべき設定

認証はAPIキー前提のままにしない

Control planeとData planeを分けて管理する

開発者が注意すべきAPI仕様

Chat completionsでは`tools`への移行を意識する

JSON modeやStructured Outputsは指示文まで含めて設計する

Embeddingsは次元数とインデックス設計に注意する

Responses APIは新規開発で優先的に検討する

API Managementを使っている環境の注意点

Copilot開発への影響

移行・展開時のおすすめ手順

よくある失敗と対策

URLだけv1に変えて、リクエスト本文を旧形式のまま送る

プレビューAPIを本番で固定してしまう

`max_tokens`と`max_completion_tokens`を混同する

`n`や`best_of`で想定以上にトークンを消費する

まず実施すべきチェックリスト

まとめ：最初にやるべきことは「移行」ではなく「棚卸し」

この記事を書いた人

コメント

コメントするコメントをキャンセル

Azure AI Foundry REST API更新まとめ：Azure OpenAI in Microsoft Foundry Modelsの変更点と移行注意点

Azure AI FoundryのREST API更新で押さえるべき全体像

今回の変更点を実務目線で整理

既存システムへの影響範囲

旧形式のREST APIとv1 APIの違い

開発者がコードで確認すべき項目

管理者が確認すべき設定

認証はAPIキー前提のままにしない

Control planeとData planeを分けて管理する

開発者が注意すべきAPI仕様

Chat completionsではtoolsへの移行を意識する

JSON modeやStructured Outputsは指示文まで含めて設計する

Embeddingsは次元数とインデックス設計に注意する

Responses APIは新規開発で優先的に検討する

API Managementを使っている環境の注意点

Copilot開発への影響

移行・展開時のおすすめ手順

よくある失敗と対策

URLだけv1に変えて、リクエスト本文を旧形式のまま送る

プレビューAPIを本番で固定してしまう

max_tokensとmax_completion_tokensを混同する

nやbest_ofで想定以上にトークンを消費する

まず実施すべきチェックリスト

まとめ：最初にやるべきことは「移行」ではなく「棚卸し」

この記事を書いた人

関連記事

コメント

コメントする コメントをキャンセル

Chat completionsでは`tools`への移行を意識する

`max_tokens`と`max_completion_tokens`を混同する

`n`や`best_of`で想定以上にトークンを消費する

コメントするコメントをキャンセル