Azure OpenAI APIの使い方｜リソース作成からPython・REST呼び出しまでの実装手順

Azure OpenAI APIは、リソースを作ってモデルをデプロイし、エンドポイントと資格情報を取り出せば動き出します。詰まりどころは手順の多さではありません。デプロイ名という独自概念と、2025年8月に登場したv1形式のクライアント初期化の2点に集約されます。この記事では、リソース作成からモデルデプロイ、エンドポイントとAPIキーの取得、Python SDKとRESTでの呼び出し、Entra IDによるキーレス認証への切り替えまでを、2026年8月16日時点の公式ドキュメント実測にもとづいて整理しました。OpenAI直APIのコードをAzureへ移すとき、書き換える箇所と据え置ける箇所も切り分けます。

まとめ：Azure OpenAI APIを動かすまでの四工程と認証方式の決め方

やることは四つです。Azure OpenAI（Microsoft Foundry）のリソースを作り、モデルをデプロイしてデプロイ名を決め、エンドポイントと資格情報を取得し、クライアントから呼び出す。この順番を崩さなければ、初回の疎通は短時間で済みます。

実装で最初に決めるのは認証方式です。試作段階はAPIキーで構いませんが、本番運用ではEntra IDのトークンに寄せます。v1形式のAPIなら初期化の差はapi_keyに何を渡すかの一行だけで、切り替えのコストは小さくなりました。

もう一つの決めどころがモデル名の扱いです。Azure OpenAIではmodel引数にモデル名ではなくデプロイ名を渡します。ここを取り違えると404が返り、原因がコードにもキーにも見当たらないまま時間を失いがちです。以降の章は、この二点を軸に手順と判断基準を具体化しました。

Azure OpenAI APIの呼び出しに必要な四つの構成要素と役割分担

呼び出しの成立には、エンドポイント、デプロイ名、資格情報、クライアントライブラリの四つが要ります。どこで発行され、コードのどの引数に入るのかを先に押さえてください。サービス全体の位置づけや料金体系はAzure OpenAI Serviceとは？できること・料金・導入事例まで実務目線で解説にまとめています。

リソースのエンドポイントURLの形式と二種類のホスト名の違い

エンドポイントはリソース単位で発行され、https://YOUR-RESOURCE-NAME.openai.azure.com/の形を取ります。Foundryリソースとして作成した場合はhttps://YOUR-RESOURCE-NAME.services.ai.azure.com/形式です。v1 APIのドキュメント（ms.date 2026-05-13）には、base_urlが両形式を受け付けると明記されています。

v1形式で呼び出すときは、このホスト名の末尾にopenai/v1/を足した文字列をそのままbase_urlへ渡します。コード内で連結するとv1responsesのように潰れる事故が起きるため、完成形のURLを環境変数に入れてください。

デプロイ名がmodel引数に入る仕組みと命名で失敗しない規則

Azure OpenAIでは、モデルを使う前に「デプロイ」という単位を作ります。デプロイ名は作成時に自由に決められ、API呼び出しのmodel引数にはこの名前を渡すのが決まりです。公式ドキュメントも、モデル名ではなくデプロイ名を参照する点をOpenAI直APIとの主要な差として挙げています。

公式サンプルはデプロイ名とモデル名を同じ文字列にした例が多く、それが混乱の元です。実務ではgpt-4-1-nano-prodのように用途と環境を含む命名にし、モデル名と一致させないでください。デプロイ名を環境変数に逃がしておけば、モデル更改は設定変更で済みます。

APIキーとEntra IDトークンの二方式と取得場所の違い

資格情報は二系統あります。APIキーはAzureポータルのリソース画面「キーとエンドポイント」で2本発行され、値をコピーして使います。Entra IDトークンは、実行環境のマネージドIDや開発者のサインイン情報からライブラリが取得するため、値を人が持ち回る場面がありません。

