新しくなった 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 開発者ポータルの概要