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

[アーティクル]
03/29/2024

適用対象: Developer | Basic | Standard | Premium

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

重要

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

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

Note

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

メディアファイルがマネージドポータルに既にアップロードされているか変更されている場合は、この記事の後の方にある「マネージドからセルフホステッド開発者ポータルへの移行」を参照してください。

前提条件

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

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 パッケージをインストールする必要があります。

api-management-developer-portal レポジトリを GitHub から複製します。
```
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
```

ヒント

常に最新のポータルリリースを使用し、フォークしたポータルを最新の状態に保つようにします。ソフトウェアエンジニアはこのリポジトリの 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 Fonts Developer API へのアクセスを許可する Google API キーに設定します。このキーは、開発者ポータルエディターの [スタイル] セクションで Google フォントを追加する場合にのみ必要です。

まだキーがない場合は、Google Cloud コンソールを使用してキーを構成できます。次の手順のようにします。
1. Google Cloud コンソールを開きます。
2. Web Fonts Developer API が有効になっているかどうかを確認します。そうでない場合は、有効にしてください。
3. [Create credentials] (資格情報の作成)> [API key] (API キー) の順に選択します。
4. 開いているダイアログで、生成されたキーをコピーし、config.design.json ファイル内の apiKey の値として貼り付けます。
5. [Edit API key] (API キーの編集) を選択して、キーエディターを開きます。
6. エディターの [API restrictions] (API の制限) で、[Restrict key] (キーの制限) を選択します。ドロップダウンで、[Web Fonts Developer 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 service] タブで、次のルールを構成します。

ルール	値
許可されたオリジン	*
許可されたメソッド	すべての HTTP 動詞を選択します。
許可されるヘッダー	*
公開されるヘッダー	*
最長有効期間	0

[保存] を選択します。

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

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

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

CORS 設定を追加するには、次のようにします。

Azure portal で API Management インスタンスに移動し、左側のメニューから [開発者ポータル]>[ポータル設定] を選択します。
[Self-hosted portal configuration](セルフホステッドポータルの構成) タブで、1 つ以上の配信元ドメイン値を追加します。例:
- セルフホステッドポータルがホストされているドメイン (例: 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 で通知と電子メールテンプレートを構成する方法」を参照してください。

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

Note

次の「更新」セクションの値は、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 開発者ポータルの GitHub リポジトリの 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: ビジュアルエディターを使用して編集する