見落としやすいのは、キーを閲覧できる権限と推論APIを呼べる権限が別だという点です。権限の対応は後段のキーレス認証の章で表にしました。

リソース作成からモデルデプロイまでの手順と詰まりやすい設定箇所

コードを書く前の準備工程です。ここでの選択がリージョンとクォータを決めてしまうため、後から変えると作り直しになる箇所を先に見ておきます。

Foundryポータルでのリソース作成とリージョン選定の判断軸

リソース作成の入り口はAzureポータルとMicrosoft Foundryポータルの二つで、どちらから作っても同じリソースができます。判断が要るのはリージョンです。使えるモデルとデプロイ種別がリージョンで変わるため、使いたいモデルが決まっているなら、そのモデルが提供されているリージョンから逆算してください。

1. 使うモデルを先に決める
2. 提供リージョンとデプロイ種別を確認する
3. データ所在地の制約と突き合わせる
4. リソースを作成してデプロイへ進む

日本国内にデータを置く要件がある案件では、東日本リージョンで目的のモデルが取れるかが先に効きます。この照合手順はAzure OpenAIのリージョン選定：東日本で使えるモデルをデプロイの種類別に確認するで詳しく扱いました。Responses API自体は、2026年8月6日更新のクイックスタート時点で japaneast を含む34以上のリージョンで提供されています。

デプロイ種別とクォータ上限の確認手順・不足したときの申請経路

デプロイ作成時には種別を選びます。グローバル標準、データゾーン標準、地域標準などがあり、処理を行う地理的範囲と価格が変わります。要件が緩い検証用途ならグローバル標準、データ所在地の制約が厳しいならデータゾーン以下、という順で絞り込んでください。

次に見るのがクォータです。デプロイには1分あたりのトークン数（TPM）が割り当てられ、この値が実効的なスループット上限になります。閲覧にはサブスクリプションスコープの Cognitive Services Usages Reader ロールが要ります。権限が足りないとクォータ画面が空に見えるだけで、エラーは出ません。

不足時はポータルからの増枠申請です。承認まで日単位の時間がかかるため、負荷試験の予定があるなら着手前に申請してください。用途別のモデル選定はAzure OpenAI Serviceのモデル一覧と選び方｜GPT・推論・埋め込み・音声を用途別に整理にまとめています。

APIキーとエンドポイントの取得画面・環境変数へ渡すときの注意点

デプロイが済んだら、リソースの「キーとエンドポイント」からエンドポイントURLとキーを取得します。キーが2本あるのは無停止でのローテーションのためです。片方を使いながらもう片方を再生成し、切り替えてから旧キーを再生成すれば、呼び出しを止めずに更新できます。

環境変数はOPENAI_BASE_URLとOPENAI_API_KEYの2つを設定しておくと、PythonではOpenAI()を引数なしで生成できます。ただし値はシェル履歴やプロセス一覧に残る前提で扱い、共有マシンでのキーの使い回しは避けてください。

Python SDKでの呼び出し実装とv1形式クライアントの初期化手順

Azure OpenAIのPython実装は、専用SDKではなくOpenAI公式のPythonライブラリを使います。v1 APIの登場で、Azure専用クライアントを経由しない書き方が標準になりました。

pip installから最小コードまでの構成と実行確認の進め方

導入はpip install openai azure-identityの一行です。キー認証だけならazure-identityは要りませんが、後からキーレス認証へ移す前提なら最初から入れておくと差分が小さくなります。

最小構成は4要素で足ります。ライブラリのインポート、base_urlとapi_keyを渡したクライアント生成、client.responses.createへのmodelとinputの指定、応答の出力。modelに渡すのはデプロイ名です。ライブラリ側の書き方はOpenAI Python SDKの使い方｜インストールから最新クライアント・Responses APIまでで補足しています。

疎通確認は短い文字列を1回投げれば十分です。応答が返れば、エンドポイント、デプロイ名、資格情報、権限の4点がすべて通ったと分かります。401なら資格情報、404ならデプロイ名、接続不能ならエンドポイント文字列を疑ってください。

