在 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 分析和分析的步驟。

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：

  • 在 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 延伸模組。

  如需 apic-extension 中的最新變更和更新，請參閱版本資訊。 某些功能可能需要預覽或特定版本的擴充功能。

  注意

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

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

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

此選項的其他必要條件

• 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 中，使用下列命令進行驗證：

   Azure CLI

   azd auth login
   
   az login
   

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

   Azure

   azd up
   

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

   注意

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

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

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

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

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

此選項的其他必要條件

• 搭配 Azure Functions 延伸模組 v1.10.4 或更新版本的 Visual Studio Code。

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

Azure CLI

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

   Azure CLI

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

   Azure CLI

   # 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>。

   Azure CLI

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

   Azure CLI

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

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

   Azure CLI

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

   Azure CLI

   # 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>。

   Azure CLI

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

   Azure CLI

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

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

   Azure CLI

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

   Azure CLI

   # 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 定義的事件。

   Azure CLI

   #! /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
   

   Azure CLI

   # 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 命令來取得詳細資料。 例如：

   Azure CLI

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

注意

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

在您的 API 中心內觸發事件

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

• 如需將 API、API 版本和 API 定義新增至 API 中心的詳細步驟，請參閱教學課程：在 API 中心內註冊 API。
• 若要使用 Azure CLI 上傳 API 定義檔案來建立 API，請參閱從規格檔案註冊 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 定義的分析報告摘要：

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

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

   

相關內容

深入了解事件方格：

• 在 API 中心啟用 API 分析 - Microsoft 受控
• Azure 事件方格中的系統主題
• 事件方格推送傳遞 - 概念
• Azure API 中心的事件方格結構描述