貴組織的 API 中心 包含內建的、由 Microsoft 管理的程式碼檢查功能（預覽），可以用來分析 API 定義是否符合組織樣式規則，並能產生個別報告和摘要報告。 API 分析可識別並協助您更正 API 定義中的常見錯誤和不一致。
使用 API 分析：
- 每當您新增或更新 API 定義時，Azure API 中心會自動分析您的 API 定義。 API 定義的 linting 預設會使用
spectral:oas規則集（API 風格指南）來完成。 - API 分析報告會在 Azure 入口網站 中產生，其中顯示 API 定義如何符合樣式指南。
- 使用分析設定檔指定被分析 API 的規則集與篩選條件。 使用 Azure API Center 擴充功能在 Visual Studio Code 中設定設定檔的規則集。
重要
如果您想要的話，您可以使用自定義 Azure 函式來啟用 自我管理 Linting 和分析，並覆寫內建功能。 在使用受控 API 分析之前，請先停用任何用於自我管理 linting 的函式。
限制
- 目前只會分析 JSON 或 YAML 格式的 OpenAPI 和 AsyncAPI 規格檔。
- 分析剖面的數量及 API 定義的最大數量都有 限制 。 分析可能需要幾分鐘的時間，最多 24 小時才能完成。
必要條件
- Azure 訂用帳戶中的 API 中心。 如果你還沒有，請參考 快速入門：建立你的 API 中心。
- 若要自定義規則集， Visual Studio Code 和下列 Visual Studio Code 延伸模組：
檢視 API 分析報告
在 Azure 入口網站中檢視 API 定義的分析摘要和分析報表。 分析 API 定義之後，報表會根據已設定的 API 樣式指南列出錯誤、警告和資訊。
在 API 分析報告中，也檢閱用於分析的規則集，以及 Linting 傳遞的歷程記錄。
若要在 API 中心檢視分析摘要：
在入口網站中，瀏覽至您的 API 中心。
在左側功能表中的 [治理] 底下，選取 [API 分析]。 摘要隨即出現。
可選擇點選 API 定義的 API 分析報表圖示。 定義的 API 分析報表隨即出現，如下列螢幕擷取畫面所示。
提示
您也可以從 API 定義的功能表列選取 [分析]，以檢視 API 分析報表。
管理分析設定檔
Azure API 中心使用 analysis profile來進行 linting 和分析 API。 分析設定檔指定規則集，並可選擇篩選分析的 API 條件。 預設分析設定檔將該 spectral:oas 規則集套用於所有 OpenAPI 與 AsyncAPI 定義。
你可以自訂規則集並在預設設定檔中定義篩選條件，或者建立新的設定檔。 例如，你可能想用一個設定檔來管理正在開發中的 API，另一個設定檔用於生產中的 API。
備註
在 API 中心的標準方案中，你可以建立最多三個分析剖面。 免費方案僅支援單一設定檔。
要建立分析檔案：
- 在 Azure 入口網站中，流覽至您的 API 中心。
- 在左側選單中，於 治理下，選擇 API 分析>管理分析設定檔>+建立分析設定檔。
- 在 「建立新分析檔案 」面板中，輸入該檔案 的名稱 與 描述 。
- 在 規則集中，該規則集的分析器類型（linting engine）會顯示出來。 目前僅支援 Spectral。
- 在 定義過濾器條件中，為該設定檔所應用的 API 定義新增一個或多個過濾器條件。
- 選擇創建。
建立設定檔並建立規則集架構。 要查看目前規則集，選擇設定檔，然後在上下文（...）選單中選擇 「檢視規則集」。
若要自訂規則集，請繼續閱讀以下章節。
自訂個人檔案的規則集
使用 Azure API Center 的 Visual Studio Code 擴充功能來自訂設定檔的規則集。 自訂規則集並在本地測試後，你可以部署回你的 API 中心。
- 在 Visual Studio Code 中，從活動列選取 Azure API 中心圖示。
- 在 API 中心窗格中，展開你正在使用的 API 中心資源，並展開「 設定檔」。
- 展開你想修改的設定檔，然後選擇
ruleset.yaml。 - 視需要修改或取代內容。
- 將變更儲存至
ruleset.yaml。
在本機測試規則集
將自訂規則集部署至您的 API 中心之前，請先在本機進行驗證。 適用於 Visual Studio Code 的 Azure API 中心延伸模組可透過 Spectral 提供對 API 規格 Lint 分析的整合式支援。
在 Visual Studio Code 中，使用 Ctrl+Shift+P 鍵盤快速鍵以開啟命令選擇區。
輸入 Azure API 中心：設定作用中 API 樣式指南，然後按 Enter 鍵。
選擇 [選取本機檔案]，並指定您自訂的
ruleset.yaml檔案。 按 Enter 鍵。此步驟使自訂規則集合成為用於本地 linting 的主要 API 樣式指南。
現在，當您在 Visual Studio Code 中開啟基於 OpenAPI 的 API 定義檔案時，會自動觸發本機語法檢查操作。 結果會在編輯器中內嵌顯示，以及在 [問題] 視窗中顯示 ([檢視] > [問題] 或 Ctrl+Shift+M)。
提示
貴組織中的 API 開發人員也可以在 API 中心註冊 API 之前，使用此本地程式碼檢查功能來協助改善他們的 API 定義。
檢閱 Lint 分析結果。 對規則集進行任何必要的調整，並繼續在本機進行測試，直到其依照您想要的方式執行為止。
將規則集部署至您的 API 中心
若要將自訂規則集部署至您的 API 中心：
- 在 Visual Studio Code 中，從活動列選取 Azure API 中心圖示。
- 在 [API 中心] 窗格中，展開在其中已自訂規則集的 API 中心資源。
- 展開 個人資料。
- 右鍵點擊你自訂規則集的設定檔，然後選擇 「部署規則到API Center」。
成功將規則部署至 API 中心之後，會有訊息通知您。 linting 引擎利用更新後的規則集來分析設定檔中的 API 定義。
若要查看使用更新規則集進行 Lint 檢查的結果，請在平台中檢視 API 分析報表。
相關內容
- 若要深入瞭解預設的內建規則集，請參閱 光譜 GitHub 存放庫。
- 在 API 中心啟用 API 分析 - 自我管理