Azure API 管理中的修订

适用于:所有 API 管理层级

修订允许你以受控且安全的方式更改 API。 若想进行更改,请创建新的修订。 然后,可以在不干扰 API 使用者的情况下编辑和测试 API。 准备就绪后,即可将修订设为最新。 同时,你可以根据需要将条目发布到更改日志中,以使 API 使用者了解最新的更改。 将更改日志发布到开发人员门户。

备注

开发人员门户在消费层中不可用。

借助修订,可以:

  • 安全地更改 API 定义和策略,而不会干扰生产 API。
  • 在发布之前,先试用一下更改。
  • 记录所做的更改,以便开发人员可以了解新增功能。
  • 如果发现问题,请回滚。

通过我们的教程来开始修订。

访问特定修订

可以使用特殊格式的 URL 访问 API 的每个修订版。 追加 ;rev={revisionNumber} 到 API URL 末尾,但在查询字符串之前,以访问该 API 的特定修订。 例如,可以使用此 URL 访问 API 的 customers 修订版 3:

https://apis.contoso.com/customers;rev=3/leads?customerId=123

默认情况下,每个修订与当前修订具有相同的安全设置。 如果要为每个修订应用不同的安全性,可以有意更改特定修订的策略。 例如,你可能想要添加 IP 筛选策略 ,以防止外部调用方访问仍在开发的修订。

备注

;rev={id}必须附加到 API ID 上,而不是在 URI 路径上。

当前修订

可以将单个修订设置为 当前 修订。 此修订将用于未在 URL 中指定显式修订号的所有 API 请求。 通过将该修订设置为当前版本,可以回滚到以前的修订。

可以使用 Azure 门户将修订设置为当前版本。 如果使用 PowerShell,可以使用 New-AzApiManagementApiRelease cmdlet。

修订说明

创建修订时,可以为自己的跟踪目的设置说明。 不会向 API 用户显示说明。

将修订设置为当前版本时,还可以选择指定公共更改日志注释。 更改日志包含在开发人员门户中,供 API 用户查看。 可以使用 PowerShell cmdlet 修改更改日志注释 Update-AzApiManagementApiRelease

注意

如果正在编辑 API 的非当前修订版,则无法更改以下属性:

  • 名称
  • 类型
  • DESCRIPTION
  • 需要订阅
  • API 版本
  • API 版本说明
  • 路径
  • 协议

只能在当前修订版本中更改这些属性。 如果编辑更改了非当前修订版的上述任何属性,则将显示错误消息 Can't change property for non-current revision

将修订移至离线

修订可以脱机,即使调用方尝试通过其 URL 访问修订,也无法访问该修订。 可以使用 Azure 门户将修订标记为脱机。

备注

建议在不用于测试时将修订脱机处理。

版本和修订

版本和修订是不同的功能。 每个版本可以有多个修订,就像非版本控制 API 一样。 可以在不使用版本的情况下使用修订,也可以以其他方式使用修订。 通常,版本用于将 API 版本与中断性变更分开,而修订可用于 API 的次要和非中断性变更。

如果你发现你的修订有重大变更,或者你希望将修订版正式作为 beta/测试版本,可以基于修订版创建新版本。 使用 Azure 门户,单击“修订版本”选项卡上修订上下文菜单上的“从修订版本创建新版本”。