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

分析 API 中心中的 API - 由 Microsoft 管理的

组织的 API 中心包括内置的由 Microsoft 托管的代码规整功能（预览版），用于分析 API 定义是否符合组织样式规则，同时生成单个报告和汇总报告。 API 分析可以识别和帮助你更正 API 定义中的常见错误和不一致。

使用 API 分析：

  • 每当添加或更新 API 定义时，Azure API 中心都会自动分析 API 定义。 默认情况下，API 定义的 Lint 分析会使用一个 spectral:oas 规则集（即 API 风格指南）来完成。
  • API 分析报告是在 Azure 门户中生成的，其中显示了 API 定义与样式指南的符合程度。
  • 使用分析配置文件为分析的 API 指定规则集和筛选条件。 使用适用于 Visual Studio Code 的 Azure API 中心扩展来自定义配置文件的规则集。

重要

如果愿意，可以使用自定义 Azure 函数启用自托管的 Lint 分析和分析，从而重写内置功能。 在使用托管 API 分析之前，禁用用于自托管 Lint 分析的任何函数。

限制

  • 目前，仅会分析 JSON 或 YAML 格式的 OpenAPI 和 AsyncAPI 规范文档。
  • 分析模型的数量和 API 定义分析的最大数量都有 限制。 分析可能需要几分钟到长达 24 小时才能完成。

先决条件

查看 API 分析报告

在 Azure 门户中查看 API 定义的分析摘要和分析报告。 分析 API 定义后，报告会根根据配置的 API 样式指南列出错误、警告和信息。

在 API 分析报告中，还可查看用于分析的规则集和 Lint 分析通过的历史记录。

在 API 中心查看分析摘要：

  1. 在门户中，导航到你的 API 中心。

  2. 在左侧菜单的“治理”下，选择“API 分析”。 此时会显示摘要。

    门户中 API 分析摘要的屏幕截图。

  3. （可选）为 API 定义选择 API 分析报告图标。 将显示定义的 API 分析报告，如以下屏幕截图所示。

    门户中 API 分析报告的屏幕截图。

    提示

    还可以通过从 API 定义的菜单栏中选择“分析”来查看 API 分析报告。

管理分析配置文件

Azure API 中心使用分析配置文件进行 Lint 分析和 API 分析。 分析配置文件为分析的 API 指定规则集和（可选）筛选条件。 默认分析配置文件将 spectral:oas 规则集应用于所有 OpenAPI 和 AsyncAPI 定义。

可以在默认配置文件中自定义规则集并定义筛选器条件，也可以创建新的配置文件。 例如，你可能想要对正在开发的 API 使用一个配置文件，而对于生产中的 API，则使用另一个配置文件。

注释

在 API 中心的标准计划中，最多可以创建三个分析配置文件。 免费计划中仅支持单个配置文件。

若要创建分析配置文件，请执行以下操作：

  1. 在 Azure 门户中，导航到 API 中心。
  2. 在左侧菜单中的 “治理”下，选择 “API 分析>管理分析配置文件>+ 创建分析配置文件”。
  3. 在“ 新建分析配置文件 ”窗格中，输入配置文件 的名称 和 说明 。
  4. 在“结果集”中，将显示规则集的分析器类型（linting 引擎）。 目前仅支持光谱。
  5. 在“定义筛选器条件”下，为应用配置文件的 API 定义添加一个或多个筛选条件。
  6. 选择“创建”。

在门户中创建分析配置文件的屏幕截图。

创建配置文件并创建规则集基架。 若要查看当前规则集，请选择配置文件，然后在上下文（...）菜单中，选择“ 查看规则集”。

若要自定义规则集，请继续阅读以下部分。

自定义配置文件的规则集

使用适用于 Visual Studio Code 的 Azure API 中心扩展来自定义配置文件的规则集。 自定义规则集并在本地测试规则集后，可以将其部署回 API 中心。

  1. 在 Visual Studio Code 中，选择“活动栏”中的 Azure API 中心图标。
  2. 在 API 中心窗格中，展开正在使用的 API 中心资源，然后展开 “配置文件”。
  3. 展开要修改的配置文件，然后选择 ruleset.yaml。
  4. 根据需要修改或替换内容。
  5. 保存对 ruleset.yaml 的更改。

在本地测试规则集

将自定义规则集部署到 API 中心之前，请在本地验证它。 适用于 Visual Studio Code 的 Azure API 中心扩展，为使用 Spectral 进行 API 规范 Lint 分析提供了集成支持。

  1. 在 Visual Studio Code 中，使用键盘快捷方式 (Ctrl+Shift+P) 开启命令面板。

  2. 输入“Azure API 中心：设置活动 API 样式指南”，然后按“Enter”。

  3. 选择“选择本地文件”并指定自定义的 ruleset.yaml 文件。 按“Enter”。

    此步骤使自定义规则集成为用于本地代码审查的默认 API 样式指南。

现在，打开基于 OpenAPI 的 API 定义文件时，Visual Studio Code 中会自动触发本地 Lint 操作。 系统会在编辑器和“问题”窗口中直接显示结果（“查看”>“问题”或 Ctrl+Shift+M）。

提示

组织中的 API 开发人员还可以使用此本地 Lint 功能来帮助改进 API 定义，然后再在 API 中心注册 API。

在 Visual Studio Code 中对 API 定义进行 Lint 操作的屏幕截图。

查看 Lint 分析的结果。 对规则集进行任何必要的调整，并继续在本地测试，直到它按所需方式执行。

将规则集部署到 API 中心

将自定义规则集部署到 API 中心：

  1. 在 Visual Studio Code 中，选择“活动栏”中的 Azure API 中心图标。
  2. 在 API 中心窗格中，展开自定义规则集的 API 中心资源。
  3. 展开 配置文件。
  4. 右键单击自定义规则集的配置文件，然后选择“ 将规则部署到 API 中心”。

成功将规则部署到 API 中心后，消息会通知你。 linting 引擎使用更新的规则集来分析配置文件中的 API 定义。

若要查看使用更新的规则集进行 linting 的结果，请查看门户中的 API 分析报告。

相关内容

  • Last updated on