共用方式為

自我裝載您的 API 中心入口網站

  • 發行項

本文介紹 API 中心入口網站，這是貴組織中開發人員和其他項目關係人可用來探索 API 中心 API 的網站。 從 API 中心入口網站入門 存放庫部署入口網站的參考實作。

使用者登入后 API 中心入口網站的螢幕快照。

關於 API 中心入口網站

API 中心入口網站是一個網站，您可以建置和裝載以在 API 中心顯示 API 清查。 入口網站可讓組織中的開發人員和其他項目關係人探索 API 並檢視 API 詳細數據。

您可以使用 API 中心入口網站入門存放庫中的程式碼來建置及部署入口網站的參考實作。 入口網站會使用 Azure API 中心數據平面 API ，從 API 中心擷取數據。 使用者對 API 資訊的存取是以 Azure 角色為基礎的訪問控制為基礎。

API 中心入口網站參考實作提供：

  • 使用 GitHub Actions 發佈和維護客戶管理的 API 入口網站架構
  • 客戶可修改或擴充以符合其需求的入口網站平臺
  • 彈性裝載於不同的基礎結構上，包括部署至 Azure Static Web Apps 等服務。

必要條件

  • Azure 訂用帳戶中的 API 中心。 如果您尚未建立，請參閱快速入門：建立您的 API 中心。

  • 在與 Azure 訂用帳戶相關聯的 Microsoft Entra 租用戶中建立應用程式註冊的權限，以及授與 API 中心資料存取權的權限。

  • 若要建置和部署入口網站，您需要在本機計算機上安裝 GitHub 帳戶和下列工具：

建立 Microsoft Entra 應用程式註冊

先在 Microsoft Entra ID 租用戶中設定應用程式註冊。 應用程式註冊可讓 API 中心入口網站代表已登入的使用者，從您的 API 中心存取資料。

  1. 在 Azure 入口網站中，瀏覽至 [Microsoft Entra ID] > [應用程式註冊]。

  2. 選取 + 新增註冊。

  3. 在 [登錄應用程式]頁面上設定數值，如下所示：

    • 將 [名稱] 設定為有意義的名稱，例如 api-center-portal

    • 在 [支援的帳戶類型] 區段中，選取 [此組織目錄中的帳戶 (單一租用戶)]。

    • 在 [ 重新導向 URI] 中，選取 [單頁應用程式][SPA]， 然後設定 URI。

      • 針對本機測試，請將 URI 設定為 https://localhost:5173。
      • 針對生產環境，請將URI設定為API中心入口網站部署的URI。

    • 選取註冊。

  4. 在 [概 觀] 頁面上，複製 應用程式 （用戶端） 識別碼 和 目錄 （租使用者） 識別碼。 當您建置入口網站時，會設定這些值。

  5. 在 [API 權限] 頁面上，選取 [+ 新增權限]。

    1. 在 [要求 API 權限] 頁面上，選取 [我的組織使用的 API] 索引標籤。搜尋並選取 [Azure API 中心]。 您也可以搜尋並選取應用程式識別碼 c3ca1a77-7a87-4dba-b8f8-eea115ae4573。
    2. 在 [要求權限] 頁面上，選取 user_impersonation。
    3. 選取新增權限。

    Azure API 中心權限會出現在 [已設定的權限] 底下。

    入口網站中 Microsoft Entra ID 應用程式註冊中所需許可權的螢幕快照。

設定本機環境

請遵循下列步驟，在本機建置及測試 API 中心入口網站。

  1. 將 API 中心入口網站入門 存放庫複製到本機電腦。

    git clone https://github.com/Azure/APICenter-Portal-Starter.git

  2. 變更為 APICenter-Portal-Starter 目錄。

    cd APICenter-Portal-Starter

  3. 簽出 main 分支。

    git checkout main

  4. 若要設定服務，請將檔案複製或重新命名 public/config.example 為 public/config.json。

  5. 然後編輯檔案 public/config.json 以指向您的服務。 更新檔案中的值，如下所示：

    • 將和 <region> 取代<service name>為 API 中心的名稱及其部署所在的區域
    • 將與 <tenant ID> 取代為您在上一節建立應用程式註冊的應用程式（客戶端）識別碼和目錄（租使用者）識別碼。<client ID>
    • 將的值 title 更新為您想要出現在入口網站上的名稱。
    {
  "dataApiHostName": "<service name>.data.<region>.azure-apicenter.ms/workspaces/default",
  "title": "API portal",
  "authentication": {
      "clientId": "<client ID>",
      "tenantId": "<tenant ID>",
      "scopes": ["https://azure-apicenter.net/user_impersonation"],
      "authority": "https://login.microsoftonline.com/"
  }
}

  6. 安裝必要的套件。

    npm install

  7. 啟動開發伺服器。 下列命令會在本機執行的開發模式中啟動入口網站：

    npm start

    瀏覽至位於 https://localhost:5173的入口網站。

