如何用APIOps CLI管理API管理配置

适用于：所有 API 管理层级

APIOps CLI 是 Azure API 管理的配置即代码工具。在本文中，你将用它提取API管理配置到本地工件中，在Git中审查工件，预览变更，并将批准的工件发布到API管理实例。 CLI还可以为GitHub Actions或Azure Pipelines文件搭建架构，实现APIOps工作流程。

使用此工作流程：

通过拉取请求审查API定义、策略及其他API管理配置。
保持可审计的批准配置变更历史。
在 API Management 环境之间提升已审核的工件。
从现有实例中提取配置开始，或以代码形式编写与 CLI 兼容的配置文件。

APIOps CLI 补充了 Use DevOps 和 CI/CD 发布 API 中描述的 API DevOps 方法。在非生产环境中评估CLI和你预期的工件工作流，再用它进行生产部署。

先决条件

Node.js 版本 22 或更高版本。
Azure CLI，用于本文中的本地认证步骤。
一个 Azure 订阅和一个现有的非生产 API 管理实例。
一个用于存储 API 管理工件的 Git 仓库。
一个拥有 API 管理实例访问权限的身份。 APIOps CLI 启动指南在其提取和发布工作流程的 API 管理资源范围内列出了 API 管理服务贡献 者和读取者角色。

生产自动化时，尽量使用独立的、权限最低的身份。提取标识需要具有对源实例的读取权限。发布标识仅需要更新目标实例所需的权限。

安装APIOps CLI

安装 @azure-tools/apiops-cli npm 包：

npm install -g @azure-tools/apiops-cli

验证已安装的版本：

apiops --version

记录并固定你批准的、用于 CI/CD 流水线的版本。升级前请先查看 APIOps CLI的更新日志。

向 Azure 进行身份验证

本地使用时，使用Azure CLI登录并选择包含你非生产API管理实例的订阅：

az login
az account set --subscription <subscription-id>

APIOps CLI 使用 DefaultAzureCredential. 除了 Azure CLI 凭证外，它还支持 environment 凭证、工作负载身份、管理身份、Azure PowerShell 和 Azure 开发者 CLI 凭证。

对于 CI/CD，应优先使用工作负载身份联合或托管身份，而不是客户端机密。切勿在源代码控制中放置凭证、访问令牌、订阅密钥或秘密命名值。有关支持的认证选项，请参阅 APIOps CLI认证指南。

准备一个文物仓库

从包含你 API 管理工件的 Git 仓库根节点运行 APIOps CLI 命令。

要搭建 GitHub Actions 的管道和配置模板，请执行：

apiops init --ci github-actions --environments dev,prod --non-interactive

对于 Azure Pipelines，请使用：

apiops init --ci azure-devops --environments dev,prod --non-interactive

该命令创建管道定义、提取过滤模板、环境覆盖模板、身份设置指南和目录 apim-artifacts 。在提交或启用流水线之前，请检查每个生成的文件。除非你先检查该命令将要覆盖的文件，否则不要在包含现有文件的仓库中使用 --force。

如果你已经有仓库和流水线设计，也可以改为创建或选择一个工件目录，并直接使用提取和发布命令。

创建初始工件

请选择以下方法之一来确定你的仓库拥有的工件。

提取现有配置

要从现有的 API 管理实例创建基线，提取其配置：

apiops extract \
  --subscription-id <source-subscription-id> \
  --resource-group <source-resource-group> \
  --service-name <source-apim-name> \
  --output ./apim-artifacts

该命令在 apim-artifacts下创建 JSON 信息文件、XML 策略文件和 API 规范文件的层级结构。对于大型实例，配置一个提取过滤器，使仓库只管理预期的资源。

从代码优先的工件开始

对于以代码为先的工作流程，可以通过使用 APIOps CLI 工件格式添加 OpenAPI 规范以及所需的 API 管理信息和策略文件。不要假设现有的应用仓库布局或OpenAPI文件本身就准备好支持 apiops publish。

如果你是artifact格式的新手，先从非生产实例中提取一个小型参考API。将生成的文件作为模板使用，并查看以代码为先的工作流程指导。

审查文物

发表前：

检查生成或自制的文件，确认仓库仅包含你打算管理的资源。
审查API规范、策略、后端、命名值、产品及其依赖关系。
移除那些不应该迁移到其他环境的环境特定值。在适当情况下，使用经过审查的环境覆盖文件或 Azure 密钥保管库引用。
查找凭据和机密值。提取过程会对受支持的敏感字段和已识别的策略模式进行脱敏处理，但可能无法检测到所有嵌入的敏感信息。请勿提交机密信息或未解析的 *** REDACTED *** 值。
将工件提交到分支，并使用拉取请求进行验证和审批。

预览与发布

针对非生产目标实例进行一次试运行。试运行会报告计划执行的创建、更新和删除操作，但不会实际应用这些更改：

apiops publish \
  --subscription-id <target-subscription-id> \
  --resource-group <target-resource-group> \
  --service-name <target-apim-name> \
  --source ./apim-artifacts \
  --dry-run

审查输出，解决意外变化或缺失的依赖。成功的试运行不能替代对API行为、策略、权限或后端连接的测试。

Caution

不要在你的第一个工作流程中添加 --delete-unmatched 内容。该选项会删除目标实例中源文物中未表示的资源。

发布经过审查的文物

拉取请求获批且试运行成功后，将同一批已审核的构件发布到非生产目标环境：

apiops publish \
  --subscription-id <target-subscription-id> \
  --resource-group <target-resource-group> \
  --service-name <target-apim-name> \
  --source ./apim-artifacts

发布后验证目标实例中的 API 和策略。在将此工作流自动化时，配置流水线以发布已获批准的提交，并使用组织要求的检查和审批来保护部署环境。

后续步骤

上次更新时间为 2026-09-18