開發人員入口網站概觀

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

API 管理 開發人員入口網站會自動產生且完全可自定義的網站，其中包含API的檔。 API 取用者可以在此探索您的 API、了解如何使用 API、要求存取權和試用 API。

本文介紹開發人員入口網站的功能、入口網站呈現的內容類型，以及管理及擴充特定使用者和案例開發人員入口網站的選項。

注意

我們最近改善了入口網站編輯器介面，以提高您的生產力，並增強與慣用功能和工具的互動。 我們也重新設計了 API 和產品詳細數據小工具，以提升訪客的入口網站體驗。

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

開發人員入口網站架構概念

入口網站元件可以邏輯方式分成兩個類別：「程式碼」和「內容」。

代碼

程式碼會在 API 管理開發人員入口網站 GitHub 存放庫中維護，其中包含：

• 小工具 - 代表視覺化元素，並結合 HTML、JavaScript、樣式功能、設定和內容對應。 範例包括影像、文字段落、表單、API 清單等。
• 樣式定義 - 指定小工具如何設定樣式
• 引擎 - 從入口網站內容產生靜態網頁，並以 JavaScript 撰寫
• 視覺化編輯器 - 允許瀏覽器內自訂和撰寫體驗

Content

內容分成兩個子類別：入口網站內容和 API 管理 數據。

• 入口網站內容 專屬於入口網站，包括：

  • 頁面 - 例如登陸頁面、API 教學課程、部落格文章

  • 媒體 - 影像、動畫和其他檔案型內容

  • 版面配置 - 與 URL 相符的範本，並定義頁面的顯示方式

  • 樣式 - 樣式定義的值，例如字型、色彩、框線

  • 設定 - 最愛圖示、網站中繼資料等設定

    除了媒體以外，入口網站內容會以 JSON 檔表示。

• API 管理 數據報括在 API 管理 實例中管理的實體，例如 API、作業、產品和訂用帳戶。

自訂和設定入口網站的樣式

現成可用的開發人員入口網站已填入已發佈的 API 和產品，並準備好根據您的需求自定義。 身為 API 發行者，您可以使用開發人員入口網站的系統管理介面來自定義開發人員入口網站的外觀和功能。

如果您是第一次存取入口網站，入口網站會包含佔位元元頁面、內容和導覽功能表。 您看到的佔位元元內容已設計為展示入口網站的功能，並將個人化入口網站所需的自定義專案降到最低。

如需自定義和發佈開發人員入口網站的逐步解說，請參閱 教學課程：存取和自定義開發人員入口網站。

重要

• API 發行者和取用者對開發人員入口網站的存取需要對開發人員入口網站的端點（預設值：）和 API 管理 實例的管理端點進行網路連線（預設值：https://<apim-instance-name>.portal.azure-api.net）。 https://<apim-instance-name>.management.azure-api.net
• 發佈開發人員入口網站需要對美國西部區域 API 管理 所管理的 Blob 記憶體進行額外的連線。
• 如果 API 管理 實例部署在 VNet 中，請確定開發人員入口網站和管理端點的主機名會正確解析，並讓您能夠連線到開發人員入口網站所需的相依性。 深入了解。

視覺效果編輯器

開發人員入口網站的系統管理介面為發行者提供可視化編輯器，以自定義入口網站的內容和樣式。 使用可視化編輯器，您可以新增、移除和重新排列頁面、區段和小工具。 您也可以變更入口網站元素的樣式，例如字型、色彩和間距。

身為系統管理員，您可以使用可視化編輯器自定義入口網站的內容。

• 使用左側的功能表選項來建立或修改頁面、媒體、版面配置、功能表、樣式或網站設定。

• 在頂端，切換檢視區（針對不同大小的螢幕），或檢視不同 群組中用戶可看見的入口網站元素。 例如，您可能只想要將特定頁面顯示給與特定產品相關聯的群組，或顯示可存取特定 API 的使用者。

• 此外，儲存或復原您所做的變更，或發佈網站。

