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

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

ポータルの自己ホストについて

API Center ポータルのスターター リポジトリのコードを使用して、ポータルの参照実装をビルドしてデプロイできます。 ポータルでは、 Azure API Center データ プレーン API を使用して API センターからデータを取得します。

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

• 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 センターからデータにアクセスできます。

API Center では、アプリの登録を自動的に設定することも、アプリの登録を手動で作成することもできます。

アプリの登録を自動的に設定する

アプリの登録を自動的に設定するには、次の手順に従います。

1. Azure portal で、API センターに移動します。
2. 左側のメニューで、 API センター ポータル>Settings を選択します。
3. [ ID プロバイダー ] タブで、[ セットアップの開始] を選択します。
4. [ クイック セットアップ ] タブで、[ 保存と発行] を選択します。

後でアプリ登録にアクセスする必要がある場合は、ポータルの [ アプリの登録] で確認できます。 アプリケーションには、 <api-center-name>-apic-aad という形式で名前が付けられます。

アプリの登録を手動で設定する

アプリの登録を手動で作成する場合は、次の手順に従います。

1. Azure portal で、Microsoft Entra ID>Manage>App 登録に移動します。

2. [+ 新規登録] を選択します。

3. [アプリケーションを登録] ページで、次のように値を設定します。

   1. 名前を api-center-portal などのわかりやすい名前に設定する
   2. [サポートされているアカウントの種類] で、この組織のディレクトリ内のアカウントのみを選択します (<Directory 名> - シングル テナント)。
   3. [リダイレクト URI] で、[シングルページ アプリケーション (SPA)] を選択し、URI を設定します。 API Center ポータルのデプロイの URI を、次の形式で入力します: https://<service-name>.portal.<location>.azure-apicenter.ms。 <service name>と<location>は、API センターの名前とデプロイ先の場所 (例: https://myapicenter.portal.eastus.azure-apicenter.ms) に置き換えます。
   4. 登録 を選択します。

VS Code 拡張機能の追加のリダイレクト URI を構成する

Api Center の Visual Studio Code 拡張機能で API センター ポータル ビューを有効にする場合は、アプリの登録で次のリダイレクト URI も構成します。

1. Azure portal で、アプリの登録に移動します。

2. [ 管理>認証 ] ページで、[ プラットフォームの追加 ] を選択し、[ モバイル アプリケーションとデスクトップ アプリケーション] を選択します。

3. 次の 3 つのカスタム リダイレクト URI を構成します。
   https://vscode.dev/redirect
http://localhost
ms-appx-web://Microsoft.AAD.BrokerPlugin/<application-client-id>
   

   <application-client-id>を、このアプリのアプリケーション (クライアント) ID に置き換えます。 この値は、アプリ登録の [概要 ] ページで確認できます。

ローカル環境を構成する

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

1. API Center ポータルのスターター リポジトリをローカル コンピューターに複製します。

   git clone https://github.com/Azure/APICenter-Portal-Starter.git
   

2. APICenter-Portal-Starter ディレクトリに変更します。

   cd APICenter-Portal-Starter
   

3. メイン ブランチを確認します。

   git checkout main
   

4. サービスを構成するには、 public/config.example ファイルを public/config.jsonにコピーまたは名前を変更します。

5. 次に、サービスを指す public/config.json ファイルを編集します。 ファイル内の値を次のように更新します。

   1. <service name>と<location>を、API センターの名前とデプロイ先の場所に置き換えます
   2. <client ID>と<tenant ID>を、前のセクションで作成したアプリ登録のアプリケーション (クライアント) ID とディレクトリ (テナント) ID に置き換えます。
   3. titleの値を、ポータルの上部バーに表示する名前に更新します。

   {
     "dataApiHostName": "<service name>.data.<location>.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/"
     }
   }
   

6. 必要なパッケージをインストールします。

   npm install
   

7. 開発サーバーを起動します。 次のコマンドは、ローカルで実行されている開発モードでポータルを起動します。

   npm start
   

   https://localhost:5173のポータルを参照します。

Azure にデプロイする

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

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

API センター ポータルへのサインインを有効にして API にアクセスするには、API センターをスコープとする組織内のユーザーまたはグループに Azure API Center データ閲覧者 ロールを割り当てます。

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

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

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

トラブルシューティング

エラー: "このポータルにアクセスする権限がありません"

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

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

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

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

az provider register --namespace Microsoft.ApiCenter

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

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

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

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

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 センター ポータルを設定する
• Azure のロールベースのアクセス制御 (RBAC) とは
• Azure RBAC のベスト プラクティス
• リソース プロバイダーを登録する