Azure AI Foundry でデプロイした Azure OpenAI のモデルエンドポイントを、Azure API Management に REST API として取り込めるようにする手順が整理されています。結論から言うと、新規構築では Microsoft Foundry から直接インポートする方法が第一候補です。API Management 側で /openai エンドポイント、認証、バックエンド接続、AI ゲートウェイ関連の管理をまとめやすくなるため、複数アプリから Azure OpenAI を使う企業環境では特に効果があります。(Microsoft Learn)
一方で、既存の OpenAPI 管理フローに合わせたい場合や、API 仕様を編集してから取り込みたい場合は、Azure OpenAI REST API の OpenAPI 仕様をダウンロードして API Management に追加する方法も使えます。ただし、この方法では認証設定を管理者が明示的に構成する必要があります。移行期限や廃止期限が示された変更ではありませんが、管理者はエンドポイント形式、認証方式、deployment-id、api-version、トークン制限、監視設定を確認しておくべきです。(Microsoft Learn)
Azure AI Foundry と API Management 連携で何が変わるのか
今回の「Import an Azure OpenAI API as a REST API」は、Azure AI Foundry の Azure OpenAI モデルデプロイを、Azure API Management の API として扱うための実務的な手順です。対象はすべての API Management レベルとされており、特定の上位 SKU だけに閉じた話ではありません。(Microsoft Learn)
ポイントは、アプリケーションが Azure OpenAI のエンドポイントへ直接アクセスする構成から、API Management を経由する構成へ整理できることです。これにより、認証、アクセス制御、利用量の管理、監視、ポリシー適用を API Gateway 層に集約できます。
たとえば、社内に複数の生成 AI アプリがある場合、各アプリが個別に Azure OpenAI のキーやエンドポイントを持つ構成は管理が複雑になります。API Management を前段に置けば、アプリ側には統一された API を公開し、バックエンドの Azure OpenAI への接続や認証は管理者側で制御できます。
更新ポイントの要点
今回確認すべきポイントは、「Azure OpenAI を API Management に登録できる」という単純な機能紹介ではありません。実務上は、どの取り込み方法を選ぶか、クライアント互換性をどう設計するか、認証を API キーのままにするかマネージド ID に寄せるかが重要です。
| 確認項目 | 内容 | 管理者が見るべきポイント |
|---|---|---|
| 取り込み方法 | Microsoft Foundry から直接インポート、または OpenAPI 仕様から追加 | 新規構築は直接インポートを優先 |
| 対象 | Azure OpenAI in Foundry Models のモデルデプロイ | 対象のデプロイ ID を事前に確認 |
| エンドポイント | /openai を含む API Management 側のパス | 既存クライアントの URL 変更影響を確認 |
| 認証 | API キーまたはマネージド ID | 本番環境ではマネージド ID を優先検討 |
| テスト | API Management の Test タブで実行 | deployment-id と api-version が必要 |
| 運用管理 | トークン使用量、制限、監視、ポリシー適用 | 部門別・アプリ別の利用制御を設計 |
公式手順では、Azure OpenAI API を API Management に取り込む方法として、Microsoft Foundry のデプロイから直接インポートする方法と、OpenAPI 仕様をダウンロードして追加する方法の2つが示されています。(Microsoft Learn)
推奨は Microsoft Foundry からの直接インポート
新規に Azure AI Foundry と API Management の連携を設計するなら、まず検討すべきは Microsoft Foundry からの直接インポートです。
この方法では、API Management のポータルから Microsoft Foundry を選択し、対象の Foundry ツールやモデルデプロイを指定して API を作成します。インポート時には、API の REST エンドポイント、システム割り当てマネージド ID、バックエンドリソース、set-backend-service ポリシー、バックエンド認証などが自動的に構成されます。(Microsoft Learn)
特に重要なのは、マネージド ID による認証を自動構成できる点です。OpenAPI 仕様を手動で取り込む場合は認証設定を別途構成する必要がありますが、Foundry から直接インポートする場合は、API Management インスタンスのマネージド ID を使った認証が自動的に構成されます。(Microsoft Learn)
直接インポートが向いているケース
Microsoft Foundry からの直接インポートは、次のようなケースに向いています。
- Azure AI Foundry 上の Azure OpenAI モデルを本番アプリから利用する
- 複数のアプリや部門に同じモデル基盤を提供する
- API キーをアプリ側に持たせたくない
- トークン使用量やレート制限を API Management 側で管理したい
- 将来的にセマンティックキャッシュやコンテンツ安全性ポリシーを適用したい
実務では、「まず動かす」だけならアプリから Azure OpenAI に直接接続する方が簡単です。しかし、利用部門やアプリが増えると、キー管理、利用量の偏り、障害時の切り分け、ログ取得が難しくなります。API Management を挟む構成は、PoC から本番運用へ進む段階で価値が出ます。
OpenAPI 仕様から追加する方法は既存管理フロー向け
もう一つの方法は、Azure OpenAI REST API の OpenAPI 仕様をダウンロードし、Azure API Management に OpenAPI API として追加する方法です。公式手順では、例として 2024-10-21 GA バージョンの仕様が挙げられています。(Microsoft Learn)
この方法では、OpenAPI 仕様内の servers 要素を自社の Azure OpenAI エンドポイントに合わせて編集します。たとえば、Azure OpenAI エンドポイントが contoso.openai.azure.com の場合、url は https://contoso.openai.azure.com/openai、既定の endpoint は contoso.openai.azure.com のように設定します。(Microsoft Learn)
OpenAPI 仕様からの追加が向いているケース
OpenAPI 仕様からの追加は、次のような組織に向いています。
| ケース | 理由 |
|---|---|
| API 仕様を Git で管理している | OpenAPI ファイルをレビュー・承認フローに載せやすい |
| API Management への取り込みを IaC や CI/CD に組み込みたい | ポータル操作に依存しない運用にしやすい |
| 既存の API 命名規則やパス設計に合わせたい | 仕様編集で調整できる |
| 監査上、API 仕様の差分管理が必要 | 変更履歴を残しやすい |
ただし、手動取り込みでは認証設定を忘れやすい点に注意が必要です。Azure OpenAI API への認証には API キーまたはマネージド ID を使えますが、OpenAPI 仕様から追加した場合は、API Management ポリシーなどで認証を構成する必要があります。(Microsoft Learn)
クライアント互換性は最初に決める
Microsoft Foundry API のインポートでは、クライアント互換性の選択が重要です。API Management では、Microsoft Foundry の AI API に対して、Azure OpenAI、Azure AI、Azure OpenAI v1 などのクライアント互換性オプションが用意されています。(Microsoft Learn)
選択を誤ると、アプリ側のリクエストパスやリクエスト本文の作り方に影響します。後から変更できるとしても、既存アプリの修正やテストが必要になるため、最初に利用予定のクライアントとモデル種別を整理しておくべきです。
| 互換性オプション | 主な用途 | 呼び出し形式の考え方 |
|---|---|---|
| Azure OpenAI | Azure OpenAI in Foundry Models のデプロイを扱う | /openai/deployments/{deployment-id}/... のようにパスにデプロイ名を含める |
| Azure AI | Azure AI Model Inference API 経由のモデルも扱いたい | 複数モデルを切り替える設計に向く |
| Azure OpenAI v1 | Azure OpenAI API version 1 を使う構成 | v1 形式のクライアントとの整合性を重視 |
既存の Azure OpenAI SDK や REST クライアントを活かすなら、Azure OpenAI 互換の /openai エンドポイントを意識して設計するのが分かりやすい選択です。一方、将来的に Azure OpenAI 以外のモデルも同じ API 基盤で扱いたい場合は、Azure AI 側の互換性も検討対象になります。
認証は API キーよりマネージド ID を優先検討する
本番運用で特に見直したいのが認証です。Azure OpenAI API への認証には API キーとマネージド ID の選択肢があります。API キーを使う場合、API Management の Named values にシークレットとして保存し、ポリシーで api-key ヘッダーを付与できます。より安全に扱う場合は Key Vault 参照も検討できます。(GitHub)
ただし、Azure 環境内で完結する本番構成では、マネージド ID を優先的に検討する価値があります。API Management のシステム割り当てまたはユーザー割り当てマネージド ID に、対象リソースへの適切なロールを付与し、API Management から Azure OpenAI へ認証させる構成です。公式情報では、マネージド ID に Cognitive Services OpenAI User ロールを適切なスコープで割り当てる手順が示されています。(GitHub)
認証方式の判断基準
| 認証方式 | メリット | 注意点 |
|---|---|---|
| API キー | 実装が分かりやすい。既存構成から移行しやすい | キーの漏えい、ローテーション、保管場所の管理が必要 |
| マネージド ID | キーをアプリや設定ファイルに持たせずに済む | RBAC 設計と権限付与の確認が必要 |
| OAuth 2.0 併用 | 利用者やアプリ単位で細かく制御しやすい | Azure OpenAI へのバックエンド認証の代替ではなく、多層防御として設計する |
OAuth 2.0 は、API Management にアクセスするユーザーやアプリを事前認可する用途で有効です。ただし、公式情報でも示されている通り、OAuth 2.0 は API キーやマネージド ID による Azure OpenAI への認証を置き換えるものではなく、防御を重ねるための仕組みとして考えるべきです。(GitHub)
管理者が確認すべき設定変更
Azure AI Foundry の Azure OpenAI API を API Management に取り込む前に、管理者は次の項目を確認してください。
| 確認項目 | 具体的な確認内容 | 失敗しやすいポイント |
|---|---|---|
| API Management インスタンス | 既存インスタンスを使うか、新規作成するか | PoC 用インスタンスを本番流用して権限や監視が不足する |
| Foundry プロジェクト | Azure OpenAI モデルがデプロイ済みか | デプロイ名をアプリ側のモデル名と混同する |
| デプロイ ID | API Management のテストで使う deployment-id を控える | モデル名ではなくデプロイ名が必要になる |
| API バージョン | 利用する api-version を確認する | OpenAPI 仕様のバージョンと実際の呼び出しがずれる |
| API URL suffix | /openai で終わるパスを設計する | 既存クライアントのベース URL と衝突する |
| 認証 | API キー、マネージド ID、OAuth の役割を分ける | フロント側認可とバックエンド認証を混同する |
| サブスクリプションキー | API Management の Product と Subscription を設計する | built-in の all-access subscription を本番確認用に使い続ける |
| 監視 | token usage、ログ、メトリックを確認する | 成功レスポンスだけ見て利用量の追跡を忘れる |
特に注意したいのは、API Management のテストコンソールです。テスト時には deployment-id と api-version を指定し、モデルに対応した操作を選ぶ必要があります。テストが成功すると、バックエンドから成功コードとデータが返り、レスポンスにはトークン使用量の情報も含まれます。(Microsoft Learn)
影響範囲はアプリ開発者、API 管理者、セキュリティ担当に及ぶ
この変更の影響は、Azure AI Foundry の管理者だけに閉じません。実際には、アプリ開発者、API 管理者、セキュリティ担当、コスト管理担当にまたがります。
アプリ開発者にとっては、Azure OpenAI の直接エンドポイントではなく、API Management 側のベース URL を使う構成になる可能性があります。deployment-id や api-version の扱いも、API Management 側の設計に合わせて確認が必要です。
API 管理者にとっては、API の Product への関連付け、Subscription Key、ポリシー、バックエンド、ログ、レート制限の設計が作業範囲になります。セキュリティ担当は、API キーをアプリ側に持たせる必要があるか、マネージド ID に寄せられるか、OAuth 2.0 による利用者単位の制御を追加するかを確認すべきです。
コスト管理担当にとっては、トークン使用量の可視化と制限が重要です。API Management の AI gateway では、AI バックエンドの認証、ロードバランス、ログ、トークン使用量、クォータ管理などを扱えます。(Microsoft Learn)
AI gateway と組み合わせると運用価値が高まる
Azure API Management の AI gateway は、AI モデル、エージェント、ツールを安全に運用するための機能群です。既存の API Management を拡張する位置づけであり、別サービスとして分離されたものではありません。(Microsoft Learn)
Azure OpenAI API を API Management に取り込むだけでも、エンドポイントの統一や認証管理の効果はあります。しかし、本番環境では AI gateway のポリシーを組み合わせることで、より実用的な管理ができます。
たとえば、LLM token limit policy を使うと、サブスクリプションキー、送信元 IP、任意のポリシー式などをカウンターキーとして、TPM や一定期間のトークンクォータを設定できます。これにより、特定のアプリや部門がトークン枠を使い切り、他のアプリが利用できなくなる事態を防ぎやすくなります。(Microsoft Learn)
また、セマンティックキャッシュを使うと、過去のプロンプトと意味的に近いリクエストに対してキャッシュ済みの応答を再利用し、バックエンドへの呼び出し回数、応答時間、コストを抑えられる可能性があります。(Microsoft Learn)
移行期限はあるのか
今回の公式手順は、Azure OpenAI API を API Management に REST API として取り込むための構成ガイドであり、特定日までに移行しなければならない廃止告知ではありません。少なくとも対象ページ内では、既存の Azure OpenAI 直接接続を廃止する期限や、強制移行期限は示されていません。(Microsoft Learn)
ただし、移行期限がないからといって後回しにしてよいわけではありません。複数のアプリが Azure OpenAI を使い始めてから API Gateway 化しようとすると、URL、認証、ログ、利用量管理、権限設計を後付けで直すことになります。
特にグローバル環境では、リージョン、部門、アプリごとに利用量や権限が分かれます。早い段階で API Management を前段に置く設計にしておくと、あとからモデル追加、リージョン追加、ポリシー変更をしやすくなります。
導入手順の実務イメージ
実際に導入する場合は、次の順番で進めると失敗を減らせます。
| 手順 | 作業 | 確認ポイント |
|---|---|---|
| 1 | Azure AI Foundry で Azure OpenAI モデルをデプロイ | デプロイ ID を控える |
| 2 | API Management インスタンスを確認 | 本番用の SKU、ネットワーク、監視設定を確認 |
| 3 | Microsoft Foundry から API をインポート | クライアント互換性と Base path を決める |
| 4 | 認証方式を確認 | 直接インポートならマネージド ID 自動構成を確認 |
| 5 | Test タブで動作確認 | deployment-id と api-version を指定 |
| 6 | Product と Subscription を設計 | 利用者・アプリ単位の公開範囲を決める |
| 7 | ポリシーを追加 | トークン制限、ログ、必要に応じてセマンティックキャッシュ |
| 8 | アプリ側の接続先を切り替え | 旧 URL 直接接続が残っていないか確認 |
PoC では、まず API Management 経由でチャット補完などの基本リクエストが成功することを確認します。その後、本番化に向けて、サブスクリプションキーの払い出し単位、ログの保存先、トークン制限値、障害時の切り分け手順を決める流れが現実的です。
よくある失敗と対策
デプロイ名とモデル名を混同する
Azure OpenAI の呼び出しでは、モデル名ではなくデプロイ ID が必要になる場面があります。API Management のテストでも deployment-id を指定するため、Foundry 側のデプロイ名を正確に控えておくことが重要です。(Microsoft Learn)
/openai のパス設計を後で変える
API URL suffix を適当に決めると、後からアプリ側の修正が広範囲に及びます。公式手順では、API Management インスタンスから Azure OpenAI API エンドポイントへアクセスするため、/openai で終わる API URL suffix を指定する例が示されています。(Microsoft Learn)
本番では、my-openai-api/openai のような検証用の名前ではなく、環境、用途、チーム名を含めた命名規則を決めてから作成すると運用しやすくなります。
テストコンソールの all-access subscription を本番前提で使う
API Management のテストコンソールでは、Ocp-Apim-Subscription-Key ヘッダーと built-in の all-access subscription が自動的に設定されます。このキーは API Management インスタンス内のすべての API にアクセスできるため、本番の利用者向けキーとは分けて考える必要があります。(Microsoft Learn)
本番公開時は Product を分け、アプリ単位や部門単位で Subscription を払い出す設計にしましょう。
認証と認可を混同する
Azure OpenAI へのバックエンド認証と、利用者・アプリが API Management にアクセスする際の認可は別の話です。
バックエンド認証には API キーまたはマネージド ID を使います。一方、利用者やアプリ単位で細かく制御したい場合は、OAuth 2.0 や Microsoft Entra ID を使った認可を API Management 側で追加します。OAuth 2.0 は多層防御として有効ですが、Azure OpenAI へのバックエンド認証そのものの代替ではありません。(GitHub)
グローバル運用での確認ポイント
グローバル向けに Azure AI Foundry と API Management を運用する場合は、単一リージョンの構成だけで判断しない方が安全です。利用者の地域、データ境界、レイテンシ、障害時の継続性を踏まえて設計します。
| 観点 | 確認内容 |
|---|---|
| リージョン | API Management と Azure OpenAI の配置リージョン、利用者地域との距離 |
| データ管理 | ログにプロンプトや応答を残すか、マスキングが必要か |
| 可用性 | 複数リージョン構成、バックエンド分散、障害時の迂回 |
| コスト | アプリ別・部門別のトークン使用量、上限、アラート |
| セキュリティ | マネージド ID、RBAC、Subscription、OAuth 2.0 の役割分担 |
| 開発者体験 | 既存 SDK との互換性、エンドポイント形式、ドキュメント整備 |
API Management 自体はスケールユニット追加やマルチリージョン展開などのスケーリング機能を持ちますが、AI バックエンド側の容量やリージョン配置も合わせて考える必要があります。公式情報でも、API Management のゲートウェイ容量だけでなく、AI バックエンド側の負荷分散や分散配置を考慮する必要があると説明されています。(Microsoft Learn)
管理者が今すぐ確認すべきこと
まず、現在のアプリが Azure OpenAI に直接接続しているか、すでに API Management などのゲートウェイを経由しているかを棚卸ししてください。直接接続が多い場合は、キー管理、ログ、利用量制限の観点でリスクが高くなりやすいです。
次に、Azure AI Foundry 上のモデルデプロイ一覧を確認し、どのデプロイを API Management 経由で公開するかを決めます。そのうえで、Microsoft Foundry からの直接インポートを検証し、マネージド ID、/openai パス、deployment-id、api-version、トークン使用量の見え方を確認します。
最後に、本番化する前に Product、Subscription、ポリシー、ログ、トークン制限、OAuth 2.0 の要否を設計してください。今回の更新ポイントは、単なるインポート手順ではなく、Azure OpenAI を組織内の共通 AI API として安全に提供するための入口です。小さく検証し、早い段階で API Management 経由の標準パターンを作っておくことが、後の運用負荷を大きく下げます。
コメント