共用方式為

啟用和檢視 Azure API 中心平臺 API 目錄

  • 發行項

本文說明如何在適用於 Azure API 中心的 Visual Studio Code 擴充功能中，為企業開發人員提供 Azure API 中心平臺 API 目錄 （預覽） 的存取權。 使用平臺 API 目錄，開發人員可以在 Azure API 中心探索 API、檢視 API 定義，以及選擇性地在無法管理 API 中心本身或將 API 新增至清查時產生 API 用戶端。 平臺 API 目錄的存取是使用 Microsoft Entra ID 和 Azure 角色型存取控制來管理。

提示

Visual Studio Code 擴充功能為具有管理 Azure API 中心許可權的 API 開發人員提供更多功能。 例如，API 開發人員可以直接在 API 中心或使用 CI/CD 管線註冊 API。 深入了解

必要條件

適用於 API 中心管理員

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

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

適用於應用程式開發人員

下列 Visual Studio Code 擴充功能是選擇性的：

API 中心系統管理員啟用目錄存取權的步驟

下列各節提供 API 中心系統管理員的步驟，讓企業開發人員能夠存取平臺 API 目錄。

建立 Microsoft Entra 應用程式註冊

首先，在您的 Microsoft Entra ID 租用戶中設定應用程式註冊。 應用程式註冊可讓適用於 Azure API 中心的 Visual Studio Code 延伸模組代表登入的使用者存取平臺 API 目錄。

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

  2. 選取 + 新增註冊。

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

    • 將 [名稱] 設定為有意義的名稱，例如 platform-api-catalog
    • 在 [支援的帳戶類型] 區段中，選取 [此組織目錄中的帳戶 (單一租用戶)]。
    • 在 [ 重新導向 URI] 中，選取 [單頁應用程式][SPA]， 並將 URI 設定為 API 中心的運行時間 URI。 例如： https://<service name>.data.<region>.azure-apicenter.ms 。 範例：https://contoso-apic.data.eastus.azure-apicenter.ms。
    • 選取註冊。

    提示

    您可以使用相同的應用程式註冊來存取更多 API 中心。 在 [重新導向 URI] 中，針對您想要出現在平臺 API 目錄中的其他 API 中心，繼續新增重新導向 URI。

  4. 在 [概 觀] 頁面上，複製 應用程式 （用戶端） 識別碼 和 目錄 （租使用者） 識別碼。 當您從 Visual Studio Code 擴充功能連線到 API 中心時，稍後會設定這些值。

  5. 在左側功能表的 [管理] 下方，選取 [驗證]>[+ 新增平台]。

  6. 在 [ 設定平臺] 頁面上，選取 [ 行動和桌面應用程式]。

  7. 在 [設定 桌面 + 裝置 ] 頁面上，輸入下列重新導向 URI，然後選取 [ 設定]：

    https://vscode.dev/redirect

  8. 在左側功能表中的 [管理] 底下，選取 [API 許可權>+ 新增許可權]。

  9. 在 [ 要求 API 許可權 ] 頁面上，執行下列動作：

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

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

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

Microsoft Entra 使用者和群組來啟用平臺 API 目錄的登入

企業開發人員必須使用Microsoft帳戶登入，才能查看 API 中心的平臺 API 目錄。 如有需要， 請將開發人員 新增或邀請至您的 Microsoft Entra 租使用者。

然後，若要啟用登入，請將 Azure API 中心數據讀取器 角色指派給租使用者中的使用者或群組，範圍限定於您的 API 中心。

重要

根據預設，您和其他 API 中心的系統管理員無法存取 API 中心延伸模組平臺 API 目錄中的 API。 請務必將 Azure API 中心資料讀取者角色指派給您自己和其他系統管理員。

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

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

注意

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

企業開發人員存取平臺 API 目錄的步驟

開發人員可以遵循下列步驟，使用 Visual Studio Code 擴充功能連線並登入以檢視平臺 API 目錄。 聯機到 API 中心的設定必須由 API 中心管理員提供。

