Azure API Management（APIM）の Standard v2／Basic v2 に移行したところ、「カスタムドメインは設定できたのに、開発者ポータルでは既定の *.azure-api.net のまま」「開発者ポータル用のカスタムドメインが追加できない・追加しても消える」といった声が増えています。本記事では、2024〜2025 年の公式情報や実例を踏まえつつ、この v2 特有のカスタムドメイン不具合の整理と、現場で取り得る現実的な対処方法を解説します。
Azure API Management v2 とカスタムドメインの前提
まずは、Standard v2／Basic v2 で「何ができるはずか」を押さえておきます。
APIM v2 ティアの位置づけ
Azure API Management には v1（Classic 系）と v2 ティアが並存しており、v2 としては Basic v2 と Standard v2 が一般提供されています。Basic v2 はチームや小規模プロジェクト向け、Standard v2 は本番利用を想定したティアという位置づけです。
どちらも、ゲートウェイ／開発者ポータルなどのエンドポイントに対してカスタムドメインを設定できる設計になっています。
本来のカスタムドメインの挙動
APIM の「カスタムドメイン」は、主に次のエンドポイントに割り当てます。
- Gateway（API 呼び出し用のエンドポイント）
- Developer portal（開発者ポータル）
- （必要に応じて）Management API など
通常想定される挙動は以下です。
- ゲートウェイ：
https://api.example.com/のような独自ドメインで API を呼び出せる。 - 開発者ポータル：
https://dev.example.com/にアクセスするとポータルが開き、API ドキュメントや「Try it」コンソールのベース URL 表示も、このカスタムドメインに揃う。 - 既定の
<name>.azure-api.netも並存し、必要であれば引き続き利用可能。
ところが v2 ティアでは、この「あるべき挙動」が崩れているケースが報告されています。
APIM Standard/Basic v2 で発生している 2 つの症状
症状の概要
| 症状 | 発生箇所 | 代表的な現象 | 主な影響 |
|---|---|---|---|
| 症状 A | 開発者ポータル | ゲートウェイにカスタムドメインを設定済みでも、API ドキュメント／「Try it」コンソールの表示が *.azure-api.net のまま変わらない。 | 利用者が既定ドメインで実装してしまい、のちの移行やセキュリティ要件への影響が大きい。 |
| 症状 B | Azure Portal（カスタムドメインブレード） | 開発者ポータル用カスタムドメインを追加しても、「サービスを更新中…」の後に一覧から消える／反映されない。 | 開発者ポータル用カスタムドメインが実質使えない。DNS 設定をいくら調整しても成功しない。 |
これらはStandard v2 だけではなく Basic v2 でも再現するという報告があり、v2 スタック共通の問題と考えられています。
公式 Q&A・ドキュメントから読み解く現在地
開発者ポータル用カスタムドメインの実装状況
2024 年 3 月の Microsoft Q&A では、Standard v2 でのカスタムドメイン問題について、Microsoft のモデレーターから次のような回答が出ています。
- 開発者ポータル用カスタムドメイン自体の機能は 既に実装済み。
- ただし、Azure Portal 側の UI がまだ追いついておらず、「開発者ポータル用カスタムドメインを追加する UI」がない／うまく動作しない状態。
- 現時点では ワークアラウンドは提供されていない。
つまり、「バックエンドとしてはサポートしているが、ポータル UI からは設定しにくい（あるいはできない）」という中途半端な状態だった、ということです。
症状 A：開発者ポータルに既定ドメインしか表示されない問題
同じ Q&A スレッドでは、ゲートウェイにカスタムドメインを設定しても開発者ポータルの API ドキュメントに反映されない（既定ドメインのまま）という報告に対し、Microsoft 側が「これはバグであり、ワークアイテムを起票する」とコメントしています。
その後も 2024 年〜2025 年にかけて、
- Classic／Developer ティアでは正しくカスタムドメインが表示されるのに、v2 ティアでは
*.azure-api.netのまま、という差分報告 - Standard v2 だけでなく、Basic v2 でも同じ現象が起きている、という追記
が挙がっており、2025 年初頭時点でも「完全には解消していない」ことがうかがえます。
症状 B：開発者ポータル用カスタムドメインが「消える」問題と証明書制限
同じ Q&A スレッドの中で、Microsoft 側から次のような言及があります。
- v2 ティアには「同一ワイルドカード証明書（＝同一サムプリント）を複数エンドポイントで共用できない」という既知の制限がある。
- 具体的には、
*.example.comの証明書を、ゲートウェイと開発者ポータルの両方に同じサムプリントで割り当てることはできない。 - 開発者ポータル用には、別サムプリントの証明書を使用する必要がある。
この制限に引っかかると、「開発者ポータル用カスタムドメインを追加しても、少し時間が経つと勝手に消える」「サービス更新メッセージの後に反映されない」といった挙動になりやすいと考えられます。
v2 ティアの開発者ポータルには他にも制限あり
v2 ティアの開発者ポータルには、カスタムドメイン以外にも、ビルトインのカスタム HTML ウィジェットやカスタムウィジェットがまだサポートされていないなど、一部機能制限が残っています。
このため、「ポータル側で文言を工夫して回避したい」と思っても、Classic ティアほど自由に HTML を埋め込めない場合があります。この点も「運用での回避策」を考えるうえで、頭に入れておく必要があります。
実務で取り得る 4 つの対処（推奨順）
ここからは、現場で今すぐ取り組める対処を、優先度順に整理します。
対処 1：ゲートウェイと開発者ポータルで証明書を分ける
最優先で検討すべきなのが証明書の分離（サムプリントを分ける）です。
ポイントは次の 2 点です。
- 同じワイルドカード
*.example.comであっても、別発行・別サムプリントの証明書であれば OK。 - あるいは、
api.example.com用とdev.example.com用に、別々の証明書を用意してもよい。
| 用途 | 例 | 証明書 | サムプリント |
|---|---|---|---|
| ゲートウェイ | api.example.com | 証明書 A（例：ワイルドカード *.example.com） | Thumbprint: AAAA... |
| 開発者ポータル | dev.example.com | 証明書 B（同じく *.example.com でも可） | Thumbprint: BBBB...（証明書 A と異なる必要あり） |
おすすめの手順は次の通りです。
- 既存のゲートウェイ用証明書を確認する（Key Vault かローカルアップロードか、サムプリントを控える）。
- 同じ CA から、もう 1 枚ワイルドカード証明書を発行するか、
dev.example.com専用の証明書を発行する。 - APIM の「カスタムドメイン」から、開発者ポータル用エンドポイントに新証明書を割り当てる。
- エラーが出ないか確認したうえで、「サービスを更新中」の表示が消えた後に一覧へ残っているか確認する。
この「証明書分離」によって、症状 B（登録後にドメインが消える）だけでなく、症状 A の解消・安定化にもつながったという報告がいくつか見られます。
対処 2：DNS → ポータル再公開 → キャッシュクリアの「反映ルーティン」を徹底
証明書を分けた上で、次に重要なのが反映ルーティンの徹底です。
DNS 設定のチェックポイント
- 開発者ポータル用の FQDN（例：
dev.example.com）に対し、APIM に指定された CNAME を設定しているか。 - 所有権確認用の TXT レコードが求められている場合、それも正しく設定されているか。
- 一時的に TTL を短くしておくと、切り替え時の待ち時間を短縮できる。
nslookup dev.example.com/dig dev.example.comなどで、期待どおりの CNAME に解決されるか確認する。
開発者ポータルの再公開（Publish）
DNS が行き渡っていそうなタイミングで、開発者ポータルを管理画面から再公開します。
- APIM リソースから「Developer portal」を開き、管理者モードに入る。
- 右上などにある「Publish」ボタンを押して公開処理を実行。
- エラーなく完了したか確認する。
ブラウザキャッシュ／Service Worker のクリア
開発者ポータルは Service Worker を利用しているため、キャッシュが強く効くケースがあります。
- Chrome/Edge なら「サイトのデータを削除」や DevTools から「Unregister service worker」を実行。
- それでも変わらない場合は、シークレットウィンドウや別ブラウザで再確認。
この一連のルーティン（DNS → 再公開 → キャッシュクリア）を踏まないと、「直したつもりなのに直っていない」錯覚に陥りやすいので注意してください。
対処 3：症状 B（カスタムドメインが「消える」）の追加チェック
証明書分離＋反映ルーティンでも症状 B が残る場合は、次の点も確認します。
証明書チェーンと Key Vault 設定
- 証明書チェーンに中間証明書が含まれているか（PFX に中間 CA を含める）。
- Key Vault から参照している場合：
- APIM のマネージド ID に Key Vault の「Certificate User」や「Get/List」権限が付与されているか。
- 仮にバージョン固定している場合、期限切れになっていないか。
Azure Portal 側の状態確認
- 「診断と解決」ブレードに関連するアラート／既知の問題が表示されていないか。
- 一度削除してから、別名（例：
dev2.example.com）で試すと、問題が証明書かドメイン名か切り分けしやすくなります。
それでも改善しない場合はサポートへケース起票
上記を試してもなお、
- カスタムドメインを追加しても数分後に一覧から消える
- 「サービス更新中…」表示のあと、何も変わらない
といった状態が続く場合は、製品側の不具合に巻き込まれている可能性が高いため、Azure サポートへのケース起票を強く推奨します。
その際には、次のような情報を添えると話が早く進みます。
- 対象の APIM ティア（Standard v2 or Basic v2）。
- 症状 A／B のどちらが発生しているか。
- 証明書の配置パターン（ゲートウェイと開発者ポータルで同じサムプリントか、別か）。
- DNS 設定と疎通確認の結果。
- 可能であれば、先述の Microsoft Q&A スレッド（Issues with custom domains in APIM Standard V2）を参照として添付（既知の不具合への紐づけを依頼）。
対処 4：利用者への影響を最小化する運用テクニック
「表示が既定ドメインのまま」という症状 A は、利用者の実装ベース URL を誤らせる点で厄介です。ただし、API 自体はカスタムドメインでも利用可能なため、ドキュメントと運用でリスクを抑えることができます。
ドキュメント上で「正しいベース URL」を徹底明記する
- 開発者ポータル内の Top ページや各 API 説明に「利用ベース URL＝
https://api.example.com」を太字で明記。 - 既定ドメインでのアクセスは非推奨である旨を添える。
v2 ティアでは HTML 任意埋め込みが難しいため、標準のテキストウィジェットを使ってメッセージを配置することになります。
配布用 OpenAPI では servers.url をカスタムドメインに統一
Swagger／OpenAPI を開発者に配布している場合は、servers セクションをカスタムドメインに統一すると、クライアント実装のブレを防げます。
servers:
- url: https://api.example.com
description: 本番用カスタムドメイン
ステージング環境を分けたい場合でも、
servers:
- url: https://api.example.com
description: 本番
- url: https://stg-api.example.com
description: ステージング
といった形で、あくまでカスタムドメインのみを列挙するのがおすすめです。
必要に応じて、*.azure-api.net からのリダイレクトをポリシーで実装
どうしても既定ドメイン（<name>.azure-api.net）での呼び出しが止められない場合、APIM のポリシーでカスタムドメインへ 301／308 リダイレクトする方法もあります。
<inbound>
<base />
<choose>
<when condition="@(context.Request.OriginalUrl.Host.EndsWith(".azure-api.net"))">
<return-response>
<set-status code="308" reason="Permanent Redirect" />
<set-header name="Location" exists-action="override">
<value>@($"https://api.example.com{context.Request.OriginalUrl.PathAndQuery}")</value>
</set-header>
</return-response>
</when>
</choose>
</inbound>
注意点：
- ブラウザベースのツールや「Try it」コンソールは、リダイレクト処理に弱い場合があります。
- CORS 設定にも影響するため、事前にテスト環境で十分に検証すること。
- 必要ならメソッドやパスで条件分岐し、
GETのみリダイレクトするなどの工夫も検討します。
実践例：Standard v2 での最小構成シナリオ
ここでは、よくある構成例を使って、実際の設定フローをイメージしてみます。
前提シナリオ
- APIM ティア：Standard v2
- ゲートウェイ用ドメイン：
api.example.com - 開発者ポータル用ドメイン：
dev.example.com - 証明書：
- 証明書 A：ワイルドカード
*.example.com（ゲートウェイ用） - 証明書 B：同じく
*.example.comだが別発行（開発者ポータル用）
- 証明書 A：ワイルドカード
設定手順の例
- DNS を準備する
api.example.com→ APIM 既定ゲートウェイへの CNAME を設定。dev.example.com→ APIM 開発者ポータル用の CNAME を設定。- TXT レコードが要求されていれば併せて設定。
- 証明書 A/B を Key Vault か APIM にアップロード
- 証明書チェーン（中間証明書を含む）になっているか確認。
- Key Vault のアクセス権限（
Get/List）を APIM のマネージド ID に付与。
- ゲートウェイに証明書 A を割り当てる
- カスタムドメインブレードで
api.example.comを追加し、証明書 A を指定。 - https での疎通（
curlやブラウザ）を確認。
- カスタムドメインブレードで
- 開発者ポータルに証明書 B を割り当てる
- 同じくカスタムドメインブレードで
dev.example.comを追加し、証明書 B を指定。 - 「サービス更新中…」の表示の後も、一覧にエントリが残るか確認。
- 同じくカスタムドメインブレードで
- 開発者ポータルを再公開し、疎通確認
- 管理モードで「Publish」→ 完了後、シークレットウィンドウから
https://dev.example.com/にアクセス。 - API ドキュメントが表示され、ログインや「Try it」が動作するか確認。
- この時点でベース URL 表示が
*.azure-api.netのままでも、実際の API 呼び出し先（レスポンスヘッダなど）を確認し、カスタムドメインでも動作することを確認しておく。
- 管理モードで「Publish」→ 完了後、シークレットウィンドウから
- OpenAPI／運用ドキュメントをカスタムドメインで統一
- 配布用 OpenAPI の
serversをカスタムドメインに揃える。 - 開発者ポータル内の説明文にも、正しいベース URL を明記する。
- 配布用 OpenAPI の
チェックリスト：設定〜運用までの総点検
| 項目 | チェックポイント | OK の目安 |
|---|---|---|
| DNS | CNAME／TXT レコードが正しく設定されているか。 TTL が極端に長くないか。 | nslookup / dig で期待どおりのホスト名に解決する。 |
| 証明書 | 中間証明書を含む完全なチェーンか。 有効期限・SAN（Subject Alternative Name）が正しいか。 | ブラウザからアクセスした際に証明書エラーが出ない。 |
| 証明書の分離 | ゲートウェイと開発者ポータルで、サムプリントの異なる証明書を使用しているか。 | カスタムドメイン一覧に両方のエンドポイントが正常に表示される。 |
| ポータル再公開 | 開発者ポータル管理画面から Publish を実行したか。 | Publish 完了後、最新版のコンテンツが反映されている。 |
| キャッシュ／Service Worker | ブラウザキャッシュ削除、Service Worker の unregister を行ったか。 | 別ブラウザ／シークレットウィンドウで同じ結果が再現する。 |
| ドキュメント | API 説明／OpenAPI にカスタムドメインを明記しているか。 | 利用者が迷わずカスタムドメインで実装できる状態。 |
| サポート | 上記をすべて実施しても解消しない場合、サポートケースを起票したか。 | ケース番号を保持し、既知の不具合に紐づけてもらっている。 |
よくある質問と補足
Q1：Classic／Developer ティアに戻せば解消しますか？
Microsoft Q&A では、「Developer ティアではカスタムドメインが正しく表示されるが、Standard v2 では表示されない」という比較報告があります。
そのため、「旧ティアに戻せば少なくとも症状 A は出にくくなる」可能性はありますが、
- ティア変更はコストや機能（VNet 連携など）に影響する
- 将来的には v2 への統一が進む可能性が高い
といった点から、短期的な回避策以上の意味は持たないことが多いでしょう。まずは本記事で挙げた v2 前提での回避策を検討するのがおすすめです。
Q2：自己ホスト型 Developer Portal にすれば解消しますか？
APIM の開発者ポータルは、自己ホスト（self-host）することもできます。
自己ホスト化すると：
- 独自のフロントエンド実装でベース URL 表記を制御しやすくなる。
- より自由な UI カスタマイズや拡張が可能になる。
一方で、
- ポータルのアップデートやセキュリティ対応を自分たちで維持する必要がある。
- 症状 A の根本原因が「APIM のバックエンド API から返されるホスト名」にある場合、自己ホストでも同様の問題が残る可能性がある。
といったデメリットもあります。本格的に自己ホストへ移行する前に、PoC 環境で「求めるレベルまで問題を回避できるか」を検証してから判断するのが現実的です。
Q3：いつ頃までに完全修正されそうですか？
Microsoft は Q&A で「バグとしてワークアイテムを作成した」「リリースノート（GitHub リポジトリ）でアップデートを確認してほしい」と案内していますが、具体的な修正時期は明示されていません。
また、2024 年〜2025 年にかけて複数の追加コメントで「まだ修正されていない」「Standard v2／Basic v2 ともに再現する」との声が上がっていることから、現場としては当面は「バグが残る前提」で設計・運用するのが現実的と考えられます。
まとめ：APIM v2 のカスタムドメイン不具合と付き合うコツ
Azure API Management Standard v2／Basic v2 のカスタムドメイン周りは、2025 年時点でも「設計どおりとは言い難い」部分が残っています。しかし、ポイントを押さえれば、致命的なトラブルを避けつつ運用していくことは十分可能です。
- まずは証明書の分離：ゲートウェイと開発者ポータルで別サムプリントの証明書を使用する。
- DNS → 再公開 → キャッシュクリアの反映ルーティンを徹底し、「設定ミス」と「製品バグ」を切り分ける。
- 症状 A に対しては、ドキュメントと OpenAPI をカスタムドメインに統一し、既定ドメイン利用を控えるよう明示する。
- 必要に応じて、
*.azure-api.netからカスタムドメインへのリダイレクトや、自己ホスト型ポータルの検討も選択肢に入れる。 - それでも解消しない場合は、Azure サポートへのケース起票を躊躇しない（既知不具合として扱ってもらう）。
APIM v2 はコスト・性能面で魅力的な選択肢である一方、Classic からの移行ではこうした「思わぬ落とし穴」にハマりがちです。本記事の内容が、トラブルシューティングと設計見直しの一助になれば幸いです。
コメント