自行託管 API 管理開發者入口網站

適用於：開發人員 |基本 |基本 v2 |標準 |標準 v2 |Premium |進階 v2

本教學課程說明如何自我裝載 API 管理開發人員入口網站。自我託管是擴展開發者門戶功能的數個選項之一。例如，您可以自行架設具備不同功能的多個 API 管理實例入口網站。當您自行裝載入口網站時，您會成為其維護者，並負責其升級。開發人員入口網站需要 API 管理 REST API 來管理內容。

這很重要

只有在您需要修改開發人員入口網站核心程式碼時，才考慮自行主機開發人員入口網站。此選項需要進階設定，包括：

部署至託管平台，選用內容傳遞網路（CDN）等解決方案來作為前端，以提高可用性和效能。
維護和管理託管基礎設施。
手動更新，包括安全性修補程式，這可能需要您在升級程式碼庫時解決程式碼衝突。

備註

自我裝載入口網站不支援受控開發人員入口網站中可用的可見度和存取控制。

如果您已在受控入口網站中上傳或修改媒體檔案，請參閱本文稍後的從受控移至自我裝載。

先決條件

若要設定本機開發環境，您必須有：

API 管理服務執行個體。如果您沒有帳戶，請參閱快速入門 - 建立 Azure API 管理實例。

如果您在 v2 服務層級中建立了執行個體，請先啟用開發人員入口網站。
1. 在側邊欄功能表的 [開發人員入口網站] 底下，選取 [入口網站設定]。
2. 在 入口網站設定視窗中，選取 已啟用。選取 [儲存]。啟用開發人員入口網站可能需要幾分鐘的時間。
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
```

小提示

請務必使用最新版入口網站，並將分支入口網站保持為最新狀態。 API 管理開發小組會使用此倉庫的 master 分支進行日常開發。其軟體版本不穩定。

步驟 2：設定 JSON 檔案、靜態網站和 CORS 設定

config.design.json file

移至 src 資料夾並開啟 config.design.json 檔案。

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

在 subscriptionId、 resourceGroupName和 serviceName中，輸入 API 管理執行個體的訂用帳戶、資源群組和服務名稱的值。 I

config.design.json 中的選用設定

可選擇在 config.design.json 檔案中配置以下設定：

如果您要在開發人員入口網站中開啟 CAPTCHA，請設定 "useHipCaptcha": true。請務必設定開發人員入口網站後端的CORS設定。
```
{
    ...
    "useHipCaptcha": true
    ...
}
```
在 integration的下 googleFonts，選擇性地設定 apiKey 為允許存取 Web Fonts Developer 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 file

移至 src 資料夾並開啟 config.publish.json 檔案。

{
    "environment": "publishing",
    "subscriptionId":"<service subscription>",
    "resourceGroupName":"<service resource group>",
    "serviceName":"<service name>"
}

從上一個組態檔複製並貼上 subscriptionId、 resourceGroupName和 serviceName 值。

config.runtime.json file

移至 src 資料夾並開啟 config.runtime.json 檔案。

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

將 < service name > 替換為先前組態檔中使用的 API 管理執行個體的名稱。

設定靜態網站

提供索引和錯誤頁面的路由，以設定記憶體帳戶中的 靜態網站 功能：

在 Azure 入口網站中，移至您在 Azure 入口網站中的儲存體帳戶。
在側邊欄功能表中，選取 資料管理>靜態網站。
在 [靜態網站] 頁面上，選取 [已啟用]。
在 [ 索引檔案名稱] 欄位中，輸入 index.html。
在 [ 錯誤檔案路徑] 欄位中，輸入 404/index.html。
選取 [儲存]。

記下 主要端點 URL。您稍後可以設定它，以存取自行託管的入口網站。

設定記憶體帳戶的 CORS 設定

若要設定儲存體帳戶的跨來源資源共用（CORS）設定：

移至 Azure 入口網站中您的儲存體帳戶。
從側邊欄功能表的 [設定] 底下，選取 [資源共用（CORS）]。
在 [Blob 服務] 索引標籤中，設定下列規則：

規則價值觀

允許的原始來源 *

允許的方法選取所有 HTTP 動詞。

允許的標題 *

公開的標頭 *

最大年齡上限 0
選取 [儲存]。

規則	價值觀
允許的原始來源	*
允許的方法	選取所有 HTTP 動詞。
允許的標題	*
公開的標頭	*
最大年齡上限	0

設定開發人員入口網站後端的CORS設定

設定開發人員入口後端的 CORS 設定，以允許源自您自行托管的開發人員入口的請求。自行託管的開發人員入口網站依賴於開發人員入口網站的後端端點（在入口網站backendUrl檔案中設定config.runtime.json），以啟用多項功能，包括：

CAPTCHA 驗證
測試主控台中的 OAuth 2.0 授權
使用者驗證和產品訂用帳戶的委派

若要新增 CORS 設定：

在 Azure 入口網站中移至您的 API 管理執行個體。
在側邊欄功能表中，選取 [開發人員入口網站>設定]。
在 [自我裝載入口網站設定] 索引標籤上，新增一或多個原始網域值。例如：
- 裝載了自我裝載入口網站的網域，例如 https://contoso.developer.azure-api.net
- localhost 用於本地開發（如果適用），例如 http://localhost:8080 或 https://localhost:8080
選取 [儲存]。

步驟 3：運行門戶網站

現在，您可以在開發模式中建置和執行本機入口網站執行個體。在開發模式中，所有的優化設置都會關閉，並開啟原始碼地圖。

執行下列命令：
```
npm run start
```
系統會提示您透過瀏覽器進行驗證。選取您的 Microsoft 認證以繼續。
一段時間後，預設瀏覽器會自動開啟，並顯示您的本端開發人員入口網站實例。默認位址為 http://localhost:8080，但如果 8080 已佔用，該埠可能會變更。當您對專案的程式碼庫進行變更時，它會觸發重建並重新整理您的瀏覽器視窗。

步驟 4：透過可視化編輯器編輯

使用視覺化編輯器來執行下列工作：

自訂您的入口網站
作者內容
組織網站的結構
美化它的外觀

請參閱教學課程：存取和自定義開發人員入口網站。其涵蓋系統管理使用者介面的基本概念，並列出預設內容的建議變更。儲存本機環境中的所有變更，然後按 Ctrl+C 將其關閉。

步驟 5：在本機發佈入口網站

執行 npm run publish。系統會提示您透過瀏覽器進行驗證。選取您的 Microsoft 認證以繼續。
一段時間後，內容會發佈到資料夾 dist/website 。

步驟 6：將靜態檔案上傳至 Blob

使用 Azure CLI 將本機產生的靜態檔案上傳至 Blob，並確定您的訪客可以存取它們：

開啟 Windows 命令提示字元、PowerShell 或其他命令列介面。
執行下列 az storage blog upload-batch 命令。將 <connection-string> 取代為您的儲存體帳戶的連接字串。您可以從儲存體帳戶的 [安全性 + 網路>存取金鑰] 區段取得它。
```
az storage blob upload-batch --source dist/website \
    --account-name <your-storage-account-name> \
    --destination '$web' \
    --connection-string "<connection-string>"
