在 API 中心啟用 API 控管的 Linting 和分析

本文說明如何啟用Linting分析組織 API 中心中的 API 定義，以符合組織的 API 樣式規則。 Linting 會產生可在 API 中心存取的分析報告。 使用 API linting 和分析來偵測 API 定義中的常見錯誤和不一致。

案例概觀

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

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

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

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

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

4. 在接收事件時，函式應用程式會叫用光譜 Linting 引擎。

5. Linting 引擎會檢查定義中定義的 API 是否符合組織的 API 樣式指南，併產生報告。

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

部署 Linting 引擎和事件訂用帳戶的選項

本文提供兩個選項，可在 API 中心部署 linting 引擎和事件訂用帳戶：

• 自動化部署 - 使用 Azure 開發人員 CLI （azd） 進行 Linting 基礎結構的單步驟部署。 針對簡化的部署程式，建議使用此選項。

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

限制

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

必要條件

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

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

• 對於 Azure CLI：

  • 在 Azure Cloud Shell 中使用 Bash 環境。 如需詳細資訊，請參閱 Azure Cloud Shell 中的 Bash 快速入門。

    

  • 若要在本地執行 CLI 參考命令，請安裝 Azure CLI。 若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。 如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。

    • 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。 請遵循您終端機上顯示的步驟，完成驗證程序。 如需其他登入選項，請參閱使用 Azure CLI 登入。

    • 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。 如需擴充功能詳細資訊，請參閱使用 Azure CLI 擴充功能。

    • 執行 az version 以尋找已安裝的版本和相依程式庫。 若要升級至最新版本，請執行 az upgrade。

  注意

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

  注意

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

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

本節提供使用 Azure 開發人員 CLI 來設定 Azure Functions 應用程式和事件訂用帳戶的自動化步驟，以在您的 API 中心啟用 Linting 和分析。 您也可以手動設定資源。

此選項的其他必要條件

• Azure Developer CLI (azd)

使用 執行範例 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 中心啟用 Linting 和分析。 您也可以使用 Azure 開發人員 CLI 進行自動化部署。

此選項的其他必要條件

• 具有 Azure Functions 擴充功能 v1.10.4 或更新版本的 Visual Studio Code。

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

若要部署在 API 定義上執行 Linting 函式的 Azure Functions 應用程式：

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

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

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

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

   注意

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

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. 檢閱角色指派，然後選取 [檢閱 + 指派]。

Azure CLI

1. 使用 az functionapp identity assign 命令啟用函式應用程式的系統指派 身分識別。 將和 <resource-group-name> 取代<function-app-name>為您的函式應用程式名稱和資源組名。 下列命令會將系統指派受控識別的主體標識符儲存在變數中 principalID 。

   #! /bin/bash
   principalID=$(az functionapp identity assign --name <function-app-name> \
       --resource-group <resource-group-name> --identities [system] \
       --query "principalId" --output tsv)
   

   # PowerShell syntax
   $principalID=$(az functionapp identity assign --name <function-app-name> `
       --resource-group <resource-group-name> --identities [system] `
       --query "principalId" --output tsv)
   

2. 取得 API 中心的資源識別碼。 以您的 API 中心名稱與資源群組名稱取代 <apic-name> 與 <resource-group-name> 。

   #! /bin/bash
   apicID=$(az apic service show --name <apic-name> --resource-group <resource-group-name> \
       --query "id" --output tsv)
   

   # PowerShell syntax
   $apicID=$(az apic service show --name <apic-name> --resource-group <resource-group-name> `
       --query "id" --output tsv)
   

3. 使用 az role assignment create 命令，在 API 中心中將函式應用程式的受控識別指派為 Azure API 中心合規性管理員角色。

   #! /bin/bash
   az role assignment create \
       --role "Azure API Center Compliance Manager" \
       --assignee-object-id $principalID \
       --assignee-principal-type ServicePrincipal \
       --scope $apicID 
   

   # PowerShell syntax
   az role assignment create `
       --role "Azure API Center Compliance Manager" `
       --assignee-object-id $principalID `
       --assignee-principal-type ServicePrincipal `
       --scope $apicID 
   

步驟 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. 選取 [ 事件訂閱] 索引標籤，然後選取 [ 重新整理]。 確認 事件訂用帳戶的布建狀態 為 [成功]。

   

Azure CLI

1. 取得 API 中心的資源識別碼。 以您的 API 中心名稱與資源群組名稱取代 <apic-name> 與 <resource-group-name> 。

   #! /bin/bash
   apicID=$(az apic service show --name <apic-name> --resource-group <resource-group-name> \
       --query "id" --output tsv)
   

   # PowerShell syntax
   $apicID=$(az apic service show --name <apic-name> --resource-group <resource-group-name> `
       --query "id" --output tsv)
   

2. 取得函式應用程式中函式的資源識別碼。 在此範例中，函式名稱為 apicenter-analyzer。 以您的函式應用程式名稱與資源群組名稱取代 <function-app-name> 與 <resource-group-name> 。

   #! /bin/bash
   functionID=$(az functionapp function show --name <function-app-name> \
       --function-name apicenter-analyzer --resource-group <resource-group-name> \
       --query "id" --output tsv)
   

   # PowerShell syntax
   $functionID=$(az functionapp function show --name <function-app-name> `
       --function-name apicenter-analyzer --resource-group <resource-group-name> `
       --query "id" --output tsv)
   

3. 使用 az eventgrid event-subscription create 命令建立事件訂用帳戶。 所建立的訂用帳戶包含用於新增或更新 API 定義的事件。

   #! /bin/bash
   az eventgrid event-subscription create --name MyEventSubscription \
       --source-resource-id "$apicID" --endpoint "$functionID" \
       --endpoint-type azurefunction --included-event-types \
       Microsoft.ApiCenter.ApiDefinitionAdded Microsoft.ApiCenter.ApiDefinitionUpdated
   

   # PowerShell syntax
   az eventgrid event-subscription create --name MyEventSubscription `
       --source-resource-id "$apicID" --endpoint "$functionID" `
       --endpoint-type azurefunction --included-event-types `
       Microsoft.ApiCenter.ApiDefinitionAdded Microsoft.ApiCenter.ApiDefinitionUpdated
   

   命令輸出會顯示事件訂閱的詳細數據。 您也可以使用 az eventgrid event-subscription show 命令來取得詳細數據。 例如：

   az eventgrid event-subscription show --name MyEventSubscription --source-resource-id "$apicID"
   

注意

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

在您的 API 中心觸發事件

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

• 如需將 API、API 版本和 API 定義新增至 API 中心的詳細步驟，請參閱 教學課程：在 API 中心註冊 API。
• 若要使用 Azure CLI 上傳 API 定義檔案來建立 API，請參閱 從規格檔案註冊 API。

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

1. 流覽至您的 API 中心，然後選取 左側功能表中的事件 。

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

3. 檢閱計量以確認事件訂用帳戶已觸發，且已成功叫用Linting。

   

   注意

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

分析 API 定義之後，Linting 引擎會根據已設定的 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 定義的分析報告摘要：

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

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

   

相關內容

深入瞭解事件方格：

• Azure 事件方格 中的系統主題
• 事件方格推送傳遞 - 概念
• Azure API 中心的事件方格架構