API Center ポータルをセルフホストする

[アーティクル]
05/06/2024

この記事では、API Center ポータルを紹介します。これは、開発者や組織内の他の利害関係者が API センターで API を検出するために使用できる Web サイトです。 API Center ポータルのスターターリポジトリからポータルの参照実装をデプロイします。

ユーザーのサインイン後の API Center ポータルのスクリーンショット。

API Center ポータルについて

API Center ポータルは、API センターに API インベントリを表示するために構築およびホストできる Web サイトです。ポータルを使用すると、組織内の開発者やその他の利害関係者が API を検出し、API の詳細を表示できます。

API Center ポータルのスターターリポジトリのコードを使用して、ポータルの参照実装をビルドしてデプロイできます。ポータルでは、Azure API Center データプレーン API を使用して API センターからデータを取得します。 API 情報へのユーザーアクセスは、Azure ロールベースのアクセス制御に基づいています。

API Center ポータルのリファレンス実装では、次の機能が提供されます。

GitHub Actions を使用してカスタマーマネージド API ポータルを発行および保守するためのフレームワーク
顧客がニーズに合わせて変更または拡張できるポータルプラットフォーム
Azure Static Web Apps などのサービスへのデプロイなど、さまざまなインフラストラクチャでホストできる柔軟性。

前提条件

Azure サブスクリプション内の API センター。まだ作成していない場合は、「クイックスタート: API センターを作成する」を参照してください。
Azure サブスクリプションに関連付けられている Microsoft Entra テナントでアプリ登録を作成するためのアクセス許可と、API センター内のデータへのアクセス権を付与するためのアクセス許可。
ポータルをビルドしてデプロイするには、GitHub アカウントと、ローカルコンピューターに次のツールがインストールされている必要があります。
- Node.js と npm
- Vite パッケージ

Microsoft Entra アプリ登録を作成する

まず、Microsoft Entra ID テナントでアプリ登録を構成します。このアプリ登録により、API センターポータルは、サインインユーザーの代わりに API センターのデータにアクセスできるようになります。

Azure portal で、[Microsoft Entra ID]>[アプリの登録] の順に移動します。
[+ 新規登録] を選択します。
[アプリケーションを登録] ページで、次のように値を設定します。
- [名前] を api-center-portal などのわかりやすい名前に設定します。
- [サポートされているアカウントの種類] で、[この組織ディレクトリに含まれるアカウント (シングルテナント)] を選択します。
- [リダイレクト URI] で、[シングルページアプリケーション (SPA)] を選択し、URI を設定します。
  - ローカルテストの場合は、URI を http://localhost:5173 に設定します。
  - 運用環境では、URI を API Center ポータルのデプロイの URI に設定します。
- 登録を選択します。
[概要] ページのアプリケーション (クライアント) ID とディレクトリ (テナント) ID をコピーします。これらの値は、ポータルをビルドするときに設定します。
[API のアクセス許可] ページで、[+ アクセス許可の追加] を選択します。
1. [API のアクセス許可の要求] ページで、[所属する組織で使用している API] タブを選択します。[Azure API センター] を検索して選択します。また、アプリケーション ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573 を検索して選択することもできます。
2. [アクセス許可の要求] ページで、[user_impersonation] を選択します。
3. アクセス許可の追加 を選択します。
Azure API センターのアクセス許可は、[構成されたアクセス許可] に表示されます。

ローカル環境を構成する

API Center ポータルをローカルでビルドしてテストするには、次の手順に従います。

API Center ポータルのスターターリポジトリをローカルコンピューターに複製します。
```
git clone https://github.com/Azure/APICenter-Portal-Starter.git
```
APICenter-Portal-Starter ディレクトリに変更します。
```
cd APICenter-Portal-Starter
```
main ブランチをチェックアウトします。
```
git checkout main
```
サービスを構成するには、サービスを指すように public/config.json ファイルを編集します。ファイル内の値を次のように更新します。
- <service name> と <region> を、API センターの名前とそれのデプロイ先のリージョンに置き換えます
- <client ID> と <tenant ID> を、前のセクションで作成したアプリ登録のアプリケーション (クライアント) ID とディレクトリ (テナント) ID に置き換えます。
- title の値を、ポータルに表示する名前に更新します。
```
{
  "dataApiHostName": "<service name>.data.<region>.azure-apicenter.ms/workspaces/default",
  "title": "API portal",
  "authentication": {
      "clientId": "<client ID>",
      "tenantId": "<tenant ID>",
      "scopes": ["https://azure-apicenter.net/user_impersonation"],
      "authority": "https://login.microsoftonline.com/"
  }
}
```
必要なパッケージをインストールします。
```
npm install
```
開発サーバーを起動します。次のコマンドは、ローカルで実行されている開発モードでポータルを起動します。
```
npm start
```
https://localhost:5173 のポータルを参照します。