Responses APIとChat Completionsの使い分けと引数の差

呼び出し口は2系統あります。v1 APIのドキュメントは、Azure OpenAIのモデルに対してResponses APIを推奨しています。DeepSeekやGrokなど他社提供モデルをFoundry経由で呼ぶ場合には、Chat Completions構文が使えると明記されました。

新規実装ならResponses APIから始めてください。既存資産がChat Completionsで書かれている場合、動作するうちは無理に書き換える必要はありません。移行判断は、会話状態の持ち回りやツール連携が要る時点で行えば足ります。

旧AzureOpenAIクライアントからv1形式へ書き換える手順

2025年8月より前のコードは、AzureOpenAI()にazure_endpointとapi_versionを渡す形です。書き換えは3点だけ。クラスをOpenAI()に変える、azure_endpointをbase_urlへ置き換えて末尾にopenai/v1/を足す、api_versionの行を削る。

v1 GA APIでは日付付きのapi-version指定が不要になりました。旧コードが特定の日付版に固定されていた場合、その版でしか通らないパラメータを使っていないかだけ確認してください。版体系の読み方と、固定と追随のどちらを選ぶかの判断はAzure OpenAIのapi-versionとは？v1 APIへの移行とバージョン固定の判断に切り出しています。

プレビュー機能の扱いも変わりました。v1ではヘッダ指定かパス内のalphaで表現されるため、本番をGAに置いたまま一部機能だけ先行して試せます。

REST APIでの呼び出しとcurlによる疎通確認・ヘッダの指定方法

SDKを入れる前、あるいは権限まわりを切り分けたいときに効くのがRESTでの直接呼び出しです。ヘッダ1行の違いで認証方式が変わるため、どちらの資格情報が通っていないかを最短で特定できます。

api-keyヘッダとAuthorizationヘッダの使い分けと失敗の切り分け

v1 APIのエンドポイントはPOST {endpoint}/openai/v1/responsesです。キー認証ならapi-keyヘッダに、Entra ID認証ならAuthorizationヘッダにBearer付きトークンを載せます。両方を同時に送る必要はありません。

切り分けの順序を決めておくと早いです。キーで通ってトークンで落ちるなら、原因はコードではなくロール割り当てにあります。どちらでも落ちるなら、疑うのはエンドポイント文字列かデプロイ名です。RESTで通った構成をそのままSDKへ写せば、SDK固有の設定ミスも切り分けられます。

レスポンスJSONの構造と本文テキストを取り出す位置の見分け方

Responses APIの応答は入れ子のJSONで返り、生成テキストは出力配列の中に入ります。Pythonならresponse.output_textで取り出せますが、RESTで直接受ける場合は配列をたどる必要があります。v1 APIのドキュメントには、応答オブジェクトが予告なく追加されうるため必要なものだけを解析せよ、という注意書きが添えられました。

応答全体を厳密な型へ写し取る設計はフィールド追加のたびに壊れます。必要なキーだけを取り出し、未知のキーは無視する読み方にしてください。

Entra IDによるキーレス認証への切り替えとRBACロールの割り当て

キー認証は速い代わりに、値が流出したときの影響範囲が広く、失効も手動です。Entra IDに寄せれば、資格情報の管理をAzure側へ預けられます。v1 APIではトークンの自動更新がOpenAIクライアント側で扱えるようになり、切り替えの実装負担が下がりました。

DefaultAzureCredentialとトークンプロバイダの実装差分

Pythonではazure-identityのDefaultAzureCredentialとget_bearer_token_providerを組み合わせ、生成したトークンプロバイダをOpenAI()のapi_key引数へ渡します。文字列ではなく関数を渡す形で、有効期限が来ればライブラリが取り直します。

