Azure API Managementの開発者ポータル

このエントリは2020/07/10現在の情報に基づいています。将来の機能追加や変更に伴い、記載内容との乖離が発生する可能性があります。

Azure API Management (以下、APIM) の開発者ポータルが新しくなった(旧開発者ポータルはセキュリティフィックスの提供のみ継続し、新規機能の追加はない)。

開発者ポータルについて備忘録がてらまとめておく。

利用できるTier

Premium、Standard、Basic、Developer

どこにホストできる?

デフォルトはAPIMインスタンス(<インスタンス名>.developer.azure-api.net)
セルフホストも可能。その場合は任意の場所(APIMインスタンスに対して接続し通信が可能な場所)に配置可

カスタマイズできる?

UIの配置変更やイメージの置き換えだけでなく、セルフホストの場合はソースコードレベルでのカスタマイズが可能

ポータルのアーキテクチャの概念 / Portal architectural concepts
https://docs.microsoft.com/azure/api-management/api-management-howto-developer-portal#portal-architectural-concepts
GitHub repository
https://github.com/Azure/api-management-developer-portal

旧開発者ポータルにあって、新開発者ポータルでなくなったもの

Applications (アプリケーション)と Issues(問題)。移行先もないので、別途カスタム開発が必要。

旧開発者ポータルからの移行

移行手段が用意されていないため、手作業で移行するしかない。

https://docs.microsoft.com/azure/api-management/api-management-howto-developer-portal#how-can-i-migrate-from-the-old-developer-portal-to-the-developer-portal

プレビュー版からの移行

一般公開の発表後にポータルをプロビジョニングした場合は、新しい既定のコンテンツに変わっており、ユーザー側での操作は不要。
https://docs.microsoft.com/azure/api-management/api-management-howto-developer-portal#preview-to-ga

その他の場合は以下の手順を参考に。

a) マネージドの場合

[操作] メニュー セクションの [コンテンツのリセット] をクリックして、ポータルのコンテンツをリセットすれば、ポータルのすべてのコンテンツが削除され、新しい既定のコンテンツがプロビジョニングされ、ポータルのエンジンは、APIM サービスで自動的に更新される。

b. セルフホストの場合

GitHub リポジトリの scripts/cleanup.bat と scripts/generate.bat を使用して、既存のコンテンツを削除し、新しいコンテンツをプロビジョニングする(ポータルのコードを GitHub リポジトリから最新リリースにアップグレードしておくこと)。

その他(ポータルのコンテンツをリセットしたくない場合)

既存のウィジェットは、最新バージョンに自動的に更新されているため、新たに利用可能になったウィジェットをページ全体で使用するのが一つの選択肢。

ARMテンプレートでのデプロイは可能?

できない。サポートしていない。

APIM DevOpsリソースキットと互換性はある?

ない。

開発者ポータルのデプロイの自動化

APIでコンテンツを取得できるので、テスト環境から運用環境など、環境間でのポータル コンテンツの移行を自動化するために利用可能。

開発者ポータルのコンテンツアクセスのためのAPIの情報
https://github.com/Azure/api-management-developer-portal/wiki
サービス間で開発者ポータルを移行する際の手引き
https://github.com/Azure/api-management-developer-portal/wiki/Migrate-portal-between-services

ポータルの再発行が必要な状況

何か開発者ポータルに対する設定変更をした場合には再発行が必要、と思ったほうがよい。以下はその例。

  1. カスタムの APIMドメインを割り当て、変更を有効にする場合
  2. (AAD、AAD B2C などの) ID プロバイダーを構成した後、変更を有効にする場合
  3. 委任を設定した後、変更を有効にする場合

開発者ポータルからのAPIテスト呼び出し時のCORSエラー

対話型コンソールは、ブラウザーがクライアントとしてAPIリクエストを発行するため、回避するには2方法ある。

  1. 開発者ポータルの設定でグローバルレベルでCORSポリシーを有効化する
    以下のスクリーンショットでは黄色でマークした箇所をクリック。
  2. APIに対し手作業でCORS ポリシーを追加、有効化する
    以下のスクリーンショットでは朱色でマークした箇所をクリックし、出力されるCORSポリシーの設定を各APIに設定する

https://docs.microsoft.com/azure/api-management/api-management-howto-developer-portal#im-getting-a-cors-error-when-using-the-interactive-console

注意

APIキーが必要なAPIでは、Preflight要求時にもAPIキーが必要だが、対話型コンソールではAPIキーはHTTP Headerではなく、Query parameterとしてのみ渡すことができる(換言すると、HTTP HeaderでAPIキーを期待しているAPIは対話型コンソールからはテストできない)。

開発者アカウントの承認に利用可能なIDプロバイダー

開発者アカウントを承認するために、APIM独自のユーザーストアだけでなく、IDプロバイダーを利用できる。注意点は、2020/07/10現在、ドキュメントには以下のような記述があるが、スクリーンショットで比較するとわかる通り、日本語UIの実際とは違うので注意が必要。【ユーザー】も2個あるので、中ほどのユーザーを選択する必要がある。

[開発者ポータル] で [ID] を選択します。
一番上にある [+追加] を選択します。
[ID プロバイダーの追加] ウィンドウが右側に表示されます。

Azure AD を使用して開発者アカウントを承認する / Authorize developer accounts by using Azure AD
https://docs.microsoft.com/azure/api-management/api-management-howto-aad#authorize-developer-accounts-by-using-azure-ad

追加できるIDプロバイダーは以下の通り(複数のプロバイダーの追加が可能)。

既存のWebサイトを開発者ポータルの認証認可に使いたい場合

委任(delegate)を使うことで実現可能な場合がある(個人的には、IDプロバイダーにまとめるべきことを推奨するが…)。

ユーザーの登録と成果物のサブスクリプションを委任する方法
How to delegate user registration and product subscription
https://docs.microsoft.com/azure/api-management/api-management-howto-setup-delegation

対話型の開発者コンソールでの OAuth による認証

2020/07/10現在、ドキュメント上は

OAuth 2.0 認証は、新しい開発者ポータルの対話型コンソールではまだ使用できません。(OAuth 2.0 authorization is not yet available in the interactive console of the new developer portal.)

Azure API Management の OAuth 2.0 を使用して開発者アカウントを認証する方法 / How to authorize developer accounts using OAuth 2.0 in Azure API Management
https://docs.microsoft.com/azure/api-management/api-management-howto-oauth2

と記載があるが、開発者ポータル2.4.0のリリースノートを見ると対応済みとあるので、しばらくすると更新されるはず。
https://github.com/Azure/api-management-developer-portal/releases/tag/2.4.0

なお、OAuth 2.0対応の手順は以下に記載がある。

Azure API Management の OAuth 2.0 を使用して開発者アカウントを認証する方法
How to authorize developer accounts using OAuth 2.0 in Azure API Management
https://docs.microsoft.com/azure/api-management/api-management-howto-oauth2

コメントを残す

以下に詳細を記入するか、アイコンをクリックしてログインしてください。

WordPress.com ロゴ

WordPress.com アカウントを使ってコメントしています。 ログアウト /  変更 )

Google フォト

Google アカウントを使ってコメントしています。 ログアウト /  変更 )

Twitter 画像

Twitter アカウントを使ってコメントしています。 ログアウト /  変更 )

Facebook の写真

Facebook アカウントを使ってコメントしています。 ログアウト /  変更 )

%s と連携中