部署至 Azure

如需將入口網站部署至 Azure Static Web Apps 的步驟，請參閱 API 中心入口網站入門 存放庫。

啟用透過 Microsoft Entra 使用者和群組登入入口網站

用戶必須登入，才能在 API 中心查看 API。 若要啟用登入，請將 Azure API 中心資料讀取者角色指派給您的組織中的使用者或群組，範圍限定於您的 API 中心。

重要

根據預設，您和 API 中心的其他系統管理員無法存取 API 中心入口網站中的 API。 請務必將 Azure API 中心資料讀取者角色指派給您自己和其他系統管理員。

如需將角色指派給使用者和群組的詳細必要條件和步驟，請參閱使用 Azure 入口網站指派 Azure 角色。 簡短步驟如下：

  1. 在 Azure 入口網站中，瀏覽至您的 API 中心。
  2. 在左側功能表中，選取 [存取控制 (IAM)] > [+ 新增角色指派]。
  3. 在 [新增角色指派] 窗格中，設定值，如下所示：
    • 在 [角色] 頁面上，搜尋並選取 [Azure API 中心資料讀取者]。 選取 [下一步]。
    • 在 [成員] 頁面上的 [指派存取權] 中，選取 [使用者、群組或服務主體] > [+ 選取成員]。
    • 在 [選取成員] 頁面上，搜尋並選取要指派角色的使用者或群組。 按一下 [選取]，然後按 [下一步]。
    • 檢閱角色指派，然後選取 [檢閱 + 指派]。

注意

若要簡化新使用者的存取設定，建議您將角色指派至 Microsoft Entra 群組，並設定動態群組成員資格規則。 若要深入了解，請參閱在 Microsoft Entra ID 中建立或更新動態群組。

設定入口網站的存取權之後，設定的使用者就可以登入入口網站，並在您的 API 中心檢視 API。

注意

系統會對第一個登入入口網站的使用者提示同意 API 中心入口網站應用程式註冊所要求的權限。 之後更不會對其他已設定的使用者提示同意。

疑難排解

錯誤：「您未獲授權，無法存取此入口網站」

在某些情況下，使用者可能會在使用已設定的使用者帳戶登入 API 中心入口網站之後，遇到下列錯誤訊息：

You are not authorized to access this portal. Please contact your portal administrator for assistance. `

首先，確認已在 API 中心為使用者指派 Azure API 中心資料讀取者角色。

如果使用者獲派該角色，則訂用帳戶中 Microsoft.ApiCenter 資源提供者的註冊可能發生問題，且您可能需要重新註冊資源提供者。 若要這樣做，請在 Azure CLI 中執行下列命令：

az provider register --namespace Microsoft.ApiCenter

無法登入入口網站

如果在 API 中心入口網站中選取 [登入] 之後，已獲指派 Azure API 中心數據讀取者角色的用戶無法完成登入流程，則 Microsoft Entra ID 識別提供者的設定可能會有問題。

在 Microsoft Entra 應用程式註冊中，檢視需要更新 [ 重新導向 URI ] 設定，以確保 URI 符合 API 中心入口網站部署的 URI。

無法在 Microsoft Entra 應用程式註冊中選取 Azure API 中心權限

如果您無法在 API 中心入口網站的 Microsoft Entra 應用程式註冊中向 Azure API 中心要求 API 權限，請檢查您正在搜尋 Azure API 中心 (或應用程式識別碼 c3ca1a77-7a87-4dba-b8f8-eea115ae4573)。

如果應用程式不存在，您的訂用帳戶中 Microsoft.ApiCenter 資源提供者的註冊可能發生問題。 您可能需要重新註冊資源提供者。 若要這樣做，請在 Azure CLI 中執行下列命令：

az provider register --namespace Microsoft.ApiCenter

重新註冊資源提供者之後，請重試以要求 API 權限。

支援原則

在 API 中心入口網站入門存放庫中提供意見反應、要求功能，以及取得 API 中心入口網站參考實作的支援。

相關內容