注意が要るのはスコープの値です。v1 APIのドキュメント（2026-08-16時点）ではhttps://ai.azure.com/.defaultが使われています。旧世代のサンプルにはhttps://cognitiveservices.azure.com/.defaultが残っており、コピー元を間違えるとトークン取得は成功するのに401で弾かれます。検索結果からの貼り付けではなく、参照中の公式ドキュメントの値に揃えてください。

Cognitive Services OpenAI Userロールが必要になる境界線

Entra IDで推論APIを呼ぶには、リソースに対する Cognitive Services OpenAI User ロールが要ります。サブスクリプションのOwnerやContributorでも通りますが、それは継承された強い権限が効いているだけで、最小権限の設計にはなっていません。

表の3つ目 Cognitive Services Contributor には落とし穴があります。キーは見られるのに、Entra IDでの推論呼び出しは公式ドキュメントで不可と明記されています。「管理者だから何でも通る」という前提で権限を配ると、開発者がキー運用から抜け出せません。推論を行う人には OpenAI User を明示的に割り当ててください。

ローカル開発と本番運用で資格情報を切り替えるときの構成の決め方

DefaultAzureCredentialは、実行環境に応じて資格情報の取得元を順に試します。ローカルでは開発者のAzure CLIサインイン、Azure上ではマネージドIDが拾われるため、コードを環境ごとに分岐させずに済みます。

便利な反面、意図しない資格情報を拾って「動いてしまう」原因にもなります。CI環境に開発者の個人アカウントが残っていれば、権限検証は素通りです。本番相当の検証では、使う資格情報を明示的に指定するクラスへ切り替えてください。

OpenAI直APIとの実装差分と移植で書き換えが必要になる箇所

OpenAI直APIで動いているコードをAzureへ移す案件は多く、どこまで書き換えるかの見積りが要ります。v1形式になったことで、書き換え範囲は以前よりかなり狭くなりました。

base_urlとmodel引数の二点だけで動く条件と成り立たない例外

キー認証で、Responses APIまたはChat Completionsを叩いているだけのコードなら、書き換えはbase_urlとmodelの2箇所で済みます。クラス名もメソッド名もレスポンスの扱い方も同じままです。公式ドキュメントが「最小限のコード変更で入れ替えられる」と述べるのはこの範囲を指します。

例外もあります。Azure側にデプロイしていないモデルは、名前を書いても存在しません。埋め込みでは入力配列が最大2,048件、1リクエストの入力トークンが8,191未満という制約もあり、大きなバッチを組んでいたなら分割が要ります。

直API向けコードをそのまま流用すると壊れる引数と回避の手順

引数レベルでは、推論モデル向けのmax_completion_tokensと旧来のmax_tokensの関係が事故になりやすい箇所です。o1系以降の推論モデルではmax_tokensが機能せず、置き換えが要ります。エラーを返さず挙動だけ変わる引数もあるため、移植後は「動いた」で止めず、トークン内訳まで確認してください。

プレビュー段階の機能にも注意が要ります。Azure側ではヘッダやパスでプレビューが表現され、直API側の書き方とは対応しません。見積りでは、GA機能だけで再現できる範囲を先に切り出し、プレビュー依存部分を別タスクへ分けておきます。

キー認証で止める場面とEntra IDへ寄せるべき条件の判断基準

ここは玉虫色にせず条件で言い切ります。「本番はキーレスにすべき」という一般論より、どこで線を引くかの方が実務では効きます。

キー認証のままで問題ない規模と切り替えを見送る条件の実務線引き

キー認証のままでよいのは、開発者が2〜3名以内で、実行環境がローカルと単一の検証用サーバに閉じ、キーの再生成を担当者が即座に行える構成です。この規模ならEntra IDに寄せる工数のほうが上回ります。

逆に、次のいずれかに当たるなら切り替えを見送るべきではありません。実行環境がAzure上のApp ServiceやFunctions、コンテナならマネージドIDが使えるため、キーを持たせる理由がありません。複数チームが同じリソースを共有する場合、キーは誰が持っているかを追えなくなります。監査ログで呼び出し主体を特定する要件があるなら、キー認証では主体が1つに潰れます。

