共用方式為


在 API 中心啟用 API 分析 - 自我管理

本文說明如何手動設定 Lint 分析引擎和觸發程序,在 Azure API 中心啟用 API 分析。 這些功能會分析您的 API 定義,以遵守組織樣式規則,同時產生個別和摘要報告。 API 分析可協助您識別和更正 API 定義中的常見錯誤和不一致。

注意

在預覽版中,Azure API 中心 會自動設定 預設 Linting 引擎和 API 分析的相依性。 如果您如本文所述啟用自我管理分析,則會覆寫這些內建功能。

案例概觀

在此案例中,您會使用光譜開放原始碼 Lint 分析引擎來分析 API 中心內的 API 定義。 Azure Functions 應用程式會執行 Lint 分析引擎,以回應 API 中心內的事件。 光譜會檢查 JSON 或 YAML 規格文件中定義的 API 是否符合可自訂 API 樣式指南中的規則。 系統會產生可在 API 中心檢視的分析報告。

下圖顯示在您的 API 中心內啟用 Lint 分析和分析的步驟。

顯示 API Lint 分析如何在 Azure API 中心內運作的圖表。

  1. 部署在 API 定義上執行光譜 Lint 分析引擎的 Azure Functions 應用程式。

  2. 在 Azure API 中心內設定事件訂閱以觸發函數應用程式。

  3. 事件會藉由在 API 中心內新增或取代 API 定義來觸發。

  4. 在接收事件時,函數應用程式會叫用光譜 Lint 分析引擎。

  5. Lint 分析引擎會檢查定義中所定義的 API 是否符合組織的 API 樣式指南,並產生報告。

  6. 在 API 中心內檢視分析報告。

部署 Lint 分析引擎和事件訂閱的選項

本文提供兩個選項,可在 API 中心內部署 Lint 分析引擎和事件訂閱:

  • 自動化部署 - 使用 Azure Developer CLI (azd) 進行 Lint 分析基礎結構的單步驟部署。 針對簡化的部署程序,建議使用此選項。

  • 手動部署 - 遵循逐步指導來部署 Azure Functions 應用程式並設定事件訂閱。 如果您想要手動部署和管理資源,建議您使用此選項。

限制

  • Lint 分析目前僅支援 JSON 或 YAML 規格檔案,例如 OpenAPI 或 AsyncAPI 規格文件。
  • Lint 分析引擎預設會使用內建spectral:oas規則集。 若要擴充規則集或建立自訂 API 樣式指南,請參閱光譜 GitHub 存放庫
  • 叫用 Lint 分析的 Azure 函數應用程式會個別收費,而您負責管理和維護它。

必要條件

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

  • 在訂閱中註冊的事件方格資源提供者。 如果您需要註冊事件方格資源提供者,請參閱訂閱 Azure 事件方格的合作夥伴所發佈的事件

  • 對於 Azure CLI:

    注意

    az apic 命令需要 apic-extension Azure CLI 延伸模組。 如果您尚未使用 az apic 命令,則可以在執行第一個 az apic 命令時動態安裝延伸模組,也可以手動安裝延伸模組。 深入了解 Azure CLI 延伸模組

    如需 apic-extension 中的最新變更和更新,請參閱版本資訊

    注意

    本文中的 Azure CLI 命令範例可在 PowerShell 或 Bash 殼層中執行。 若因變數語法不同而有需要,可參考為兩個殼層提供的個別命令範例。

azd 部署 Azure Functions 應用程式和事件訂閱

本節提供使用 Azure Developer CLI 來設定 Azure Functions 應用程式和事件訂閱的自動化步驟,以在您的 API 中心啟用 Lint 分析和分析。 您也可以手動設定資源。

此選項的其他必要條件

使用 azd 執行範例

  1. 複製 GitHub 存放庫, 並在 Visual Studio Code 中開啟。

  2. 將目錄變更為存放庫中的 APICenter-Analyzer 資料夾。

  3. resources/rulesets 資料夾中,您可以找到 oas.yaml 檔案。 此檔案會反映您目前的 API 樣式指南,並且可根據您的組織需要和要求進行修改。

  4. 在 Azure Developer CLI 和 Azure CLI 中,使用下列命令進行驗證:

    azd auth login
    
    az login
    
  5. 執行下列命令,將 Lint 分析基礎結構部署至您的 Azure 訂用帳戶。

    azd up
    
  6. 依照提示提供必要的部署資訊和設定,例如環境名稱和 API 中心名稱。 如需詳細資訊,請參閱使用 Azure Developer CLI (azd) 執行範例

    注意

    部署可能需要幾分鐘的時間。

  7. 部署完成後,在 Azure 入口網站中瀏覽至您的 API 中心。 在左側功能表中選取 [事件]>[事件訂閱],以檢視已建立的事件訂閱。

此時您可以將 API 定義檔上傳至 API 中心,以觸發事件訂閱及執行 Lint 分析引擎。

設定 Azure Functions 應用程式和事件訂閱的手動步驟

本節提供手動部署步驟,設定 Azure Functions 應用程式和事件訂閱,以在您的 API 中心啟用 Lint 分析和分析。 您也可以使用 Azure Developer CLI 進行自動化部署。

此選項的其他必要條件

步驟 1: 部署 Azure Functions 應用程式

