你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

本文介绍如何通过手动设置 linting 引擎和触发器在 Azure API 中心启用 API 分析。 API 分析提供 linting 功能，用于在组织的 API 中心中分析 API 定义。 Linting 确保 API 可k义遵守组织的样式规则，从而同时生成单个报表和摘要报表。 使用 API 分析识别和更正 API 定义中的常见错误和不一致。

注意

在预览版中，Azure API 中心还可以自动设置 linting 引擎以及任何必需的依赖项和触发器。 了解详细信息。

场景概述

在此方案中，你将使用 Spectral 开源 linting 引擎分析 API 中心中的 API 定义。 Azure Functions 应用运行 linting 引擎以响应 API 中心的事件。 Spectral 会检查 JSON 或 YAML 规范文档中定义的 API 是否符合可自定义 API 样式指南中的规则。 可在 API 中心查看生成的分析报表。

下图展示了在 API 中心启用 linting 和分析的步骤。

1. 部署对 API 定义运行 Spectral linting 引擎的 Azure Functions 应用。

2. 在 Azure API 中心配置事件订阅以触发函数应用。

3. 通过在 API 中心添加或替换 API 定义来触发事件。

4. 接收事件时，函数应用将调用 Spectral 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 样式指南，请参阅 Spectral GitHub 存储库。
• 调用 linting 的 Azure 函数应用单独收费，你负责管理和维护它。

先决条件

• Azure 订阅中的 API 中心。 如果尚未创建 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 命令需要 Azure CLI 扩展 apic-extension。 如果尚未使用 az apic 命令，则可以在运行第一个 az apic 命令时动态安装扩展，也可以手动安装扩展。 详细了解 Azure CLI 扩展。

  请参阅最新更改的发行说明和 apic-extension 中的更新。

  注意

  本文中的 Azure CLI 命令示例可以在 PowerShell 或 bash shell 中运行。 由于不同的变量语法，需要为两个 shell 提供单独的命令示例。

azd Azure Functions 应用和事件订阅的部署

本部分提供了使用 Azure Developer 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. 运行以下命令，将 linting 基础结构部署到 Azure 订阅。

   azd up
   

6. 按照提示提供所需的部署信息和设置，例如环境名称和 API 中心名称。 有关详细信息，请参阅“使用 Azure Developer CLI (azd) 运行示例”。

   注意

   部署可能需要几分钟。

7. 部署完成后，在 Azure 门户中导航到 API 中心。 在左侧菜单中，选择“事件>事件订阅”以查看已创建的事件订阅。

现在可以将 API 定义文件上传到 API 中心，触发事件订阅并运行 linting 引擎。

配置 Azure Functions 应用和事件订阅的手动步骤

本部分提供手动部署步骤，用于配置 Azure Functions 应用和事件订阅，以便在 API 中心启用 linting 和分析。 还可以使用 Azure Developer CLI 进行自动部署。

此选项的其他先决条件

• Visual Studio Code 与 Azure Functions 扩展 v1.10.4 或更高版本。

步骤 1. 部署 Azure Functions 应用

若要部署对 API 定义运行 linting 函数的 Azure Functions 应用：

1. 克隆 GitHub 存储库并在 Visual Studio Code 中打开它。

2. 在 resources/rulesets 文件夹中，可以找到一个 oas.yaml 文件。 此文件反映了你当前的 API 样式指南，你可以根据组织需求和要求修改它。

3. （可选）在本地运行函数应用以对其进行测试。 有关详细信息，请参阅存储库中的 README 文件。

4. 将函数应用部署到 Azure。 如需步骤，请参阅快速入门：在 Azure 中使用 Visual Studio Code 创建 TypeScript 函数。

   注意

   部署函数应用可能需要几分钟时间。

5. 登录 Azure 门户并转到函数应用。

6. 在“概述”页上，检查以下详细信息：

   • 确认函数应用的“状态”为“正在运行”。
   • 在“Functions”下，确认“apicenter-analyzer”函数的状态为“启用”。

   

步骤 2. 在函数应用中配置托管标识

若要使函数应用能够访问 API 中心，请为函数应用配置托管标识。 以下步骤演示如何使用 Azure 门户或 Azure CLI 为函数应用启用和配置系统分配的托管标识。

门户

1. 在 Azure 门户中，导航到函数应用，然后选择“设置”部分下的“标识”。
2. 在“系统分配”选项卡中，将“状态”设置为“开”，然后选择“保存”。

启用托管标识后，请为其分配 Azure API 中心合规经理角色以访问 API 中心。

1. 在 Azure 门户中，导航到 API 中心并选择“访问控制(IAM)”。
2. 选择“+ 添加 > 添加角色分配”。
3. 选择“职能角色”，然后选择“Azure API Center 合规经理”。 选择下一步。
4. 在“成员”页上的“将访问权限分配给”中，选择“托管标识 > + 选择成员”。
5. 在“选择托管标识”页上，搜索并选择函数应用的托管标识。 单击“选择”，然后单击“下一步”。
6. 查看角色分配，然后选择“查看 + 分配”。

Azure CLI

1. 使用 az functionapp identity assign 命令启用函数应用的系统分配标识。 将 <function-app-name> 和 <resource-group-name> 替换为你的函数应用名称和资源组名称。 以下命令将系统分配的托管标识的主体 ID 存储在 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 中心的资源 ID。 将 <apic-name> 和 <resource-group-name> 替换为你的 API 中心名称和资源组名称。

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

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

3. 在 API 中心内使用 az role assignment create 命令为函数应用的托管标识分配 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 中心的资源 ID。 将 <apic-name> 和 <resource-group-name> 替换为你的 API 中心名称和资源组名称。

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

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

2. 获取函数应用中函数的资源 ID。 在此示例中，函数名称为“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 分析”。 此时会显示摘要。

   

相关内容

详细了解事件网格：

• 在 API 中心启用 API 分析 - Microsoft 托管
• Azure 事件网格中的系统主题
• 事件网格推送传递 - 概念
• Azure API 中心事件网格架构