失敗パターン：APIキーをコードへ直書きして共有する構成の危うさ

典型的な失敗は、検証時に書いたキーの直書きがそのまま本番へ流れる形です。リポジトリに入った時点で、権限を持つ全員が呼び出し権を得ます。キーはデプロイ単位に絞れないため、1本漏れれば全デプロイが叩かれます。

回避策はキーをコードに書かないことに尽きます。検証段階は環境変数、Azure上ではマネージドID、外部からの呼び出しが避けられないならKey Vault経由という順で選びます。実装と権限設計をまとめて外部と組むなら、生成AI開発・AI受託開発のような受託の枠で引き受ける形が相談先として現実的です。認証方式の切り替えは後になるほど影響範囲が広がるため、PoCの段階で本番の権限設計まで決めておいてください。

よくある質問

Azure OpenAI APIの導入時に検索されることの多い質問を、公式ドキュメントの記載にもとづいて答えます。

Azure OpenAIのエンドポイントはどこで確認できますか？

Azureポータルで対象のリソースを開き、左メニューの「キーとエンドポイント」に表示されます。Microsoft Foundryポータルのデプロイ画面からも確認できます。表示される値はホスト名までなので、v1形式で呼ぶなら末尾にopenai/v1/を足した文字列をbase_urlへ渡してください。閲覧自体は Cognitive Services OpenAI User でも可能で、キーの閲覧権限とは別扱いです。

api-versionの指定は今でも必要ですか？

v1 GA APIを使う場合は不要です。2025年8月から提供が始まったv1 APIでは、日付付きのapi-versionを毎月更新する必要がなくなりました。日付付きの版を明示した旧来のコードはそのまま動きますが、新規実装でv1形式を選ぶなら指定は省けます。版の体系や固定方針は、Azure OpenAIのapi-versionの記事で扱っています。

Azure OpenAI専用のSDKをインストールする必要はありますか？

Pythonの場合、必要なのはOpenAI公式ライブラリで、pip install openaiで入ります。v1 APIではAzureOpenAI()という専用クラスを経由せず、OpenAI()にbase_urlを渡す形で接続します。Entra ID認証のときだけazure-identityを追加してください。C#、JavaScript、Go、Javaも同様の構成です。

APIキーが2本あるのはなぜですか？どちらを使えばよいですか？

どちらを使っても機能は同じで、2本あるのは無停止でローテーションするためです。KEY1で運用しながらKEY2を再生成し、参照先をKEY2へ切り替えてからKEY1を再生成すれば、呼び出しを止めずに更新できます。定期的な入れ替えを運用に組み込むなら、参照先をコードではなく設定値に逃がす設計が前提です。

コードを書かずに動作確認する方法はありますか？

Microsoft Foundryポータルのプレイグラウンドで、デプロイ済みモデルにブラウザから問い合わせできます。応答が返れば、リソースとデプロイまでは成立していると判断できます。利用は Cognitive Services OpenAI User ロールでも可能なため、キーを配らずに動作確認だけ依頼できるのが利点です。

関連記事

• Azure OpenAI Serviceとは？できること・料金・導入事例まで実務目線で解説：定義と料金体系の確認に
• Azure OpenAIのapi-versionとは？v1 APIへの移行とバージョン固定の判断：版を固定するか追随するかの判断材料
• Azure OpenAIでGPT-5を使う方法｜デプロイ・クォータ・推論パラメータの実装手順：モデル個別の推論パラメータ
• Azure OpenAI Serviceのモデル一覧と選び方｜GPT・推論・埋め込み・音声を用途別に整理：デプロイするモデルの選定に
• OpenAI Python SDKの使い方｜インストールから最新クライアント・Responses APIまで：クライアント側の書き方の補足