共用方式為

分析 API 中心中的 API - Microsoft受控

  • 發行項

貴組織的 API 中心 包含內建、Microsoft管理的 Linting 功能（預覽），以分析 API 定義以遵守組織樣式規則，同時產生個別和摘要報告。 API 分析可識別並協助您更正 API 定義中的常見錯誤和不一致。

使用 API 分析：

  • 每當您新增或更新 API 定義時，Azure API 中心會自動分析您的 API 定義。 根據預設，API 定義會與 光譜：oas 規則集 （API 樣式指南）搭配。
  • API 分析報告會在 Azure 入口網站 中產生，其中顯示 API 定義如何符合樣式指南。
  • 您可以使用適用於 Visual Studio Code 的 Azure API 中心延伸模組，在本機自定義及測試您自己的 API 樣式指南，然後將它部署至 API 中心。

重要

如果您想要的話，您可以使用自定義 Azure 函式來啟用 自我管理 Linting 和分析，並覆寫內建功能。 在使用受控 API 分析之前，請先停用用於自我管理 Linting 的任何函式。

限制

  • 目前只會分析 JSON 或 YAML 格式的 OpenAPI 和 AsyncAPI 規格檔。
  • 目前，您可設定單一規則集，其會套用至 API 中心中的所有 OpenAPI 定義。
  • 分析的 API 定義數目上限有 限制 。 分析可能需要幾分鐘的時間，最多 24 小時才能完成。

必要條件

檢視 API 分析報告

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

在 API 分析報告中，也檢閱用於分析的規則集，以及 Linting 傳遞的歷程記錄。

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

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

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

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

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

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

    提示

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

自訂規則集

您可以使用適用於 Visual Studio Code 的 Azure API 中心延伸模組來自定義 API 中心的預設規則集，或將它取代為組織的 API 樣式指南。 例如，您可以擴充規則集或新增自訂函式。

若要自訂或取代規則集：

  1. 在 Visual Studio Code 中，從活動列選取 Azure API 中心圖示。
  2. .api-center-rules開啟工作資料夾根目錄的資料夾。
  3. 在 API 中心資源的資料夾中，開啟 ruleset.yml 檔案。
  4. 視需要修改或取代內容。
  5. 將變更儲存至 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)。

提示

貴組織中的 API 開發人員也可以在 API 中心註冊 API 之前，使用此本機 Linting 功能來協助改善其 API 定義。

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

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

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

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

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

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

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

相關內容