Azure に配置する

ポータルを Azure Static Web Apps にデプロイする手順については、API Center ポータルのスターターリポジトリを参照してください。

API センターで API を表示するには、ユーザーがサインインする必要があります。サインインを有効にするには、API センターにスコープ指定された組織内のユーザーまたはグループに Azure API センターデータ閲覧者ロールを割り当てます。

重要

既定では、API センターの管理者は API センターポータルで API にアクセスできません。管理者に Azure API センターデータ閲覧者ロールを必ず割り当ててください。

ユーザーとグループにロールを割り当てるための詳細な前提条件と手順については、「Azure portal を使用して Azure ロールを割り当てる」を参照してください。簡単な手順を次に示します。

Azure portal で、API センターに移動します。
左側のメニューで、[アクセス制御 (IAM)]>[+ ロールの割り当ての追加] の順に選択します。
[ロールの割り当ての追加] ペインで、次のように値を設定します。
- [ロール] ページで、[Azure API センターデータ閲覧者] を検索して選択します。 [次へ] を選択します。
- [メンバー] ページの [アクセスの割り当て先] で、[ユーザー、グループ、またはサービスプリンシパル]>[+ メンバーの選択] の順に選択します。
- [メンバーの選択] ページで、ロールを割り当てるユーザーまたはグループを検索して選択します。 [選択]、[次へ] の順にクリックします。
- ロールの割り当てを確認し、[レビューと割り当て] を選択します。

Note

新しいユーザーのアクセス構成を効率化するには、Microsoft Entra グループにロールを割り当て、動的グループのメンバーシップの規則を構成することをお勧めします。詳細については、「Microsoft Entra ID で動的グループを作成または更新する」を参照してください。

ポータルへのアクセスを構成したら、構成されたユーザーはポータルにサインインし、API センターで API を表示できます。

Note

ポータルにサインインする最初のユーザーは、API センターポータルのアプリ登録によって要求されたアクセス許可に同意するよう求められます。それ以降、他の構成されたユーザーは同意を求められません。

トラブルシューティング

エラー: "You are not authorized to access this portal (このポータルへのアクセスが認可されていません)"

特定の条件下では、ユーザーが構成されたユーザーアカウントを使用して API センターポータルにサインインした後、次のエラーメッセージが表示される場合があります。

You are not authorized to access this portal. Please contact your portal administrator for assistance. `

まず、ユーザーに API センター内の Azure API センターデータ閲覧者ロールが割り当てられていることを確認します。

ユーザーにこのロールが割り当てられている場合は、サブスクリプションでの Microsoft.ApiCenter リソースプロバイダーの登録に問題がある可能性があり、リソースプロバイダーの再登録が必要になることがあります。これを行うには、Azure CLI で次のコマンドを実行します。

az provider register --namespace Microsoft.ApiCenter

Azure API Center データ閲覧者ロールが割り当てられているユーザーが、API Center ポータルで [サインイン] を選択した後にサインインフローを完了できない場合は、Microsoft Entra ID の ID プロバイダー構成に問題がある可能性があります。

Microsoft Entra アプリの登録で、必要に応じてリダイレクト URI 設定を確認し、URI が API Center ポータルのデプロイの URI と一致することを確認します。

Microsoft Entra アプリ登録で Azure API センターのアクセス許可を選択できない

API センターポータルの Microsoft Entra アプリ登録で Azure API センターへの API のアクセス許可を要求できない場合は、[Azure API センター] (またはアプリケーション ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573) を検索していることを確認します。

アプリが存在しない場合は、サブスクリプションでの Microsoft.ApiCenter リソースプロバイダーの登録に問題がある可能性があります。リソースプロバイダーの再登録が必要になることがあります。これを行うには、Azure CLI で次のコマンドを実行します。

az provider register --namespace Microsoft.ApiCenter

リソースプロバイダーを再登録した後、もう一度 API のアクセス許可を要求してみてください。

サポートポリシー

API Center ポータルのスターターリポジトリで、フィードバックを提供し、機能を要求し、API Center ポータルのリファレンス実装のサポートを受けます。

API Center ポータルをセルフホストする

API Center ポータルについて

前提条件

Microsoft Entra アプリ登録を作成する

ローカル環境を構成する

Azure に配置する

Microsoft Entra ユーザーおよびグループによるポータルへのサインインを有効にする

トラブルシューティング

エラー: "You are not authorized to access this portal (このポータルへのアクセスが認可されていません)"

ポータルにサインインできない

Microsoft Entra アプリ登録で Azure API センターのアクセス許可を選択できない

サポート ポリシー

関連するコンテンツ

その他のリソース

サポートポリシー