自我裝載 API 管理開發人員入口網站

文章
03/29/2024

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

本教學課程說明如何自我裝載 API 管理開發人員入口網站。自我裝載是數個選項中的其中一個，可針對開發人員入口網站來擴充功能。例如，您可以針對 API 管理執行個體自我裝載多個入口網站，並具有不同的功能。當您自我裝載入口網站時，您就會成為入口網站的維護者，而且您必須負責升級入口網站。

重要

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

部署至裝載平台，選擇性地面對 CDN 這類的解決方案，以提高可用性和效能
維護和管理裝載基礎結構
手動更新 (包括安全性修補程式)，而您可能需要在升級程式碼基底時解決程式碼衝突

注意

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

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

必要條件

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

API 管理服務執行個體。如果您沒有，請參閱快速入門 - 建立 Azure API 管理執行個體。
已啟用靜態網站功能的 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
```

提示

請務必使用最新版入口網站，並將分支入口網站保持為最新狀態。軟體工程師會使用此 master 存放庫的分支來進行每日開發。這會有不穩定的軟體版本。

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

開發人員入口網站需要 API 管理 REST API 來管理內容。

config.design.json file

移至 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 管理執行個體的名稱。如果您已設定自訂網域，請改使用此自訂網域 (例如，https://management.contoso.com)。
```
{
...
"managementApiUrl": "https://contoso-api.management.azure-api.net"
...
```
手動建立 SAS 權杖，讓直接 REST API 存取 API 管理執行個體。
複製產生的權杖，並貼上權杖作為 managementApiAccessToken 值。
在 backendUrl 值中，將 <service-name> 取代為 API 管理執行個體的名稱。如果您已設定自訂網域，請改使用此自訂網域 (例如，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。如果未啟用，請啟用該 API (英文)。
3. 選取 [建立認證]>[API 金鑰]。
4. 在開啟的對話方塊中，複製產生的金鑰，並將其作為 apiKey 的值貼到 config.design.json 檔案中。
5. 選取 [編輯 API 金鑰] 以開啟金鑰編輯器。
6. 在編輯器的 [API 限制] 底下，選取 [限制金鑰]。在下拉式清單中，選取 [Web Fonts Developer API]。
7. 選取 [儲存]。

config.publish.json file

移至 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 file

移至 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 管理執行個體的名稱。如果您已設定自訂網域，請改使用此自訂網域 (例如 https://portal.contoso.com)。
```
{
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...
```

設定靜態網站

藉由提供索引和錯誤頁面的路由，在您的儲存體帳戶中設定靜態網站功能：

移至 Azure 入口網站中的儲存體帳戶，然後從左側功能表中選取 [靜態網站]。
在 [靜態網站] 頁面上，選取 [已啟用]。
在 [索引文件名稱] 欄位中，輸入 index.html。
在 [錯誤文件路徑] 欄位中，輸入 404/index.html。
選取 [儲存]。

設定儲存體帳戶的 CORS 設定

設定儲存體帳戶的跨原始來源資源共用 (CORS) 設定：

移至 Azure 入口網站中的儲存體帳戶，然後從左側功能表中選取 [CORS]。
在 [Blob 服務] 索引標籤中，設定下列規則：

規則值

允許的原始來源 *

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

允許的標題 *

公開的標題 *

存留期上限 0
選取 [儲存]。

規則	值
允許的原始來源	*
允許的方法	選取所有 HTTP 動詞命令。
允許的標題	*
公開的標題	*
存留期上限	0

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

設定開發人員入口網站後端的 CORS 設定，以便允許源自您自我裝載開發人員入口網站的要求。自我裝載開發人員入口網站會依賴開發人員入口網站的後端端點 (在入口網站組態檔中的 backendUrl 進行設定)，以便啟用數項功能，包括：

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

若要新增 CORS 設定：

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

步驟 3：執行入口網站

現在，您可以在開發模式中建置和執行本機入口網站執行個體。在開發模式中，全部最佳化都會關閉，而且會開啟來源對應。

執行以下命令：

npm start

在短時間內，預設瀏覽器會使用您的本機開發人員入口網站執行個體以自動開啟。預設位址為 http://localhost:8080，但如果 8080 已佔用，則連接埠可能會變更。專案程式碼基底的任何變更都會觸發重建並重新整理瀏覽器視窗。

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

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

自訂您的入口網站
撰寫內容
組織網站的結構
樣式化其外觀

請參閱教學課程：存取及自訂開發人員入口網站。這涵蓋系統管理使用者介面的基本概念，並列出預設內容的建議變更。儲存本機環境中的全部變更，然後按下 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：前往您的網站

您的網站現在位於 Azure 儲存體屬性中指定的主機名稱底下 (靜態網站中的主要端點)。

步驟 8：變更 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 管理開發人員入口網站 GitHub 存放庫的 scripts 資料夾中找到備份指令碼。

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

提示

建議您在 config.publish.json 檔案中使用個別的儲存體帳戶。這種方法可讓您更充分掌控並簡化入口網站的主控服務管理。

下一步

了解自我裝載的替代方法

分享方式：

自我裝載 API 管理開發人員入口網站

必要條件

步驟 1：設定本機環境

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

config.design.json file

config.publish.json file

config.runtime.json file

設定靜態網站

設定儲存體帳戶的 CORS 設定

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

步驟 3：執行入口網站

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

步驟 5：在本機發佈

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

步驟 7：前往您的網站

步驟 8：變更 API 管理通知範本

電子郵件變更確認

新開發人員帳戶確認

邀請使用者

已啟用新的訂用帳戶

密碼變更確認

所有範本

從受控開發人員入口網站移至自我裝載開發人員入口網站

轉換流程

下一步

意見反映

更多資源