```

步驟 7：移至您的網站

您的網站現在會以 Azure 儲存體屬性中指定的主機名稱上線。在側邊欄功能表中，移至 資料管理>靜態網站。主機名稱是 主要端點的值。

管理網站編輯器

更改網站代碼時，您可能還需要更新網站編輯器代碼，以便能夠正確支持編輯修改後的小部件。在此情況下，除了裝載入口網站之外，您可能還想要裝載編輯器應用程式。為此，您必須建置它並設定以存取您的 API 管理服務。

為此，您的租用戶中需要有一個 Microsoft Entra ID 應用程式：

在您的 Microsoft Entra ID 租戶中註冊應用程式。記下 應用程式（用戶端） ID 和 目錄（租戶） ID。您可以在稍後的步驟中設定它們。
在此應用程式中設定 Web 重新導向 URI （回覆 URL），以指向裝載設計工具之 Web 應用程式端點。這通常是基於 Blob 儲存體的網站的位置。範例： https://<your-storage-account-name>z13.web.core.windows.net/.
如果您想要在管線中發佈入口網站（GitHub Actions），也請為此應用程式建立用戶端密碼。記下產生的秘密值並將其儲存在安全的位置。

然後，按照以下步驟託管網站編輯器：

將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 >"
}

確認 subscriptionId、resourceGroupName 和 serviceName 的設定，這些是使用 Azure Resource Manager APIs 連接到 API 管理服務所需要的。

在管線中發佈入口網站 (GitHub Actions)

您可以在管線 (例如 GitHub Actions) 中發佈自我裝載的入口網站。

管道還需要 Entra ID 應用程式憑證，才能透過管道執行發佈工作。您可以使用先前步驟所述的相同 Entra ID 應用程式。、 tenantIdclientId和特別是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 管理通知範本

取代 API 管理通知範本中的開發人員入口網站 URL，使其指向您的自我裝載入口網站。請參閱如何在 Azure API 管理中設定通知和電子郵件範本。

特別是，對預設範本執行下列變更：

備註

下列 [更新] 區段中的值假設您要在 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 管理開發人員入口網站的受控版本不再滿足您需求的情況。例如，新需求可能會強制您建置與協力廠商資料提供者整合的自訂小工具。不同於受控版本，入口網站的自我裝載版本提供您完整的彈性和擴充性。

過渡過程

您可以從受控版本轉換至相同 API 管理服務實例內的自我裝載版本。此程序會保留您在入口網站受管理版本中執行的修改。請確定您事先備份入口網站的內容。您可以在 API 管理開發人員入口網站 scripts.v3的資料夾中找到備份文稿。

轉換過程與設定一般自行架設入口網站幾乎完全相同，如本文先前的步驟所示。設定步驟中有一個例外狀況。檔案中的 config.design.json 記憶體帳戶必須與入口網站受控版本的記憶體帳戶相同。如需如何擷取 SAS URL 的指示，請參閱教學課程：使用 Linux VM 系統指派的身分識別透過 SAS 認證存取 Azure 儲存體。

小提示

建議您在config.publish.json檔案中使用單獨的儲存帳戶。此方法可讓您更好地控制並簡化入口網站的主機服務管理。

瞭解自行託管的替代方法

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-31

共用方式為

自行託管 API 管理開發者入口網站

先決條件

步驟 1：設定本機環境

步驟 2：設定 JSON 檔案、靜態網站和 CORS 設定

config.design.json file

config.design.json 中的選用設定

config.publish.json file

config.runtime.json file

設定靜態網站

設定記憶體帳戶的 CORS 設定

設定開發人員入口網站後端的CORS設定

步驟 3：運行門戶網站

步驟 4：透過可視化編輯器編輯

步驟 5：在本機發佈入口網站

步驟 6：將靜態檔案上傳至 Blob

步驟 7：移至您的網站

管理網站編輯器

在管線中發佈入口網站 (GitHub Actions)

變更 API 管理 通知範本

電子郵件變更確認

新的開發人員帳戶確認

邀請使用者

已啟動新的訂用帳戶

密碼變更確認

所有範本

從管理的開發人員入口網站轉移到自架式入口網站

過渡過程

相關內容

意見反應

其他資源

變更 API 管理通知範本