新しくなった APIM 開発者ポータル を触ってみる
はじめに
Azure API Management（APIM） は、APIを包括的に管理できるサービスです。
管理者 はAPI Management を使用して、APIを登録し、公開/非公開を切り替えたり、ポリシーで利用制限をかけたり、製品という単位でグルーピングしたり・・・など、API運用に必要な機能を利用でき、
開発者 は、API Management 経由でAPIを利用することで開発を進めていきます。 開発者ポータル と呼ばれる API Management の機能の一つを利用することで、自分が利用できるAPI仕様を確認したり、実際にポータルから叩いてみることができます。
今回は、色々と新しくアップデートされて久しい 開発者ポータル を触ってみた内容を書いてみたいと思います。
準備
- API Management（価格レベル：開発者(Developer)以上）を作成します
- デプロイ完了まで 45分程度 かかります
- 価格レベルが「消費」だと、開発者ポータルが利用できません
- 本家の説明では他にストレージアカウントも必要となりますが、今回はそこまで踏み込まずにやるため、スキップします
- 作成したリソースにアクセスし Portal overview メニューを選択します
- 以下 Developer portal, Developer portal (legacy) ボタンをクリックします
今までの開発者ポータル（legacy）
URL
https://{APIMリソース名}. portal .azure-api.net
公開方法
- すでに公開済みのため、直接URLへアクセスすれば閲覧できます
管理方法
動的ページ
開発者ポータルで 動的ページ を編集できます（言語：Liquid template language）
静的ページ
発行者ポータルで 静的ページ を編集できます（HTMLなど）
その他、発行者ポータルでは、利用する画像などのメディア管理ができたりします
新しい開発者ポータル
URL
https://{APIMリソース名}. developer .azure-api.net
公開方法
- 未公開状態で別ブラウザ（or プライベートブラウジング）でアクセスすると、以下のような画面が表示される
- 公開するには Publish ボタンを押す（公開まで数分かかる）
- 開発者ポータルからAPIを試す（
Try itする）場合 Enable CORS ボタンを押し、CORSを有効にしなければならない
APIの実際のエンドポイントのドメインと、開発者ポータルのドメインとで異なるため設定が必要となる（以前は自動で許可されていた？）
管理方法
- 基本はWeb画面上でそのままページの編集ができます
マネージド（Webページ上で視覚的にページエディット）
- コードを触らずに、UI上だけで編集を完結できます。
- 気の利いた CMS などでよく見かける感じのページエディタでしょうか。
セルフホステッド
- コードをがっつり弄り倒して細かい制御等もできるようにします。
- HTML, TypeScript, SCSS, NodeJS(npm) の知識が最低限必要となります
- ソースコード自体はオープンソースで公開されているので、以下の手順で開発をします
- Github – Azure / api-management-developer-portal からソースコードをクローン
- 中身はこんな感じの、なかなかボリュームのあるプロジェクトとなっています
npm iを実行しモジュールをインストールしますsrc/config.design.jsonやsrc/config.publish.jsonの中身を書き換えます- 必要となる情報は Azure ポータルから API Management の 管理API メニューから発行します
- 最低限、以下書き換えられていれば、ページは最低限表示されます（ローカルで簡単な動作確認くらいはできるはず・・・）
npm startを実行するとlocalhost:8080がブラウザで開かれます（ローカル開発時に利用。コード編集で自動的に再読み込みされます）- 実際のAPI Management インスタンス上に公開する場合は
npm run publishを実行します
- Github – Azure / api-management-developer-portal からソースコードをクローン
ちょこっとローカルでいじってみる
src/components/apis/list-of-apis/ko/listOfApis.htmlをエディタで開きます- 行頭に以下を追加します
<p style="position: absolute; opacity: .6; font-size: 5em; background: #000; color: #fff; transform: rotate(45deg); z-index: 1000;"> コードを編集しました </p> - 自動再読み込みされるのでブラウザを確認します（ローカルでは編集できました！）
セルフホステッドの公開（手順の案内）
- 今回は公開までは行いません（トライしたものの、ビルドエラーとなったため、いつかリベンジします。。）
- ここまでの流れ含む、公開にいたる手順は、以下のページで公開されています（上記手順でスキップした点もあるので、通して確認しておくと良いかと）
感想・まとめ
- デフォルトのデザインが洗練され、そのままでも十分使いやすいという印象を受けました
- オペレーションを切り替える際にページ読み込みが走らない（非同期通信ですっと切り替わる）など、細かい操作性なども改良されていました
- マネージド・セルフホステッド
- よほど特殊な理由がない限り マネージド一択 だと痛感しました。。。
- 既存のソースコード・構成の理解から始まり、 API Management 以外の PaaS も駆使していかないとならないのはコスト高いです。。
- 一般的な業務で使う分であれば、マネージドでも十分にカスタムして使うこともできます
- 詳細は割愛しましたが、フォントや色なども変えたりできますので
- 基本的にできることは以前の開発者ポータルとは変わりません
- ただし、以下の機能については廃止されているので要注意です
- Issues （管理者⇔開発者 間で 問題報告の簡単なやり取りができる）
- Application （APIを使って作ったWebアプリなどのギャラリー）
- Azure API Management 開発者ポータルの概要