分享方式：

在 API 中心啟用 API 分析 - Microsoft 管理

  • 文章

本文會說明如何在 Azure API 中心啟用 API 分析，而無需自行管理 API (預覽)。 API 分析提供 Lint 分析功能，以在貴組織的 API 中心分析 API 定義。 Lint 分析可確保您的 API 定義遵守組織樣式規則，同時產生個別和摘要報表。 使用 API 分析來識別和更正 API 定義中的常見錯誤和不一致。

重要

API 中心的受控 API 分析會自動設定 Lint 分析引擎和必要的相依性。 您也可以使用自訂 Azure 函式來手動啟用 Lint 分析和分析。 啟用受控 API 分析之前，停用用於手動 Lint 分析的任何函式。

在此情節中：

  1. 使用適用於 Azure API 中心的 Visual Studio Code 延伸模組，在您的 API 中心新增 Lint 分析規則集 (API 樣式指南)。
  2. 當您新增或更新 API 定義時，Azure API 中心會自動執行 Lint 分析。 當您將規則集部署至 API 中心時，也會針對所有 API 定義觸發它。
  3. 檢閱 Azure 入口網站中的 API 分析報表，以了解您的 API 定義符合樣式指南的程度。
  4. 可選擇自訂組織 API 的規則集。 在本機測試自訂規則集後，再將其部署至您的 API 中心。

限制

  • 目前只會分析 JSON 或 YAML 格式的 OpenAPI 規格文件。
  • 根據預設，您可以使用 spectral:oas 規則集來啟用分析。 若要深入了解內建規則，請參閱 Spectral GitHub 存放庫。
  • 目前，您可設定單一規則集，其會套用至 API 中心中的所有 OpenAPI 定義。
  • 以下是每 4 小時進行 Lint 分析的 API 定義數目上限：
    • 免費層：10
    • 標準層：100

必要條件

使用 Visual Studio Code 啟用 API 分析

若要使用預設 Lint 分析規則集來啟用 API 分析：

  1. 在 Visual Studio Code 中，開啟您將用來管理 Azure API 中心規則集的資料夾。

  2. 選取活動列中的 Azure API 中心圖示。

  3. 在 [API 中心] 窗格中，展開要在其中啟用 API 分析的 API 中心資源。

  4. 以滑鼠右鍵按一下 [規則]，然後選取 [啟用 API 分析]。

    在 Visual Studio Code 中啟用 API Lint 分析的螢幕擷取畫面。

成功啟用 API 分析之後，會有訊息通知您。 API 中心的資料夾會在 .api-center-rules 中建立，位於工作資料夾的根目錄。 API 中心的資料夾包含：

  • ruleset.yml 檔案，定義 Lint 分析引擎所使用的預設 API 樣式指南。
  • functions 資料夾，其中包含可用來擴充規則集的範例自訂函式。

啟用分析後，Lint 分析引擎會根據預設規則集分析 API 中心中的 API 定義，並產生 API 分析報表。

檢視 API 分析報告

在 Azure 入口網站中檢視 API 定義的分析摘要和分析報表。 分析 API 定義之後，報表會根據已設定的 API 樣式指南列出錯誤、警告和資訊。

若要在 API 中心檢視分析摘要：

  1. 在入口網站中，瀏覽至您的 API 中心。

  2. 在左側功能表中的 [治理] 底下，選取 [API 分析]。 摘要隨即出現。

    入口網站中 API 分析摘要的螢幕擷取畫面。

  3. 可選擇選取 API 定義的 API 分析報表圖示。 定義的 API 分析報表隨即出現，如下列螢幕擷取畫面所示。

    入口網站中 API 分析報告的螢幕擷取畫面。

    提示

    您也可以從 API 定義的功能表列選取 [分析]，以檢視 API 分析報表。

自訂規則集

您可以自訂預設規則集，或將其取代為組織的 API 樣式指南。 例如，您可以擴充規則集或新增自訂函式。

若要自訂或取代規則集：

  1. 在 Visual Studio Code 中，開啟工作資料夾根目錄的 .api-center-rules 資料夾。
  2. 在 API 中心資源的資料夾中，開啟 ruleset.yml 檔案。
  3. 視需要修改或取代內容。
  4. 將變更儲存至 ruleset.yml。

在本機測試規則集

將自訂規則集部署至您的 API 中心之前，請先在本機進行驗證。 適用於 Visual Studio Code 的 Azure API 中心延伸模組可透過 Spectral 提供對 API 規格 Lint 分析的整合式支援。

  1. 在 Visual Studio Code 中，使用 Ctrl+Shift+P 鍵盤快速鍵以開啟命令選擇區。

  2. 輸入 Azure API 中心：設定作用中 API 樣式指南，然後按 Enter 鍵。

  3. 選擇 [選取本機檔案]，並指定您自訂的 ruleset.yml 檔案。 按 Enter 鍵。

    此步驟會讓自訂規則集成為 Lint 分析的使用中 API 樣式指南。

現在，當您開啟 OpenAPI 型 API 定義檔案時，會在 Visual Studio Code 中自動觸發本機 Lint 分析作業。 結果會在編輯器中內嵌顯示，以及在 [問題] 視窗中顯示 ([檢視] > [問題] 或 Ctrl+Shift+M)。

在 Visual Studio Code 中以 Lint 工具分析 API 定義的螢幕擷取畫面。

檢閱 Lint 分析結果。 對規則集進行任何必要的調整，並繼續在本機進行測試，直到其依照您想要的方式執行為止。

將規則集部署至您的 API 中心

若要將自訂規則集部署至您的 API 中心：

  1. 在 Visual Studio Code 中，從活動列選取 Azure API 中心圖示。
  2. 在 [API 中心] 窗格中，展開在其中已自訂規則集的 API 中心資源。
  3. 以滑鼠右鍵按一下 [規則]，然後選取 [將規則部署至 API 中心]。

成功將規則部署至 API 中心之後，會有訊息通知您。 Lint 分析引擎會使用更新的規則集來分析 API 定義。

若要查看使用更新的規則集進行 Lint 分析的結果，請在入口網站中檢視 API 分析報表。

相關內容