API Management 開発者ポータルをセルフホストする

2025-05-21

適用対象: 開発者 |基本 |標準 |プレミアム

このチュートリアルでは、 API Management 開発者ポータルを自己ホストする方法について説明します。セルフホスティングは、開発者ポータルの機能を拡張するためのいくつかのオプションの 1 つです。たとえば、API Management インスタンスの複数のポータルをさまざまな機能でセルフホストできます。ポータルを自己ホストすると、そのメンテナンス担当者になり、アップグレードの責任を負います。

Von Bedeutung

開発者ポータルのコードベースのコアを変更する必要がある場合にのみ、開発者ポータルを自己ホストすることを検討してください。このオプションには、次のような高度な構成が必要です。

ホスティングプラットフォームへのデプロイ(必要に応じて、可用性とパフォーマンスを向上させるために CDN などのソリューションによって前面に配置される)
ホスティングインフラストラクチャの保守と管理
セキュリティパッチを含む手動更新プログラム。コードベースをアップグレードするときにコードの競合を解決する必要がある場合があります

注

セルフホステッドポータルでは、マネージド開発者ポータルで使用できる可視性とアクセス制御はサポートされていません。

マネージドポータルでメディアファイルを既にアップロードまたは変更している場合は、この記事で後述する「管理対象からセルフホステッドへの移行」を参照してください。

[前提条件]

ローカル開発環境を設定するには、次のものが必要です。

API Management サービスインスタンス。お持ちでない場合は、「クイックスタート - Azure API Management インスタンスを作成する」を参照してください。
静的 Web サイト機能が有効になっている Azure ストレージアカウント。ストレージアカウントの作成を参照してください。
マシン上の Git。この Git チュートリアルに従ってインストールします。
Node.js (LTS バージョン、 v10.15.0 以降) と npm をコンピューターにインストールします。 Node.js と npm のダウンロードとインストールを参照してください。
Azure CLI。 Azure CLI のインストール手順に従います。

手順 1: ローカル環境を設定する

ローカル環境を設定するには、リポジトリを複製し、開発者ポータルの最新リリースに切り替えて、npm パッケージをインストールする必要があります。

GitHub から api-management-developer-portal リポジトリを複製します。
```
git clone https://github.com/Azure/api-management-developer-portal.git
```
リポジトリのローカルコピーに移動します。
```
cd api-management-developer-portal
```
ポータルの最新リリースを確認してください。

次のコードを実行する前に、リポジトリの [リリース] セクションで現在のリリースタグを確認し、 <current-release-tag> 値を最新のリリースタグに置き換えます。
```
git checkout <current-release-tag>
```
使用可能な npm パッケージをインストールします。
```
npm install
```

ヒント

常に最新のポータルリリースを使用し、フォークされたポータル up-to-date のままにします。ソフトウェアエンジニアは、毎日の開発のために、このリポジトリの master ブランチを使用します。これは、ソフトウェアの不安定なバージョンを持っています.

手順 2: JSON ファイル、静的 Web サイト、および CORS 設定を構成する

開発者ポータルでは、コンテンツを管理するために API Management REST API が必要です。

config.design.json ファイル

src フォルダーに移動し、config.design.json ファイルを開きます。

{
  "environment": "development",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature ...",
  "backendUrl": "https://<service-name>.developer.azure-api.net",
  "useHipCaptcha": false,
  "integration": {
      "googleFonts": {
          "apiKey": "..."
      }
  }
}

ファイルを構成します。

managementApiUrl値で、<service-name>を API Management インスタンスの名前に置き換えます。カスタムドメインを構成した場合は、代わりにカスタムドメインを使用します (たとえば、https://management.contoso.com)。
```
{
...
"managementApiUrl": "https://contoso-api.management.azure-api.net"
...
```
SAS トークンを手動で作成して、API Management インスタンスへの直接 REST API アクセスを有効にします。
生成されたトークンをコピーし、 managementApiAccessToken 値として貼り付けます。
backendUrl値で、<service-name>を API Management インスタンスの名前に置き換えます。カスタムドメインを構成した場合は、代わりにカスタムドメインを使用します (たとえば、https://portal.contoso.com)。
```
{
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...
```
開発者ポータルで CAPTCHA を有効にする場合は、 "useHipCaptcha": true設定します。開発者ポータルバックエンドの CORS 設定を必ず構成してください。
integrationの [googleFonts] で、必要に応じて apiKeyを、Web フォント開発者 API へのアクセスを許可する Google API キーに設定します。このキーは、開発者ポータルエディターの [スタイル] セクションで Google フォントを追加する場合にのみ必要です。

まだキーがない場合は、Google Cloud コンソールを使用してキーを構成できます。次の手順に従います。
1. Google Cloud コンソールを開きます。
2. Web フォント開発者 API が有効になっているかどうかを確認します。有効になっていない場合は、有効にします。
3. [ 資格情報の作成>API キー] を選択します。
4. 開いているダイアログで、生成されたキーをコピーし、apiKey ファイル内のconfig.design.jsonの値として貼り付けます。
5. [ API キーの編集] を選択してキーエディターを開きます。
6. エディターの [ API の制限] で、[ キーの制限] を選択します。ドロップダウンで、[ Web フォント開発者 API] を選択します。
7. 保存を選択します。

config.publish.json ファイル

src フォルダーに移動し、config.publish.json ファイルを開きます。

{
  "environment": "publishing",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature...",
  "useHipCaptcha": false
}

ファイルを構成します。

前の構成ファイルの managementApiUrl と managementApiAccessToken の値をコピーして貼り付けます。
開発者ポータルで CAPTCHA を有効にする場合は、 "useHipCaptcha": true設定します。開発者ポータルバックエンドの CORS 設定を必ず構成してください。

config.runtime.json ファイル

src フォルダーに移動し、config.runtime.json ファイルを開きます。

{
  "environment": "runtime",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "backendUrl": "https://<service-name>.developer.azure-api.net"
}

ファイルを構成します。

前の構成ファイルの managementApiUrl 値をコピーして貼り付けます。
backendUrl値で、<service-name>を API Management インスタンスの名前に置き換えます。カスタムドメインを構成した場合は、代わりにカスタムドメインを使用します (例: https://portal.contoso.com)。
```
{
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...
```

静的 Web サイトを構成する

インデックスページとエラーページへのルートを指定して、ストレージアカウントで 静的 Web サイト 機能を構成します。

Azure portal でストレージアカウントに移動し、左側のメニューから [静的 Web サイト ] を選択します。
[ 静的な Web サイト ] ページで、[ 有効] を選択します。
[ インデックスドキュメント名 ] フィールドに「 index.html」と入力します。
[ エラードキュメントパス ]フィールドに「 404/index.html」と入力します。
保存を選択します。

ストレージアカウントの CORS 設定を構成する

ストレージアカウントのクロスオリジンリソース共有 (CORS) 設定を構成します。

Azure portal でストレージアカウントに移動し、左側のメニューから CORS を選択します。

[BLOB サービス] タブで、次の規則を構成します。

規則	価値
許可されるオリジン	*
使用できるメソッド	すべての HTTP 動詞を選択します。
許可されるヘッダー	*
公開されるヘッダー	*
最大年齢	0

保存を選択します。

開発者ポータルバックエンドの CORS 設定を構成する

開発者ポータルバックエンドの CORS 設定を構成して、セルフホステッド開発者ポータルから送信された要求を許可します。セルフホステッド開発者ポータルは、開発者ポータルのバックエンドエンドポイント (ポータル構成ファイルの backendUrl で設定) に依存して、次のようないくつかの機能を有効にします。

CAPTCHA 検証
テストコンソールでの OAuth 2.0 承認
ユーザー認証と製品サブスクリプションの委任

CORS 設定を追加するには:

Azure portal で API Management インスタンスに移動し、左側のメニューから [開発者ポータル>ポータル設定 ] を選択します。
[ セルフホステッドポータルの構成 ] タブで、1 つ以上の Origin ドメイン値を追加します。例えば：
- セルフホステッドポータルがホストされているドメイン (例: https://www.contoso.com
- localhost 該当する場合には、ローカル開発用として、http://localhost:8080 や https://localhost:8080
保存を選択します。

手順 3: ポータルを実行する

これで、開発モードでローカルポータルインスタンスをビルドして実行できます。開発モードでは、すべての最適化がオフになり、ソースマップがオンになります。

次のコマンドを実行します。

npm start

しばらくすると、既定のブラウザーがローカルの開発者ポータルインスタンスと共に自動的に開きます。既定のアドレスは http://localhost:8080ですが、 8080 が既に占有されている場合はポートが変更される可能性があります。プロジェクトのコードベースを変更すると、リビルドがトリガーされ、ブラウザーウィンドウが更新されます。

手順 4: ビジュアルエディターを使用して編集する

ビジュアルエディターを使用して、次のタスクを実行します。

ポータルをカスタマイズする
作成者コンテンツ
Web サイトの構造を整理する
外観のスタイルを設定する

「チュートリアル: 開発者ポータルにアクセスしてカスタマイズする」を参照してください。管理ユーザーインターフェイスの基本について説明し、既定のコンテンツに対する推奨される変更の一覧を示します。すべての変更をローカル環境に保存し、 Ctrl キーを押しながら C キーを押して閉じます。

手順 5: ローカルに発行する

ポータルデータは、厳密に型指定されたオブジェクトの形式で生成されます。次のコマンドは、それらを静的ファイルに変換し、出力を ./dist/website ディレクトリに配置します。

npm run publish

手順 6: 静的ファイルを BLOB にアップロードする

Azure CLI を使用してローカルで生成された静的ファイルを BLOB にアップロードし、訪問者がアクセスできることを確認します。

Windows コマンドプロンプト、PowerShell、またはその他のコマンドシェルを開きます。
次の Azure CLI コマンドを実行します。

<account-connection-string>をストレージアカウントの接続文字列に置き換えます。ストレージアカウントの [アクセスキー ] セクションから取得できます。
```
az storage blob upload-batch --source dist/website \
    --destination '$web' \
    --connection-string <account-connection-string>
```

手順 7: Web サイトに移動する

Web サイトは、Azure Storage のプロパティ (静的 Web サイトのプライマリエンドポイント) で指定されたホスト名の下に存在するようになりました。

手順 8: API Management 通知テンプレートを変更する

API Management 通知テンプレートの開発者ポータルの URL を、セルフホステッドポータルを指すように置き換えます。 Azure API Management で通知と電子メールテンプレートを構成する方法を参照してください。

特に、既定のテンプレートに対して次の変更を実行します。

注

次の更新されたセクションの値は、 https://portal.contoso.com/でポータルをホストしていることを前提としています。

電子メールの変更の確認

電子メール変更確認通知テンプレートで開発者ポータルの URL を更新します。

元のコンテンツ

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

更新

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

新しい開発者アカウントの確認

新しい開発者アカウントの確認通知テンプレートで開発者ポータルの URL を更新します。

元のコンテンツ

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

更新

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

ユーザーを招待

ユーザーの招待通知テンプレートで開発者ポータルの URL を更新します。

元のコンテンツ

<a href="$ConfirmUrl">$ConfirmUrl</a>

更新

<a href="https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery">https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery</a>

アクティブ化された新しいサブスクリプション

新しいサブスクリプションがアクティブ化された通知テンプレートで、開発者ポータルの URL を更新します。

元のコンテンツ

Thank you for subscribing to the <a href="http://$DevPortalUrl/products/$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

更新

Thank you for subscribing to the <a href="https://portal.contoso.com/product#product=$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

元のコンテンツ

Visit the developer <a href="http://$DevPortalUrl/developer">profile area</a> to manage your subscription and subscription keys

更新

Visit the developer <a href="https://portal.contoso.com/profile">profile area</a> to manage your subscription and subscription keys

元のコンテンツ

<a href="http://$DevPortalUrl/docs/services?product=$ProdId">Learn about the API</a>

更新

<a href="https://portal.contoso.com/product#product=$ProdId">Learn about the API</a>

元のコンテンツ

<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/applications">Feature your app in the app gallery</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">You can publish your application on our gallery for increased visibility to potential new users.</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/issues">Stay in touch</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
      If you have an issue, a question, a suggestion, a request, or if you just want to tell us something, go to the <a href="http://$DevPortalUrl/issues">Issues</a> page on the developer portal and create a new topic.
</p>

更新

<!--Remove the entire block of HTML code above.-->

パスワードの変更確認

パスワード変更確認通知テンプレートで開発者ポータルの URL を更新します。

元のコンテンツ

<a href="$DevPortalUrl">$DevPortalUrl</a>

更新

<a href="https://portal.contoso.com/confirm-password?$ConfirmQuery">https://portal.contoso.com/confirm-password?$ConfirmQuery</a>

すべてのテンプレート

フッターにリンクがあるテンプレートの開発者ポータルの URL を更新します。

元のコンテンツ

<a href="$DevPortalUrl">$DevPortalUrl</a>

更新

<a href="https://portal.contoso.com/">https://portal.contoso.com/</a>

マネージド開発者ポータルからセルフホステッド開発者ポータルへの移行

時間の経過と伴い、ビジネス要件が変わる可能性があります。最終的に、API Management 開発者ポータルのマネージドバージョンがニーズを満たさない状況になります。たとえば、新しい要件により、サードパーティのデータプロバイダーと統合されるカスタムウィジェットを作成することが強制される場合があります。マネージドバージョンとは異なり、セルフホステッドバージョンのポータルでは、完全な柔軟性と拡張性が提供されます。

移行プロセス

マネージドバージョンから、同じ API Management サービスインスタンス内のセルフホステッドバージョンに移行できます。このプロセスでは、ポータルのマネージドバージョンで実行した変更が保持されます。ポータルのコンテンツを事前にバックアップしてください。バックアップスクリプトは、API Management 開発者ポータル scriptsのフォルダーにあります。

変換プロセスは、この記事の前の手順に示すように、汎用のセルフホステッドポータルの設定とほぼ同じです。構成手順には例外が 1 つあります。 config.design.json ファイル内のストレージアカウントは、ポータルのマネージドバージョンのストレージアカウントと同じである必要があります。 SAS URL を取得する方法については、「チュートリアル: Linux VM のシステム割り当て ID を使用して SAS 資格情報を使用して Azure Storage にアクセスする」を参照してください。

ヒント

config.publish.json ファイルでは、別のストレージアカウントを使用することをお勧めします。この方法を使用すると、ポータルのホスティングサービスをより詳細に制御し、管理を簡略化できます。

セルフホスティングの代替アプローチについて説明します

次の方法で共有

API Management 開発者ポータルをセルフホストする

[前提条件]

手順 1: ローカル環境を設定する

手順 2: JSON ファイル、静的 Web サイト、および CORS 設定を構成する

config.design.json ファイル

config.publish.json ファイル

config.runtime.json ファイル

静的 Web サイトを構成する

ストレージ アカウントの CORS 設定を構成する

開発者ポータル バックエンドの CORS 設定を構成する

手順 3: ポータルを実行する

手順 4: ビジュアル エディターを使用して編集する

手順 5: ローカルに発行する

手順 6: 静的ファイルを BLOB にアップロードする

手順 7: Web サイトに移動する

手順 8: API Management 通知テンプレートを変更する

電子メールの変更の確認

新しい開発者アカウントの確認

ユーザーを招待

アクティブ化された新しいサブスクリプション

パスワードの変更確認

すべてのテンプレート

マネージド開発者ポータルからセルフホステッド開発者ポータルへの移行

移行プロセス

関連コンテンツ

フィードバック

その他のリソース

ストレージアカウントの CORS 設定を構成する

開発者ポータルバックエンドの CORS 設定を構成する

手順 4: ビジュアルエディターを使用して編集する