• 選取現有的文字和標題元素，以編輯和格式化內容。

• 將區段停留在空白區域，然後按兩下具有加號的藍色圖示，以將區段新增至頁面。 從數個區段配置中選擇。

  

• 將滑鼠停留在空白區域，以新增小工具（例如文字、影像、自定義小工具或 API 清單），然後按兩下具有加號的灰色圖示。

  

• 依拖放方式重新排列頁面中的專案。

版面配置和頁面

版面配置定義頁面的顯示方式。 例如在預設內容中，有兩個配置：一個會套用至首頁，另一個則用於所有其他頁面。 您可以修改這些版面配置，並新增更多版面配置以符合您的需求。

配置會將其 URL 範本與頁面的 URL 進行比對，以套用至頁面。 例如，具有 URL 範本 /wiki/* 的版面配置會套用至 URL 中具有區段的每個頁面 /wiki/ ： /wiki/getting-started、 /wiki/styles等等。

在下圖中，屬於版面配置的內容會以藍色框起，而頁面特定內容則以紅色框線。

開發人員入口網站中預先布建的內容會展示具有常用功能的頁面。 您可以修改這些頁面的內容，或加入新的頁面，以符合您的需求。

注意

基於整合考量，下列頁面無法在不同的 URL 下移除或移動：/404、/500、/captcha、/change-password、/config.json、/confirm/invitation、/confirm-v2/identities/basic/signup、/confirm-v2/password、/internal-status-0123456789abcdef、/publish、/signin、/signin-sso、/signup。

樣式

[ 樣式 ] 面板是以設計工具為考慮而建立。 使用樣式來管理和自定義入口網站中的所有視覺元素，例如標題和功能表和按鈕色彩中使用的字型。 樣式設定是階層式的，許多元素會從其他元素繼承屬性。 例如，按鈕元素會使用文字和背景的色彩。 若要變更按鈕的色彩，您需要變更原始的色彩變化。

若要編輯變體，請選取它，然後在其頂端出現的選項中選取 [編輯樣式 ]。 在快顯視窗中進行變更之後，請將其關閉。

擴充入口網站功能

在某些情況下，您可能需要除了受控開發人員入口網站中提供的自訂和樣式選項之外的功能。 如果您需要實作目前不支援的自訂邏輯，則有數個選項：

• 透過專為小型自訂所設計的開發人員入口網站小工具直接新增自訂 HTML，例如，新增表單的 HTML 或內嵌視訊播放程式。 自訂程式碼會在內嵌框架 (IFrame) 中轉譯。
• 建立和上傳自訂小工具，以開發和新增更複雜的自訂入口網站功能。
• 只有在您需要修改開發人員入口網站程式碼基底的核心時，才能自我裝載入口網站。 此選項需要進階設定。 Azure 支援服務的協助僅限於自我裝載入口網站的基本設定。

注意

因為API 管理開發人員入口網站程式碼基底是在 GitHub 上進行維護，所以您可以開啟問題，並針對 API 管理小組提出提取要求，隨時合併新功能。

控制入口網站內容的存取

開發人員入口網站會與您的 API 管理 實例同步，以顯示 API、作業、產品、訂用帳戶和使用者配置檔等內容。 API 和產品必須處於 已發佈 狀態，才能在開發人員入口網站中顯示。

內容可見性和存取

在 API 管理 中，使用者群組可用來管理產品及其相關 API 對開發人員的可見度。 除了使用內建群組之外，您還可以建立自定義群組以符合您的需求。 產品是先設為可讓群組看見，然後群組中的開發人員就能檢視和訂閱與群組相關聯的產品。

您也可以根據不同的使用者身分識別，控制其他入口網站內容（例如頁面和區段）如何顯示給不同的使用者。 例如，建議您只向有權存取特定產品或 API 的使用者顯示特定頁面。 或者，僅針對特定使用者或群組顯示某個頁面區段。 開發人員入口網站內建可滿足這些需求的控制項。

注意

只有受控開發人員入口網站才支援可見性和存取控制。 自我裝載入口網站不支持它們。

• 當您新增頁面或編輯現有頁面的設定時，請在 [存取] 底下選取 ，以控制可以看到頁面的使用者或群組

  

  提示

  若要編輯現有頁面的設定，請選取 [頁面] 索引卷標上頁面名稱旁的齒輪圖示。

• 當您選取頁面內容，例如頁面區段、功能表或按鈕進行編輯時，請選取 [變更存取 ] 圖示來控制可在頁面上看到元素的使用者或群組

  

  • 您可以變更下列頁面內容的可見性：區段、功能表、按鈕，以及 OAuth 授權的登入。

  • 頁面上的媒體檔案 (例如影像) 會繼承其所屬元素的可見性。

當使用者瀏覽已套用可見性和存取控制的開發人員入口網站時：

• 開發人員入口網站會自動隱藏指向該使用者無權存取之頁面的按鈕或瀏覽項目。

• 用戶嘗試存取他們未獲授權存取的頁面，會導致 404 找不到錯誤。

提示

使用系統管理介面，您可以選取 頂端功能表中的 [檢視] 作為與任何內建或自定義群組相關聯的使用者預覽頁面。

內容安全性原則

您可以啟用內容安全策略，將一層安全性新增至開發人員入口網站，並協助減輕某些類型的攻擊，包括跨網站腳本和數據插入。 使用內容安全策略時，瀏覽器上的開發人員入口網站只會從您指定的受信任位置載入資源，例如公司網站或其他受信任的網域。

若要啟用內容安全策略：

1. 在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。
2. 在左側功能表中的 [開發人員入口網站] 底下，選取 [入口網站設定]。
3. 在 [ 內容安全策略] 索引標籤上，選取 [ 已啟用]。
4. 在 [允許的來源] 下，新增一或多個主機名，以指定開發人員入口網站可從中載入資源的信任位置。 您也可以指定通配符，以允許網域的所有子域。 例如， *.contoso.com 允許的所有子域 contoso.com。
5. 選取 [儲存]。

互動式測試主控台

開發人員入口網站會在 API 參考頁面上提供「試用」功能，讓入口網站訪客可以直接透過互動式控制檯測試 API。

測試控制台支援具有不同授權模型的 API-例如，不需要授權的 API，或需要訂用帳戶密鑰或 OAuth 2.0 授權的 API。 在後者的情況下，您可以設定測試控制台，代表測試控制台用戶產生有效的 OAuth 令牌。 如需詳細資訊，請參閱如何透過設定 OAuth 2.0 使用者授權來授權開發人員入口網站的測試主控台。

重要

若要讓入口網站的訪客透過內建的互動式控制台測試 API，請在 API 上啟用 CORS（跨原始來源資源分享）原則。 如需詳細資訊，請參閱在 API 管理 開發人員入口網站中啟用互動式控制台的CORS。

管理用戶註冊和登入

根據預設，開發人員入口網站會啟用匿名存取。 這表示任何人都可以在不登入的情況下檢視入口網站及其內容，不過可能會限制使用測試控制台等特定內容和功能的存取權。 您可以啟用開發人員入口網站設定，要求使用者登入才能存取入口網站。

入口網站支援數個選項來註冊和登入：

• 開發人員使用 API 管理 用戶帳戶認證登入的基本身份驗證。 開發人員可以直接透過入口網站註冊帳戶，也可以為其建立帳戶。

• 根據您的案例，要求使用者使用 Microsoft Entra ID 或 Azure AD B2C 帳戶註冊或登入，以限制對入口網站的存取。

• 如果您已經透過現有的網站管理開發人員註冊和登入， 請委派驗證 ，而不是使用開發人員入口網站的內建驗證。

深入瞭解 保護用戶註冊和登入開發人員入口網站的選項。

用戶的報告

開發人員入口網站會為已驗證的用戶產生報告，以檢視其個別 API 使用量、數據傳輸和響應時間，包括特定產品和訂用帳戶的匯總使用。 使用者可以在已驗證使用者的預設導覽功能表中選取 [報表 ]，以檢視報表。 用戶可以依時間間隔篩選報告，最多90天。

注意

開發人員入口網站中的報表只會顯示已驗證用戶的數據。 API 發行者和系統管理員可以存取 API 管理 實例所有使用者的使用方式數據，例如，藉由在入口網站中設定 Azure 應用程式 Insights 等監視功能。

儲存及發佈網站內容

更新開發人員入口網站內容或組態之後，您必須儲存併發佈變更，讓入口網站訪客可以使用這些變更。 開發人員入口網站會維護您所發佈內容的記錄，而且當您需要時，可以還原為先前的入口網站 修訂 。

儲存變更

每當您在入口網站中進行變更時，必須選取 頂端功能表中的 [儲存 ] 按鈕，或按 [Ctrl]+[S] 手動儲存它。 如果您需要，您可以 復原 上次儲存的變更。 儲存的變更只會顯示於您，而且在您發佈變更之前，入口網站訪客不會看見這些變更。

注意

受控開發人員入口網站會自動接收並套用軟體更新。 您儲存但未發佈給開發人員入口網站的變更會在更新期間維持該狀態。

發佈入口網站

若要讓您的入口網站和其最新的變更可供訪客使用，您需要「發佈」內容。 您可以在入口網站的系統管理介面內，或從 Azure 入口網站 發佈入口網站。

重要

您需要隨時發佈入口網站，以公開入口網站內容或樣式的變更。 在 API 管理 影響開發人員入口網站的服務組態變更之後，也必須重新發佈入口網站。 例如，指派自訂網域、更新身分識別提供者、設定委派，或指定登入和產品條款之後，請重新發佈入口網站。

從系統管理介面發佈

1. 選取 [儲存] 按鈕，確定您已儲存變更。

2. 在頂端的功能表中，選取 [ 發佈網站]。 這項作業可能需要幾分鐘的時間。

   

從 Azure 入口網站發佈

1. 在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。

2. 在左側功能表中開發人員入口網站下，選取 [入口網站概觀]。

3. 在入口網站概觀視窗中，選取 [發佈]。

   

還原先前的入口網站修訂

每次發佈開發人員入口網站時，都會儲存對應的入口網站修訂。 您可以隨時重新發佈先前的入口網站修訂。 例如，您可能想要回復上次發佈入口網站時所引進的變更。

注意

當您還原修訂時，會自動套用開發人員入口網站軟體更新。 當您發佈修訂時，儲存但未在系統管理介面中發佈的變更會維持在該狀態。

若要還原先前的入口網站修訂：

1. 在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。
2. 在左側功能表中開發人員入口網站下，選取 [入口網站概觀]。
3. 在 [ 修訂] 索引標籤上，選取您要還原之修訂的操作功能表 （...），然後選取 [ 讓目前和發佈]。

重設入口網站

如果您想要捨棄您對開發人員入口網站所做的所有變更，您可以將網站重設為其起始狀態。 重設入口網站會刪除您對開發人員入口網站頁面、版面配置、自定義和上傳媒體所做的任何變更。

注意

重設開發人員入口網站不會刪除已發行的開發人員入口網站版本。

若要重設開發人員入口網站：

1. 在系統管理介面的可視化編輯器左側功能表中，選取 [設定]。
2. 在 [ 進階] 索引標籤上，選取 [ 是]，將網站重設為默認狀態。
3. 選取 [儲存]。

相關內容

深入了解開發人員入口網站：

• 存取和自訂受控開發人員入口網站
• 擴充受控開發人員入口網站的功能
• 啟用開發人員入口網站使用量的記錄
• 設定入口網站的自我裝載版本

瀏覽其他資源：

• 使用原始程式碼 GitHub 存放庫
• 開發人員入口網站的常見問題