更新和版本控制

已完成

应用中正在使用的自定义连接器仍可更新。 其更新流程与发布初始版本几乎相同。 主要区别在于,您在计划更新时必须考虑其对连接器现有用户的影响。 对连接器定义做出中断性更改(即使更改幅度很小)可能会对现有用户造成影响。

随着基础 API 不断添加或扩展功能,连接器的触发器和操作也会随着时间的推移而增加和改变。 某些变更只需添加,无需中断使用连接器的应用与流之间的合同。 添加新参数、返回更多数据或允许更灵活的输入可能属于此类别。 然而,有些更改可能会适用 OpenAPI 规范,继而破坏自定义连接器定义中描述的合同。

中断性变更示例包括:

  • 移除参数

  • 不再支持某些输入

  • 更改输入、输出或操作的含义和行为

自定义连接器描述的 API 也必须避免这些中断性变更。 不同的组维护连接器定义和 API 时,必须通过协调保持同步。

要安全地发展自定义连接器和 API,您所遵循的模式要让连接器的用户能够适应。 连接器以及 API 需要保持后向兼容性、传达意图并描述版本属性。 工具设计器支持使用连接器来显示或隐藏已弃用、已过期或可能有更新版本的操作。 操作以这种方式随时间增加和发展,避免依赖这些操作的应用程序过分脆弱。

向连接器操作添加批注

您可以使用 OpenAPI 配置为连接器上的操作添加批注,以便在设计图面显示操作时传达预期用途。 例如,通过为 GetInvoice 操作添加 x-ms-api-annotation OpenAPI 扩展,您已指示其状态为预览版。

GetInvoice 操作的 OpenAPI 配置屏幕截图。

因此,在 Power Automate 云端流设计器中显示本操作时,将在操作名称之后显示(预览版)。

云端流设计器的屏幕截图。

新版操作

在操作生命周期的某个时间点,您可能发现需要引入中断性变更。 最好是创建新版操作。 原始操作的现有用户不会受到影响,新用户则可以使用新版本。 常见做法是在摘要中指示版本。 下面的屏幕截图展示了这种方式的具体实践。

新版本 Get Invoice V2 的屏幕截图。

弃用操作

在引入新操作后的某个时间点,您可能要弃用旧操作,不再在新应用和流中使用旧操作。 第一步最好是将旧操作标记为高级。 如果操作标记为重要,应考虑是否同时将新的 V2 操作标记为重要。 这两项可见性更改将新操作放置在操作列表中的更高位置,以此鼓励使用新操作。

突出显示可见性选项的屏幕截图。

此外,还可在摘要或描述区域,给出即将弃用的提示。 例如将“Get Invoice”改为“Get Invoice(已弃用)”。 如此更改能够以一种不对用户隐藏的柔和方式宣布弃用。 其目的是帮助连接器用户适应您所做出的更改。

如果要真正向新用户隐藏该操作,而又不中断现有用户,可以在 OpenAPI 配置中将该操作标记为已弃用。 您可通过 Swagger 编辑器直接编辑 OpenAPI 定义来执行本项变更。 要指示某项操作已弃用,可以将以下逻辑添加到操作配置中:

已弃用:true

显示如何将“已弃用”设置为 true 的屏幕截图。

发布本操作后,本方法将会阻止用户在新流中选择本操作。

坚持操作版本控制的原因有很多。 首先,这样做可确保当用户将连接器操作集成至其流时,Microsoft Azure 逻辑应用和 Power Automate 之类客户端能够继续正常运行。 如果以下任一情况为 true,则应使用前面几种方法对操作进行版本控制:

  • 添加新修订的操作。

  • 现有操作添加或删除参数

  • 现有操作的输入或输出出现重大变更

有些情况下,也许可以不进行版本控制,但是这样做时要格外谨慎,并且要进行大量测试,以避免忽视可能导致用户应用和流意外中断的边缘案例。

可绕过版本控制的谨慎简短列表包括:

  • 添加了新操作。

  • 向现有操作添加新的可选参数。

  • 现有操作行为的变化幅度极小。

我们建议您谨慎行事,并建议您在连接器定义或基础 API 中进行重要更改时创建修订版。