Azure API Management（APIM）で古い API 製品を見せたくない――そんなとき最初に思い浮かぶのが「Developer Portal で製品を非公開にする」設定です。本記事では、非公開化の正しい意味と実行時の影響、既存のサブスクリプションキーの扱い、運用で起こりがちな落とし穴、そして安全に段階的廃止（サンセット）へ進めるための実践手順までを、現場でそのまま使える粒度で整理します。
APIM における「製品」「開発者ポータル」「ゲートウェイ」の関係
まず用語と責務の切り分けを正しく理解しておくと、非公開化の影響を読み違えません。APIM には大きく 管理プレーン（管理・公開・可視性） と データプレーン（実行・ゲートウェイ） があり、Developer Portal は前者に属する「見せ方」の層、API Gateway は後者に属する「動かす」層です。製品（Product）は API の束ね単位で、購読（Subscription）とポリシー適用の単位でもあります。
| コンポーネント | 主な役割 | 非公開化の影響 |
|---|---|---|
| Developer Portal | 製品・API のカタログ表示、ドキュメント、購読申請 | 非公開にするとカタログから完全に非表示。新規申請不可。 |
| API Gateway（データプレーン） | リクエスト受付、ポリシー適用、サブスクリプション検証 | 非公開の有無に関係なく挙動は不変。キーが有効なら呼び出し可能。 |
| 製品（Product） | API の束ね、購読とポリシーの適用境界 | 非公開にしても定義やポリシーは残る。既存購読は継続。 |
| サブスクリプション（購読） | 開発者に付与されるアクセス資格（キー） | 非公開化では無効化されない。失効・削除・再生成は別操作。 |
「非公開」にした場合の影響まとめ（結論ファースト）
| 項目 | 内容 |
|---|---|
| ポータル表示 | 非公開にすると Developer Portal から完全に消える。新規ユーザーは検索も購読申請も不可。 |
| 実行時挙動 | API Gateway の動作は変わらない。API 本体やポリシーが削除・変更されるわけではない。 |
| 既存キーの扱い | すでにキーを持つ開発者は そのまま呼び出し可能。レート制限やその他ポリシーも従来通り。 |
| 完全停止したい | 利用を止めるには 購読の失効・ブロック・キー再生成・製品削除・API 無効化 といった別操作が必要。 |
すなわち、非公開は「カタログから消す」ためのスイッチであり、「実行を止める」スイッチではありません。ここを取り違えると、止めたつもりの旧製品がバックエンドで呼ばれ続ける、という運用事故につながります。
非公開と「限定公開（グループ制御）」の違い
APIM の可視性には二つのアプローチがあります。ひとつは本記事の主題である「非公開（Not Published）」、もうひとつは製品を公開状態のまま 可視グループ を限定する「限定公開」です。目的に応じて使い分けましょう。
| 方式 | Developer Portal での見え方 | 新規購読 | 既存キー | 主な用途 |
|---|---|---|---|---|
| 非公開（Not Published） | 誰からも見えない | 不可 | そのまま利用可 | 旧版の掲載停止、実験的製品の非公開保管 |
| 限定公開（グループ制御） | 指定グループのみ見える | 指定グループのみ可 | そのまま利用可 | 社内限定、特定パートナー向けローリング公開 |
「外部には隠したいが、社内テスターには見せたい」なら限定公開を。「誰にも見せず、既存だけは動かす」なら非公開を選びます。
既存サブスクリプションキーはなぜ使い続けられるのか
API Gateway は受け取った Ocp-Apim-Subscription-Key（またはベアラトークンとサブスクリプション検証の組み合わせなど）をもとに、該当購読が 有効 かどうかを判定します。製品が非公開かどうかは 購読の有効性とは独立 です。したがって、購読ステータスが有効のままであれば、非公開後も実行は成功します。
逆に言えば、アクセスを止めたいなら 購読側の状態を操作する 必要があります。代表的な選択肢は次章の表をご覧ください。
「止めたいとき」に選ぶ操作と副作用
| 操作 | 何が起こるか | 影響範囲 | ロールバック容易性 | 向いている場面 |
|---|---|---|---|---|
| 購読をブロック（停止） | 該当キーでの呼び出しが失敗する | 特定利用者のみ | 容易（解除で復旧） | 期限切れユーザーや違反時の一時停止 |
| キー再生成（ローテーション） | 旧キーが無効になり新キーが発行される | 該当購読のみ | 中（新キー配布が必要） | 漏洩疑い、段階的切替 |
| 購読削除 | 該当利用者のアクセス資格を破棄 | 特定利用者のみ | 困難（再申請が必要） | 契約終了・強制停止 |
| 製品削除 | 製品配下の購読が無効化 | その製品の全利用者 | 困難（再構築が必要） | 完全廃止が確定している |
| ポリシーで明示ブロック | 対象製品や API の入口で 410/403 を返す | 設定範囲の全利用者 | 容易（ポリシー切替で復旧） | サンセット期限後の段階的遮断 |
「まずは見せない（非公開）」「次に新規の入口を閉じる（申請停止）」「最後に既存を止める（ブロックや削除）」という順番で、影響を可視化しながら進めるのが安全です。
段階的サンセット（安全な廃止）テンプレート
全体像
- 計画：現行利用状況の可視化（呼び出し数、上位コーラー、IP、失敗率、SLA 影響）。
- 非公開化：Developer Portal から旧製品を非公開にし、新規申請を止める。
- 周知：移行先、代替の使い方、期限、連絡先をコミュニケーション。
- 移行支援：SDK・サンプル・ガイド、サンドボックス提供、並走期間の確保。
- 強制力：期限後はポリシーや購読状態で段階的にブロック。
- 撤去：アクセスが無くなったら製品・API を削除（もしくはアーカイブ）。
3 段階のブロック戦略例
| フェーズ | 目標 | 実装例 | 観測指標 |
|---|---|---|---|
| 警告 | 移行を促す | レスポンスに Deprecation/ Sunset ヘッダーを付与 | 警告受領後の移行率、サポート問合せ件数 |
| 制限 | 控えめに抑制 | 時間帯やコーラー単位でレート制限を強化 | 旧製品のピーク呼び出し数の逓減 |
| 遮断 | 廃止を徹底 | ポリシーで 410 Gone を返す／購読をブロック | 旧製品の成功呼び出しゼロ継続日数 |
APIM ポリシー例（期限後に 410 を返す）
<choose>
<when condition="@DateTime.UtcNow >= new DateTime(2025, 12, 31)">
<return-response>
<set-status code="410" reason="Gone" />
<set-header name="Deprecation" exists-action="override">
<value>true</value>
</set-header>
<set-header name="Sunset" exists-action="override">
<value>2025-12-31T00:00:00Z</value>
</set-header>
<set-body>This API version is retired. Please migrate to the new product.</set-body>
</return-response>
</when>
</choose>この方式なら製品や購読を即時削除せずに、戻せる安全弁を維持したまま移行を進められます。
Developer Portal の非公開化手順（運用のベストプラクティス）
ポータル UI での基本操作
- Azure ポータルで対象の API Management インスタンスを開く。
- 左ペインの 製品（Products） から対象製品を選ぶ。
- 公開（Published） のチェックを外す、または状態を非公開に切り替える。
- 保存して反映。数分の伝播遅延が起きる場合があるため監視グラフで確認。
影響確認のポイント
- Developer Portal のカタログから該当製品が消えているか。
- ポータルの直接 URL を踏んでも製品ページが表示されないか。
- 既存キーでの実行が従来どおり成功するか（意図どおり）。
- 新規購読申請ができないことを実際にテストユーザーで確認。
周知とコミュニケーションの実務
非公開は内部的なスイッチにすぎません。利用者にとって重要なのは「いつまで」「どこへ」「どう移るか」です。以下のひな型をベースに案内文面を準備しましょう。
通知テンプレート（社外開発者向け）
件名: 【重要】API v1 非公開と移行のご案内
平素より当社 API をご利用いただきありがとうございます。
旧製品 "Sample API v1" は開発者ポータル上で非公開となりました。既存のサブスクリプションキーは引き続きご利用いただけますが、
2025/12/31 をもって本製品の提供を終了いたします。以降は v2 への移行が必要です。
移行ガイド、SDK、サンプルコードは別途お送りします。ご不明点は本メール宛にご連絡ください。よくある質問（FAQ）に入れるべき項目
- 非公開後も既存キーは使えるのか（使える／いつまでか）。
- 移行先の製品名・エンドポイント・変更点（認証、スキーマ、レート）。
- サポート窓口と SLA（移行期間中の優先度設定）。
- エラーになった場合の代表的な原因（ブロック、期限切れ、ポリシー）。
バージョニングと並走運用のコツ
非公開は「もうカタログに載せない」だけなので、v1 と v2 の並走期間に向いています。以下の工夫で移行摩擦を下げられます。
- 命名規約：
Sample API v1/Sample API v2のように製品名に系譜を持たせる。 - 共通スキーマ：モデルは極力後方互換にし、Breaking Change は別リソース名やバージョンで分離。
- 非機能の差異を明示：レートや SLA、セキュリティ方式の差を表にして一目で比較できるように。
- SDK 配布：言語別に v2 を先行提供し、利用者の実装コストを最小化。
| 項目 | v1（旧） | v2（新） | 差分 |
|---|---|---|---|
| 認証 | サブスクリプションキー | OAuth2 + サブスクリプション | アクセストークン取得が追加 |
| レート制限 | 1,000 calls / 日 | 10,000 calls / 日 | 拡張 |
| エンドポイント | /api/v1/ | /api/v2/ | パスが変更 |
| サポート | 2025/12/31 まで | 通常サポート | v1 はサンセット |
観測とアラート：非公開後にやるべき 5 つのモニタリング
- 旧製品の成功呼び出し数：減少トレンドを可視化し、横ばいなら周知不足を疑う。
- v2 の採用曲線：移行率（ユニークキー数）を追い、ボトルネックを特定。
- 410/403 の失敗比率：ポリシー遮断の効き具合とやり過ぎを検出。
- 上位コーラー：依存度の高いクライアントに個別フォロー。
- バックエンド負荷：旧 v1 が裏でリソースを食っていないか確認。
これらをダッシュボード化して「非公開化の効果」を可視化できると、関係者への説明がスムーズになります。
よくある誤解と落とし穴
- 非公開＝呼び出し不能：誤り。既存キーは有効のままです。
- 非公開にすれば課金も止まる：誤り。実行が続けばメーターは回ります。
- ポータルに無いから安全：誤り。URL とキーを持つクライアントは呼び出せます。
- 製品を消せば全て片付く：乱暴。段階的な周知と移行期間が無いと業務影響大。
- キー再生成だけで十分：配布と切替の手間、ダウンタイム、失敗時の復旧を見積もるべき。
チェックリスト（そのまま使える）
非公開化の前
- 旧製品の利用実態を把握（呼び出し数、トップ 20 コーラー、ピーク時刻）。
- 移行先の準備（製品・ポリシー・ドキュメント・SDK）。
- 社内外の連絡リスト整備（メール、Slack/Teams、運用窓口）。
非公開化の直後
- ポータルからの消失を確認（ゲスト・開発者両方の視点で検証）。
- テストシナリオで既存キーの実行が継続することを確認。
- ダッシュボードに「旧製品の利用トレンド」カードを追加。
サンセット期限の前後
- 期限 30/14/7/1 日前のリマインダー送信。
- 期限当日にポリシー切替（410 返却）と購読ブロックを段階導入。
- ゼロアクセスが続いたら製品・API を撤去しタグ/コストも整理。
トラブルシューティング
| 症状 | 原因候補 | 対策 |
|---|---|---|
| 非公開にしたのにポータルに残って見える | キャッシュ・CDN の伝播遅延、別テナント/ロールで閲覧 | 数分待って再確認、シークレットウィンドウで検証、権限を切り替えて確認 |
| 新規ユーザーが申請できてしまう | 限定公開設定でゲスト/開発者グループが残っている | グループの可視化を見直すか、非公開（Not Published）に切り替える |
| 既存アプリが突然 403/401 になる | 購読ブロック、キー再生成、ポリシー追加、IP 制限 | 最近の運用変更を棚卸し、購読状態とポリシーの差分を確認 |
| 旧製品がバックエンドに負荷を与え続ける | 非公開止まりで実行は継続 | 期限を定めて 410 返却＋購読ブロック、利用者と移行計画を再確認 |
ケーススタディ：v1 を非公開→ v2 に移すリアルな流れ
- 現状把握：v1 のユニーク購読 120、日次 80k 呼び出し。上位 10 クライアントで 70% を占有。
- 非公開化：v1 を非公開に。v2 を公開し「開発者」グループへ可視化。新規は v2 のみ申請可能に。
- 周知：上位 10 社に個別ブリーフィング。残りには一斉通知＋ FAQ。
- 移行支援：ライブラリ、コードモッド、Postman コレクションを配布。
- 強制力：60 日後に昼間のみ v1 のレート制限を強化、90 日後に 410 返却へ切替。
- 撤去：アクセスゼロ 14 日継続後に製品削除、API 排除、コストタグを更新。
この運用で、業務停止や大規模なサポート事故を起こさず、静かに移行を完了できます。
セキュリティ・ガバナンスの観点
- 職責分離：製品公開権限とポリシー編集権限を分離し、レビューを必須化。
- 監査証跡：非公開化や購読ブロックの操作ログを保全。
- 自動化：IaC（テンプレート）で製品状態とグループ可視性をコード化。人手のミスを防止。
- キー管理：ローテーション手順を標準化。一次/二次キーの切替順序とタイムラインを定義。
要点のふり返り
- 非公開は 「ポータルから消すだけ」。ゲートウェイの実行は止まらない。
- 既存の購読キーは そのまま有効。止めたいときは購読やポリシーを操作する。
- 安全な廃止は 非公開 → 周知 → 制限 → 遮断 → 撤去 の段階戦略が有効。
- モニタリングと個別フォローで 移行の摩擦を最小化 できる。
以上を押さえておけば、「古い製品を見えなくする」と「古い製品を止める」を混同せず、計画的に API のライフサイクルを前へ進められます。
付録：運用ヒントのクイックリファレンス
- はじめに非公開：新規流入を止める。
- 移行先の露出を最大化：v2 のドキュメントを先に整える。
- メトリクス監視：非公開後もしばらくはアクセスが続くのが普通。焦らずプランどおり進める。
- 期限を宣言：ゴールが無い移行は永遠に終わらない。日付を決め、守る。
- 最後は自動で止める：期限後はポリシーと購読ブロックで確実に遮断。
まとめ
APIM の「非公開」は、Developer Portal の可視性だけを操作する軽量なスイッチです。運用上の副作用は小さく、既存ユーザーの体験を崩さずに掲載停止できるため、段階的サンセットの出発点として最適です。ただし、完全停止は別工程。購読やポリシーを組み合わせ、メトリクスで効果を追い、関係者に丁寧に知らせる――この 3 点を守れば、API のバージョン更改やプラットフォーム移行も静かに成功へ導けます。
コメント