若要部署在 API 定義上執行 Lint 分析函式的 Azure Functions 應用程式:

  1. 複製 GitHub 存放庫, 並在 Visual Studio Code 中開啟。

  2. resources/rulesets 資料夾中,您可以找到 oas.yaml 檔案。 此檔案會反映您目前的 API 樣式指南,並且可根據您的組織需要和要求進行修改。

  3. 或者,在本機執行函數應用程式以進行測試。 如需詳細資訊,請參閱存放庫中的讀我檔案

  4. 將函數應用程式部署至 Azure。 如需步驟,請參閱快速入門:使用 Visual Studio Code 搭配 TypeScript 在 Azure 中建立函式

    注意

    部署函數應用程式可能需要幾分鐘的時間。

  5. 登入 Azure 入口網站並移至函數應用程式。

  6. 在 [概觀] 頁面上,檢查下列詳細資料:

    • 確認函數應用程式的 [狀態] 為 [執行中]
    • 在 [函式] 下,確認 apicenter-analyzer 函式的 [狀態] 為 [已啟用]

    入口網站中函數應用程式的螢幕擷取畫面。

步驟 2。 在函數應用程式中設定受控識別

若要讓函數應用程式存取 API 中心,請設定函數應用程式的受控識別。 下列步驟示範如何使用 Azure 入口網站或 Azure CLI 為函數應用程式啟用和設定系統指派的受控識別。

  1. 在 Azure 入口網站中,瀏覽至您的函數應用程式,然後選取 [設定] 區段下的 [身分識別]
  2. 在 [系統指派] 索引標籤中,將 [狀態] 設定為 [開啟],然後選取 [儲存]

現在已啟用受控識別,請將 Azure API 中心合規性管理員角色指派給它,以存取 API 中心。

  1. Azure 入口網站中,瀏覽至您的 API 中心,然後選取 [存取控制 (IAM)]
  2. 選取 [新增] > [新增角色指派]
  3. 選取 [作業函式角色],然後選取 [Azure API 中心合規性管理員]。 選取 [下一步]。
  4. 在 [成員] 頁面上的 [指派存取權的對象] 中,選取 [受控識別] > [+ 選取成員]。
  5. 在 [選取受控識別] 頁面上,搜尋並選取函數應用程式的受控識別。 按一下 [選取],然後按 [下一步]
  6. 檢閱角色指派,然後選取 [檢閱 + 指派]

步驟 3: 在您的 API 中心內設定事件訂閱

現在,在您的 API 中心內建立事件訂閱,以在上傳或更新 API 定義檔案時觸發函數應用程式。 下列步驟示範如何使用 Azure 入口網站或 Azure CLI 建立事件訂閱。

  1. Azure 入口網站中,瀏覽至您的 API 中心,然後選取 [事件]

  2. 在 [開始使用] 索引標籤上,選取 [Azure 函式]

  3. 在 [建立事件訂閱] 頁面上,執行下列操作:

    1. 輸入事件訂閱的描述性名稱,然後選取 [事件方格結構描述]

    2. 在 [主題詳細資料] 中,輸入您選擇的系統主題名稱

    3. 在 [事件類型] 中,選取下列事件:

      • 已新增 API 定義
      • 已更新 API 定義
    4. 在 [端點詳細資料] 中,選取 [Azure 函式] > [設定端點]

    5. 在 [選取 Azure 函式] 頁面上,選取函數應用程式和您所設定的 apicenter-linter 函式。 按一下 [確認選取項目]

    6. 選取 建立

      在入口網站中建立事件訂閱的螢幕擷取畫面。

  4. 選取 [事件訂閱] 索引標籤,然後選取 [重新整理]。 確認事件訂閱的 [佈建狀態] 為 [成功]

    入口網站中事件訂閱狀態的螢幕擷取畫面。

注意

事件訂閱可能需要一些時間才能傳播至函數應用程式。

在您的 API 中心內觸發事件

若要測試事件訂閱,請嘗試在 API 中心內上傳或更新與 API 版本相關聯的 API 定義檔案。 例如,上傳 OpenAPI 或 AsyncAPI 文件。 觸發事件訂閱之後,函數應用程式會叫用 API Lint 分析引擎來分析 API 定義。

若要確認事件訂閱已觸發:

  1. 瀏覽至您的 API 中心,然後選取左側功能表中的 [事件]

  2. 選取 [事件訂閱] 索引標籤,然後選取函數應用程式的事件訂閱。

  3. 檢閱計量以確認事件訂閱已觸發,且已成功叫用 Lint 分析。

    入口網站中事件訂閱計量的螢幕擷取畫面。

    注意

    計量可能需要幾分鐘的時間才會出現。

分析 API 定義之後,Lint 分析引擎會根據已設定的 API 樣式指南來產生報告。

檢視 API 分析報告

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

在入口網站中,您也可以檢視 API 中心內所有 API 定義的分析報告摘要。

API 定義的分析報告

若要在 API 中心內檢視 API 定義的分析報告:

  1. 在入口網站中,瀏覽至您在 API 中心內新增或更新 API 定義的 API 版本。
  2. 在左側功能表中的 [詳細資料] 底下,選取 [定義]
  3. 選取您上傳或更新的 API 定義。
  4. 選取 [分析] 索引標籤。入口網站中 API 定義的 [分析] 索引標籤螢幕擷取畫面。

API 分析報告隨即開啟,並根據已設定的 API 樣式指南顯示 API 定義以及錯誤、警告和資訊。 下列螢幕擷取畫面顯示 API 分析報告的範例。

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

API 分析摘要

若要檢視 API 中心內所有 API 定義的分析報告摘要:

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

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

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

深入了解事件方格: