![[アップデート] Amazon API Gateway で作成した API の利用者向けポータルを作れる「デベロッパーポータル機能」がリリースされました](https://images.ctfassets.net/ct0aopd36mqt/wp-thumbnail-534dfb127dffcb687abcf4cdbc1124bf/e7197458a92f26395c42c51a281e72f2/amazon-api-gateway?w=3840&fm=webp)
[アップデート] Amazon API Gateway で作成した API の利用者向けポータルを作れる「デベロッパーポータル機能」がリリースされました
いわさです。
Amazon API Gateway を使うと独自で作成したバックエンド API の提供や外部 API のプロキシ、あるいはマイクロサービスアーキテクチャの API ゲートウェイパターンにおけるエントリポイントとして利用することができます。
通常 API を管理する際には API 利用者向けにリファレンスとなるポータルサイトを提供することが多いのですが、API Gateway は Swagger をサポートしているのでそれを利用したポータルサイトを構築する方法などがありました。また、AWS からもその構築に利用できる「Amazon API Gateway Serverless Developer Portal」というオープンソースのソリューションも提供していました。
これまではこのように独自で構築する必要があったのですが、先日のアップデートで Amazon API Gateway の組み込み機能としてデベロッパーポータル機能が提供されるようになりました。
Azure API Management などでは開発ポータル機能があって良いなぁと思っていたので個人的に待望だった機能です。
今回こちらの機能を使ってみましたので紹介します。
デプロイや編集は比較的簡単ですが、利用料金が発生する機能になります。
マネジメントコンソールの変更点
今回のアップデートで次のように API Gateway コンソールにデベロッパーポータルのメニューが追加されていました。東京リージョンです。
アクセスしてみます。
こんな感じでデベロッパーポータルの仕組みが説明されつつ、新リソースであるポータルとポータル製品を管理する形になっています。
新しくポータル製品とポータルの概念が登場しますのでそれぞれ使いながら理解していきましょう。
デベロッパーポータルの利用にあたっては先にポータル製品を作成しておく必要があります。
ポータル製品を作成してみる
ポータル製品やデベロッパーポータルで共有したい API プロダクトを指すもので、つまり API Gateway で作成した API リソースを示します。
作成済みの API を「ポータル製品」として登録します。
ポータル製品の登録画面から新規作成を行います。
はじめにポータル製品の名前と説明を入力します。
続いて、対象の API エンドポイントを選択します。
ここで最初の制限事項になりますが、まずこのデベロッパーポータルで管理できる対象は「REST API」のみになります。REST API はパブリックもプライベートもいけますが、プライベートの場合は後述の「お試し機能」は使えません。
また、このデベロッパーポータル機能はリージョナルサービスとなりまして、ポータル製品で選択できるのは同一リージョンの REST API のみとなります。
単一の API のみではなく、複数の API リソースとエンドポイントから選択ができるみたいです。これは良い。
選択後にそのまま作成しました。
作成されたポータル製品のページを確認できます。ポータル製品でどの API の情報をどのように表示するのかページのコンテンツまで管理する感じです。デベロッパーポータルはポータル製品が9割くらいメインです。
ドキュメントにはドキュメンテーションページと、API リファレンスページがあります。
初期段階ではドラフト版になっていますが、後ほどちょっと更新しますのでここでは一旦無視しましょう。
ドキュメンテーションページは製品概要を説明するページになってまして、Markdown形式で自由に編集できます。
API リファレンスは各 API エンドポイントの中身を示すページになります。メインの部分。
デフォルトでは関連付けた REST API リソースから情報を取得してくれています。
こちらは編集ができます。
デフォルトは API Gateway のドキュメントソースが使われるのですが、上書きも可能です。
また、「お試し機能」を有効化するとポータル上で API をお試し実行できる機能を追加できます。
これで良いのかわかりませんが、一旦ポータル製品を作成出来ました。
ポータルを作成してみる
つづいでポータルを作成してみましょう。
ポータル製品でコンテンツを作成・管理し、ポータルはデプロイとホスティングを担っている感じです。
まず作成してみましょ０う。
はじめにポータルの定義を入力します。名前と説明です。
認証方法とドメイン、オプションで RUM も設定できます。RUM はどのページがどれだけ使われているのかあとから確認できる感じですかね。
認証方法はデフォルトは不特定多数がアクセス可能なパブリックなものになっています。
こちらはCognito ユーザープールを選択することで認証付きのポータルとすることが出来ます。
またドメインはデフォルトでは AWS によって払い出されますが、カスタムドメインを使うことも可能です。
HTTPS が必要になるので証明書が別途必要で、ACM選択する形になります。
今回は RUM は無視して次のステップに進みましょう。
ここでポータル製品の選択が必須になります。そのためポータル定義前に事前にポータル製品の準備が必要というわけです。
ポータル機能ではデザインテーマについてはちょっとカスタマイズすることが出来ます。
コンテンツはポータル製品で、ブランドテーマくらいであればポータルで管理する感じですね。
以上で一旦ポータルのリソースが作成できます。
ポータルをプレビューする
ポータルが作成できたので使ってみたいところです。
まず、デフォルトではポータルはすぐに公開されていないです、非公開状態です。
ここから公開あるいはプレビューなどを行っていきます。
まずはプレビューを行いたいのですが、「ポータルプレビューを生成」を押すことでプレビューサイトが生成されます。
バナーによると数分かかるとのことでしたが、今回は1分くらいで生成されましたね。
ボタンからアクセスしてみるとプレビュー画面が表示されました。
この時点ではまだパブリックに公開はされていない状態です。
公開前の確認くらいに使いましょう。
ポータルを公開する
続いてポータルを公開してみます。
ポータル画面の「ポータルを公開」ボタンからデプロイします。
こちらは公開の確認画面です。
オプションで変更の説明を入力できるのですが、ポータル上のどこで確認できるのかはわかりませんでした。
ボタンを押すとデプロイが開始されます。こちらも少し時間がかかります。
今回は1~2分で公開されたました。
カスタムドメインを設定していないので、デフォルトドメイン名からアクセスしてみましょう。
おお、これがデベロッパーポータルか。最低限の入力で作ったデフォルトですし API に情報がなので味気ない感じです。
また、デフォルトだとポータル製品で選択した REST API について何も表示されていないことにここで気が付きました。
コンテンツの更新
ポータル製品からコンテンツを更新してみましょう。
各 API リファレンスページですが、デフォルトではドラフト状態になっているので何も表示されないみたいですね。
管理ボタンから編集ができます。
セクションを追加し、そこにドラフトページを追加することで公開することができます。
まずは「新しいセクションを追加」ボタンからセクションを追加します。
適当なセクション名をつけて、ドラフトページから含めたいコンテンツをドラッグ＆ドロップでぐぐっともっていきましょう。
この状態になれば OK です。
変更を保存します。
このポータル製品の更新ですが、更新されたあとはポータル側で再公開が必要です。
ポータルを公開ボタンからデプロイしなおしましょう。
ポータルにアクセスしてみると、コンテンツが反映されていることを確認しました。
よくある開発者向けの API ポータル画面ですね。コンテンツを充実させていけばもう少しそれっぽくなりそう。
料金
この機能良いなぁと思っていたのですが、有料になるのでその点を認識しておきましょう。
東京リージョンの場合ポータルは月額147ドル、さらにポータル製品ごとに月額14.70ドルかかります。
しまった、先に確認しておければよかった。
ポータルとポータル製品を月途中に削除した際に日割りになるのかどうかなど、削除してみましたので確認できたらこちらに追記したいと思います。
さいごに
本日は Amazon API Gateway で作成した API の利用者向けポータルを作れる「デベロッパーポータル機能」がリリースされたので使ってみました。
独自で Swagger を使ってホスティングやデプロイしていた方は検討の余地ありではないでしょうか。
料金がどうかなって感じですかね。内部用のデベロッパーポータルとしては割高な感じがするので、SaaS などでしっかりと API ポータルとして公開する時に使う感じでしょうか。
