更新和版本控制
通过认证发布或创建为开源的自定义连接器仍可更新。 更新流程与初始发布流程基本相同。 主要区别在于您必须在计划更新时考虑现有用户。 即便对连接器定义做出幅度较小的中断性变更也会影响现有用户。
随着基础 API 不断添加或扩展功能,连接器的触发器和操作也会随着时间的推移而增加和改变。 某些变更只需添加,无需中断使用连接器的应用与流之间的合同。 添加新参数、返回更多数据或允许更灵活的输入可能属于此类别。 但许多变更可能会中断 OpenAPI 规范中描述的合同。
中断性变更示例包括:
移除参数
不再支持某些输入
更改输入、输出或操作的含义和行为
自定义连接器描述的 API 也必须避免这些中断性变更。 不同的组维护连接器定义和 API 时,必须通过协调保持同步。
要安全地发展自定义连接器和 API,务必遵循支持连接器用户适应的模式。 连接器以及 API 需要保持后向兼容性、传达意图并描述版本属性。 工具设计器负责支持使用连接器显示或隐藏已弃用、已过期或可能包含更新版本的操作。 操作以这种方式随时间增加和发展,避免依赖这些操作的应用程序过分脆弱。
向连接器操作添加批注
您可以使用 OpenAPI 配置为连接器上的操作添加批注,以便在设计图面显示操作时传达预期用途。 例如,为GetInvoice操作添加 OpenAPI 扩展x-ms-api-annotation,指示其状态为预览。
因此,在 Power Automate 云端流设计器中显示本操作时,将在操作名称之后显示(预览版)。
新版操作
在操作生命周期的某个时间点,您可能发现需要引入中断性变更。 最好的方式是创建新版操作。 原始操作的现有用户不会受到影响,新用户则可以使用新版本。 常见做法是在摘要中指示版本。 以下屏幕截图展示本流程。
弃用操作
引入新操作后,您可能要弃用旧操作,不再在新应用和流中使用旧操作。 首先最好在可见性部分中将旧操作标记为高级。 如果操作标记为重要,应考虑是否同时将新的 V2 操作标记为重要。 这两项可见性更改将新操作放置在操作列表中的更高位置,以此鼓励使用新操作。
您也可在摘要或描述区域给出即将弃用的提示。 例如将Get Invoice改为Get Invoice(已弃用)。 本选项以柔和的方式宣布弃用,而不对用户隐藏。 其目的是帮助连接器用户适应您所做出的更改。
如要对新用户隐藏该操作,而不中断现有用户,可在 OpenAPI 配置中将该操作标记为已弃用。 您可以通过 Swagger 编辑器直接编辑 OpenAPI 定义来执行本项变更。 要指示某项操作已弃用,可在操作配置中添加以下命令:
deprecated: true
发布连接器后,本命令将隐藏操作,使用户无法在新流中选择本操作。
坚持操作版本控制的原因有很多。 主要原因是确保用户将连接器操作集成至流时,逻辑应用和 Power Automate 等客户端能够继续正常运行。 如果以下任一情况为 true,应使用上述方法对操作进行版本控制:
添加新修订的操作。
现有操作添加或删除参数。
现有操作的输入或输出出现重大变更。
某些情况下您可以选择不实施版本控制,但此时应格外谨慎并进行大量测试,避免忽视可能导致用户应用和流意外中断的极端情况。
您可在以下情况下(谨慎)选择不实施版本控制:
添加了新操作。
向现有操作添加新的可选参数。
现有操作行为的变化幅度极小。
我们建议您谨慎行事,在对连接器定义或基础 API 进行重要变更时创建修订版本。