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

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

Von Bedeutung

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

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

注

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

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

[前提条件]

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

API Management サービスインスタンス。お持ちでない場合は、「クイックスタート - Azure API Management インスタンスを作成する」を参照してください。

v2 サービスレベルでインスタンスを作成した場合は、まず開発者ポータルを有効にします。
1. サイドバーメニューの [開発者ポータル] で、[ ポータルの設定] を選択します。
2. ポータルの 設定ウィンドウで、[ 有効] を選択します。保存を選択します。開発者ポータルを有効にするには数分かかる場合があります。
静的な Web サイト機能を有効にするために使用する Azure BLOB ストレージアカウント。ストレージアカウントの作成を参照してください。
マシン上の Git。この Git チュートリアルに従ってインストールします。
Node.js (長期サポート (LTS) バージョン、 v10.15.0 以降) と npm をコンピューターにインストールします。 Node.js と npm のダウンロードとインストールを参照してください。
Azure CLI。 Azure CLI のインストール手順に従います。
Microsoft Entra アプリ登録を作成するためのアクセス許可。

手順 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 のままにします。 API Management 開発チームは、毎日の開発目的でこのリポジトリの master ブランチを使用します。これは、ソフトウェアの不安定なバージョンを持っています.

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

config.design.json ファイル

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

{
    "environment": "development",
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >"
}

subscriptionId、resourceGroupName、およびserviceNameで、API Management インスタンスのサブスクリプション、リソースグループ、およびサービス名の値を入力します。 I

config.design.json のオプションの設定

必要に応じて、 config.design.json ファイルで次の設定を構成します。

開発者ポータルで CAPTCHA を有効にする場合は、 "useHipCaptcha": true設定します。開発者ポータルバックエンドの CORS 設定を必ず構成してください。
```
{
    ...
    "useHipCaptcha": true
    ...
}
```
integrationの [googleFonts] で、必要に応じて apiKeyを、Web フォント開発者 API へのアクセスを許可する Google API キーに設定します。このキーは、開発者ポータルエディターの [スタイル] セクションで Google フォントを追加する場合にのみ必要です。
```
{
    ...
    "integration": {
        "googleFonts": {
            "apiKey": "< your Google API key >"
        }
    }
    ...
}
```
まだキーがない場合は、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",
    "subscriptionId":"<service subscription>",
    "resourceGroupName":"<service resource group>",
    "serviceName":"<service name>"
}

前の構成ファイルの subscriptionId、 resourceGroupName、 serviceName の値をコピーして貼り付けます。

config.runtime.json ファイル

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

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

< service name >は、前の構成ファイルで使用した API Management インスタンスの名前に置き換える必要があります。

静的 Web サイトを構成する

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

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

プライマリエンドポイントの URL を書き留めます。後で、セルフホステッドポータルにアクセスするように構成します。

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

ストレージアカウントのクロスオリジンリソース共有 (CORS) 設定を構成するには:

Azure portal で、ストレージアカウントに移動します。
サイドバーメニューの [設定] で、[ リソース共有 (CORS)] を選択します。

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

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

保存を選択します。

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

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

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

CORS 設定を追加するには:

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

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

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

次のコマンドを実行します。
```
npm run start
```
ブラウザーを使用して認証するように求められます。続行するには、Microsoft 資格情報を選択します。
しばらくすると、既定のブラウザーがローカルの開発者ポータルインスタンスと共に自動的に開きます。既定のアドレスは http://localhost:8080ですが、 8080 が既に占有されている場合はポートが変更される可能性があります。プロジェクトのコードベースを変更すると、リビルドがトリガーされ、ブラウザーウィンドウが更新されます。

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

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

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

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

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

npm run publish を実行します。ブラウザーを使用して認証するように求められます。続行するには、Microsoft 資格情報を選択します。
しばらくすると、コンテンツは dist/website フォルダーに発行されます。

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

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

