API 探索和取用

  • 5 分鐘

API 探索和取用是在整個組織中使用 API 的重要環節。

在本單元中，您將了解 API 中心 VS Code 延伸模組如何讓您輕鬆地探索及取用 API。

必要條件

若要透過 VS Code 上的 API 中心延伸模組來控管 API，您必須：

下列 Visual Studio Code 延伸模組是選擇性的，且僅適用於特定案例，如下所示：

API 探索和取用

您可以直接在 Visual Studio Code 中檢視組織的 API 目錄，內含您所有的 API、版本、定義、環境和部署。 您可以立即取得組織內所有可用 API 的概觀，一目了然。

但若組織有數百或數千個 API，該怎麼辦？ 別擔心，您可以透過搜尋圖示搜尋 API，如下所示。

此螢幕擷取畫面顯示 VS Code 上的搜尋 API 選項

檢視 API 文件

您也可以針對 VS Code 上的 API，快速存取及預覽適用的 API 文件和測試端點。 此螢幕擷取畫面顯示 VS Code 上的 Swagger 文件

  1. 從索引標籤開啟 API 中心延伸模組。
  2. 展開 [API 中心] 樹狀檢視，以顯示 API 定義。
  3. 以滑鼠右鍵按一下定義，然後選取 [開啟 API 文件]。
  4. 新的索引標籤隨即出現，其中包含 API 定義的 Swagger UI。
  5. 選取端點，然後選取 [試用]，提供必要的參數，然後選取 [執行]。

試用 API

透過 API 中心延伸模組，您可以根據 API 中心所提供的 API 定義來檢視 .http 檔案。 在此檔案上，您可以直接傳送 HTTP 要求，並直接在編輯器上檢視回應。

注意

您必須安裝 REST 用戶端延伸模組，才能使用此功能。 此螢幕擷取畫面顯示如何使用 REST 用戶端在 VS Code 上檢視 API 的 .http

  1. 展開 [API 中心] 樹狀檢視，以顯示 API 定義。
  2. 以滑鼠右鍵按一下定義，然後選取 [產生 HTTP 檔案]。
  3. 此時會出現新的索引標籤，轉譯由 API 規格填入的 .http 文件。
  4. 若要提出要求，請選取端點，然後選取 [傳送要求]。

產生 SDK

API 中心延伸模組也會使用 Microsoft Kiota，為您的慣用語言產生 HTTP REST API 的用戶端，如 OpenAPI 規格中所定義。 這可讓您立即為 API 的所有或選定端點產生用戶端，以滿足您的業務需求。

注意

您必須安裝 Microsoft Kiota 延伸模組，才能使用此功能。

  1. 展開 [API 中心] 樹狀檢視，以顯示 API 定義。

  2. 以滑鼠右鍵按一下定義，然後選取 [產生 API 用戶端]。 [Kiota OpenAPI 產生器] 窗格隨即出現。 此螢幕擷取畫面顯示如何使用 Kiota 在 VS Code 上產生 API 用戶端的選項

  3. 選取要包含在 SDK 中的 API 端點和 HTTP 作業。 您可以將滑鼠暫留在端點上方，並選取 '+' 按鈕加以新增，或選取 '-' 加以移除。

  4. 完成後，選取 [執行] 按鈕以產生 API 用戶端。 此螢幕擷取畫面顯示如何選取使用 Kiota 在 VS Code 上新增或移除特定端點的選項

  5. 選取 [產生 API 用戶端]。

    a. 輸入關於 SDK 名稱、命名空間和輸出目錄的設定詳細資料。

    b. 為產生的 SDK 選取語言。

自我裝載 API 中心入口網站

API 中心入口網站是一個網站，可讓開發人員和專案關係人順暢地探索您 API 詳細目錄中的 API 並與其互動。 透過此自我裝載網站，組織為取用者提供了 Web 型 API 探索和取用體驗。

此螢幕擷取畫面顯示 contoso API 中心入口網站或網站的登陸頁面

API 平台工程師想要為其所有的 API 取用者 (包括內部和外部) 提供一個集中且獨立的位置。 首先，您可以執行下列步驟，以使用 API 中心入口網站入門範本：

注意

以下是部署至 Azure Static Web Apps 的指示，但您可以部署在自己選擇的基礎結構上。

  1. 派生 API 中心參考實作程式碼。

  2. 在 Azure 上建立靜態 Web 應用程式資源。

  3. 在 [部署詳細資料] 底下，選取 [GitHub ] 作為來源，然後導向至包含 API 中心入門程式碼的存放庫。

  4. Static Web Apps 會偵測組建預設，並使用 React 填入。

  5. 輸入 / 作為應用程式位置。

  6. 輸入 dist 作為輸出位置。

  7. 選取 建立。

    顯示 Azure Static Web Apps 設定的螢幕擷取畫面

最多可能需要 5 分鐘才能看到您的程式碼發佈在網站上。

若要檢視在 Static Web Apps 上執行的 API 中心入口網站，請從您在 Azure 入口網站中建立的靜態 Web 應用程式資源的 [概觀] 索引標籤，選取 [在瀏覽器中檢視應用程式]。

此螢幕擷取畫面顯示已部署的 Web 入口網站

設定角色型存取控制

透過角色型存取控制，管理員對於組織 API 中心內的 API 和資產將可完全控制其存取權限的指派。

注意

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

若要存取 API 中心內的 API，使用者必須登入入口網站，且必須具有限定於您的 API 中心的必要權限。 若要啟用登入，請依照這裡提供的步驟，將 Azure API 中心資料讀者角色指派給組織中的使用者或群組。