你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
使用 DevOps 和 CI/CD 发布 API
适用于：所有 API 管理层级
API 对于企业而言具有重要的战略价值，因此采用 DevOps 持续集成 (CI) 和部署 (CD) 技术已成为 API 开发的重要方面。 本文讨论了在 API 管理中采用 DevOps 原则需要做出的决策。
API DevOps 由三个部分组成：
下面讨论了 API DevOps 管道的每个部分。
API 定义
API 开发人员通过提供要应用于 API 的规范、设置（例如日志记录、诊断和后端设置）和策略来编写 API 定义。 API 定义提供在 Azure API 管理服务上预配 API 所需的信息。 该规范可以建立在基于标准的 API 规范（如 WSDL、OpenAPI 或 GraphQL）之上，也可以通过 Azure 资源管理器 (ARM) API（例如描述 API 和操作的 ARM 模板）进行定义。 API 定义将随时间推移而更改，应被视为“源代码”。 请确保 API 定义存储在源代码管理下，并在采用前进行适当的评审。
有多种工具可帮助生成 API 定义：
- Azure APIOps 工具包提供基于 git 源代码管理系统（如 GitHub 或 Azure Repos）生成的工作流。 它使用提取程序生成 API 定义，该定义随后将应用于由发布者提供的目标 API 管理服务。 APIOps 目前支持 REST 和 GraphQL API。
- dotnet-apim 工具将格式标准的 YAML 定义转换为 ARM 模板，以供之后部署之用。 该工具侧重于 REST API。
- Terraform 是 Azure 资源管理器在 Azure 中配置资源的替代工具。 可以创建 Terraform 配置（与策略）以与创建 ARM 模板相同的方式实现 API。
还可以将基于 IDE 的工具用于编辑器（如 Visual Studio Code）来生成定义 API 所需的项目。 例如，Visual Studio Code 市场中有 30 多个插件可用于编辑 OpenAPI 规范文件。 此外，还可以使用代码生成器创建项目。 借助 CADL 语言，可以轻松创建高级构建基块，然后将其编译为标准 API 定义格式，例如 OpenAPI。
API 审批
生成 API 定义后，开发人员将提交 API 定义以供评审和审批。 如果使用基于 git 的源代码管理系统（如 GitHub 或 Azure Repos），则可以通过拉取请求完成提交。 拉取请求会通知其他人对 API 定义建议的更改。 确认审批入口后，审批者会将拉取请求合并到主存储库中，以表示可以将该 API 定义部署到生产环境。 拉取请求过程使开发人员能够修正审批过程中发现的任何问题。
GitHub 和 Azure Repos 均允许将审批管道配置为在提交拉取请求后运行。 可以将审批管道配置为运行以下工具：
- API 规范 Linter（如 Spectral），用于确保定义符合组织所需的 API 标准。
- 使用 openapi-diff 等工具进行中断性变更检测。
- 安全审核和评估工具。 OWASP 维护安全扫描工具的列表。
- 自动化 API 测试框架，例如用于 Postman 集合的测试运行程序 Newman。
注意
Azure API 必须符合一组严格的准则，这些准则可以作为你自己的 API 准则的起点。 Spectral 配置可用于强制执行准则。
运行自动化工具后，需要人工评审 API 定义。 工具不会捕获所有问题。 人工评审者确保 API 定义符合组织对 API 的要求，包括遵从安全性、隐私性和一致性准则。
API 发布
API 定义将通过发布管道发布到 API 管理服务。 用于发布 API 定义的工具取决于用于生成 API 定义的工具：
- 如果使用 Azure APIOps 工具包，请注意，该工具包包含将 API 定义写入目标服务的发布工具。
- 如果使用 dotnet-apim，则 API 定义将表示为 ARM 模板。 Azure Pipelines 和 GitHub Actions 中提供了可用于部署 ARM 模板的任务。
- 如果使用 Terraform，则 CLI 工具会将 API 定义部署在服务上。 为 Azure Pipelines 和 GitHub Actions 提供了任务。
是否可以使用其他源代码管理和 CI/CD 系统？
能。 所述过程适用于任何源代码管理系统（尽管 APIOps 明确要求源代码管理系统基于 git）。 同样，可以使用任何 CI/CD 平台，只要该平台可以通过签入触发并运行可与 Azure 通信的命令行工具。
最佳实践
设置用于发布 API 的 DevOps 管道没有任何行业标准可遵循，而上述工具也不会适用于所有情况。 但是，我们发现，使用以下工具和服务的组合能够涵盖大多数情况：
- Azure Repos 将 API 定义存储在 git 存储库中。
- Azure Pipelines 运行自动化 API 审批和 API 发布过程。
- Azure APIOps 工具包提供用于发布 API 的工具和工作流。
我们见证了客户在部署方面取得的最大成功，因此建议你采用以下做法：
- 为源代码管理系统设置 GitHub 或 Azure Repos。 此项选择还将决定你对管道运行程序的选择。 GitHub 可以使用 Azure Pipelines 或 GitHub Actions，而 Azure Repos 必须使用 Azure Pipelines。
- 为每个 API 开发人员设置 Azure API 管理服务，以便他们可以将 API 定义与 API 服务一起开发。 创建此服务时，请使用使用情况 SKU 或开发人员 SKU。
- 使用策略片段以减少开发人员需为每个 API 编写的新策略数目。
- 使用命名值和后端来确保策略是通用的，可以应用于任何 API 管理实例。
- 使用 Azure APIOps 工具包，以从开发人员服务中提取工作 API 定义。
- 设置对每个拉取请求运行的 API 审批过程。 API 审批过程应包括中断性变更检测、Lint 分析和自动化 API 测试。
- 使用 Azure APIOps 工具包发布工具将 API 发布到生产 API 管理服务。
若要更详细地了解如何使用 APIOps 配置和运行 CI/CD 部署管道，请参阅 Azure 体系结构中心的通过 APIOps 自动部署 API。
参考
- Azure DevOps 服务包括 Azure Repos 和 Azure Pipelines。
- Azure APIOps 工具包为 API 管理 DevOps 提供工作流。
- Spectral 为 OpenAPI 规范提供 Linter。
- openapi-diff 为 OpenAPI v3 定义提供中断性变更检测器。
- Newman 为 Postman 集合提供自动化测试运行程序。