Windows コマンドプロンプト、PowerShell、またはその他のコマンドシェルを開きます。
次の az storage blog upload-batch コマンドを実行します。 <connection-string>をストレージアカウントの接続文字列に置き換えます。ストレージアカウントの [セキュリティ + ネットワーク>Access キー ] セクションから取得できます。
```
az storage blob upload-batch --source dist/website \
    --account-name <your-storage-account-name> \
    --destination '$web' \
    --connection-string "<connection-string>"
```

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

Web サイトは、Azure Storage のプロパティで指定されたホスト名の下に表示されるようになりました。サイドバーメニューで、 データ管理>Static Web サイトに移動します。ホスト名はプライマリエンドポイントの値です。

Web サイトエディターをホストする

Web サイトコードを変更する場合は、変更したウィジェットの編集を適切にサポートできるように、Web サイトエディターコードの更新が必要になる場合があります。この場合、ポータルをホストするだけでなく、エディターアプリケーションをホストすることもできます。そのためには、それをビルドし、API Management サービスにアクセスするように構成する必要があります。

このためには、テナントに Microsoft Entra ID アプリケーションが必要です。

Microsoft Entra ID テナントにアプリケーションを登録します。 アプリケーション (クライアント) ID とディレクトリ (テナント) ID を書き留めます。後の手順で構成します。
デザイナーがホストされている Web アプリのエンドポイントを指すように、このアプリケーションで Web リダイレクト URI (応答 URL) を構成します。これは通常、BLOB ストレージベースの Web サイトの場所です。例: https://<your-storage-account-name>z13.web.core.windows.net/。
パイプライン (GitHub Actions) でポータルを発行する場合は、このアプリケーションのクライアントシークレットも作成します。生成されたシークレット値をメモし、安全な場所に格納します。

次に、次の手順に従って Web サイトエディターをホストします。

clientId ファイルにtenantIdフィールドとconfig.design.json フィールドを追加します。
```
{
    ...
    "clientId": "< Entra ID app ID >",
    "tenantId": "< Entra ID tenant ID >"
    ...
}
```
npm run build-designer コマンドを実行してデザイナーをビルドします。

生成された /dist/designer フォルダーに移動します。このフォルダーには、次の内容のファイル config.json が含まれています。

{
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >",
    "clientId": "< Entra ID client ID >",
    "tenantId": "< Entra ID tenant ID >"
}

Azure Resource Manager API を使用して API Management サービスに接続するために必要な subscriptionId、 resourceGroupName 、 serviceNameの構成を確認します。

パイプラインでポータルを発行する (GitHub Actions)

GitHub Actions などのパイプラインでセルフホステッドポータルを発行できます。

パイプラインによる発行を実行するためには、Entra ID アプリケーション資格情報も必要です。前の手順で説明したのと同じ Entra ID アプリケーションを使用できます。 tenantId、clientId、特にclientSecretは、それぞれのキーストレージに保持する必要があります。詳細については、 GitHub Actions でのシークレットの使用に関するページを参照してください。

GitHub Actions パイプライン YAML の例:


name: Portal-Publishing-Pipeline

on:
  pull_request:
    branches:
      - master

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
      AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Set up Node.js
        uses: actions/setup-node@v5
        with:
          node-version: '20.x'

      - name: Install dependencies
        run: npm install

      - name: Run publish command
        run: npm run publish

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.v3のフォルダーにあります。

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

ヒント

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

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

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-10-30

次の方法で共有

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

[前提条件]

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

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

config.design.json ファイル

config.design.json のオプションの設定

config.publish.json ファイル

config.runtime.json ファイル

静的 Web サイトを構成する

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

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

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

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

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

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

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

Web サイト エディターをホストする

パイプラインでポータルを発行する (GitHub Actions)

API Management 通知テンプレートを変更する

電子メールの変更の確認

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

ユーザーの招待

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

パスワードの変更確認

すべてのテンプレート

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

移行プロセス

関連コンテンツ

フィードバック

その他のリソース

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

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

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

Web サイトエディターをホストする