聯機到 API 中心

  1. 安裝適用於 Visual Studio Code for Visual Studio Code 的 Azure API 中心延伸模組發行前版本。

  2. 在 Visual Studio Code 左側的 [活動列] 中，選取 [API 中心]。

    活動列中 API 中心圖示的螢幕快照。

  3. 使用 Ctrl+Shift+P 鍵盤快速鍵開啟命令選擇區。 輸入 Azure API 中心：連線到 API 中心 ，然後按 Enter。

  4. 回答提示以輸入下列資訊：

    1. API 中心的運行時間 URL，格式 <service name>.data.<region>.azure-apicenter.ms 為 （不要加上 前置詞 https://）。 範例：contoso-apic.data.eastus.azure-apicenter.ms。 此運行時間 URL 會出現在 API 中心 Azure 入口網站 的 [概觀] 頁面上。
    2. 上一節中系統管理員所設定之應用程式註冊的應用程式（用戶端）標識碼。
    3. 上一節中系統管理員所設定之應用程式註冊的目錄（租用戶）標識碼。

    提示

    API 中心系統管理員必須提供這些連線詳細數據給開發人員，或提供下列格式的直接連結：
    vscode://apidev.azure-api-center?clientId=<Client ID>&tenantId=<tenant ID>&runtimeUrl=<service-name>.data.<region>.azure-apicenter.ms

    連線到 API 中心之後，API 中心的名稱會出現在 API 中心平臺 API 目錄中。

  5. 若要在 API 中心檢視 API 中心內的 API，請在 [API 中心名稱] 底下，選取 [ 登入 Azure]。 允許使用在 API 中心指派 Azure API 中心數據讀取器 角色的Microsoft帳戶登入。

    VS Code 延伸模組中 API 中心平臺 API 目錄的螢幕快照。

  6. 登入之後，選取 [API ] 以在 API 中心列出 API。 展開 API 以探索其版本和定義。

    API 中心平臺 API 目錄的螢幕快照，其中具有 VS Code 延伸模組中的 API。

  7. 如果已設定存取權，請重複上述步驟以連線到更多 API 中心。

探索和使用目錄中的 API

平臺 API 目錄可協助企業開發人員探索 API 詳細數據並啟動 API 用戶端開發。 開發人員可以在平臺 API 目錄中以滑鼠右鍵按下 API 定義，以存取下列功能：

  • 匯出 API 規格檔 - 從定義匯出 API 規格，然後將它下載為檔案
  • 產生 API 用戶端 - 使用 Microsoft Kiota 擴充功能，為其慣用的語言產生 API 用戶端
  • 產生 Markdown - 以 Markdown 格式產生 API 檔
  • OpenAPI 檔 - 檢視 API 定義的檔案，並嘗試 Swagger UI 中的作業（僅適用於 OpenAPI 定義）

疑難排解

在某些情況下，使用者可能會在登入 API 中心平臺 API 目錄並展開 API 中心的 API 清單之後，遇到下列錯誤訊息：

Error: Cannot read properties of undefined (reading 'nextLink')

檢查使用者是否已在 API 中心指派 Azure API 中心數據讀取器 角色。 如有必要，請將角色重新指派給使用者。 然後，在Visual Studio Code 擴充功能中重新整理 API 中心平臺 API 目錄。

無法登入 Azure

如果在平臺 API 目錄中選取 [登入 Azure] 之後，已獲指派 Azure API 中心數據讀取者角色的用戶無法完成登入流程，則聯機設定可能會有問題。

檢查您在 Microsoft Entra ID 中所設定之應用程式註冊中的設定。 在應用程式註冊和 API 中心的運行時間 URL 中，確認應用程式 （用戶端） 識別碼和目錄 （租使用者） 識別碼的值。 然後，再次設定 API 中心的連線。

無法在 Microsoft Entra ID 應用程式註冊中選取 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 權限。

相關內容