使用动态架构

已完成

配置自定义连接器的操作时,还可以配置参数。 这些参数通过导入 OpenAPI 定义或示例请求进行配置。 无论使用何种方法,参数列表均固定。 使用该操作时,将向开发者提供连接器定义的静态参数列表。 在许多场景中,这种方法比较恰当,因为列表参数固定,不会改变。 在某些情况下,应为输入显示的参数是变量。

常见用例包括:

  • 参数列表因类型而异,比如类别或发票类型。

  • 记录状态可以确定能够更改的参数。 例如,已装运订单的可用参数不同于未装运订单。

  • 参数列表可按安全功能整理。

  • 常用操作实施涵盖若干不同数据类型。 例如,API 可能实施适用于客户、联系人、订单或发票的创建操作。 输入参数将由开发者选择的对象类型定义。

自定义连接器允许您配置动态架构 OpenAPI 扩展来支持这些场景。 配置动态架构 OpenAPI 扩展时,自定义连接器运行时将调用操作检索定义对给定操作可见参数的架构。 架构数据可以包括其他选项,比如参数的显示名称和描述。

在 Contoso Invoicing API 示例中,导入 OpenAPI 定义后,在 Power Automate 流中使用操作时,操作与下图相似。

上图展示与添加采购订单发票和非采购订单发票无关的参数。 此外,并非所有发票字段均为发票创建的有效输入。 例如,createDate是 API 设置的字段,但不应作为用户输入的一部分。 为其他参数的发票类型 ID 和动态架构实施动态值后,操作与下图相类似。

开发者将发票类型从采购订单改为非采购订单时,采购订单参数隐藏或视情况显示。

自定义连接器运行时支持两个不同的可用于配置动态架构的扩展。 两者均实现相同的目标,其中x-ms-dynamic-schema扩展为版本 1,x-ms-dynamic-properties为版本 2。 如需使用操作支持较早的流,可在自定义连接器上同时配置两个版本。 如果仅支持新流,仅配置x-ms-dynamic-properties扩展。

API 支持

要配置动态架构,基础 API 必须通过定义返回架构的操作提供支持。 如果 API 尚无适当操作并且您不具备修改 API 或请求变更的能力,您可能无法实施动态架构。

返回架构的操作可以采用从自定义连接器运行时传递的一个或多个参数。 这些参数可为常量,也可以代表操作卡采集的其他数据。 该数据可供 API 用于筛选作为架构一部分返回的参数列表。 在以上示例中,将发票类型作为参数传递到操作以获取动态架构。

用于动态架构的操作响应必须是有效的 JSON 架构。 以下示例展示 Contoso API GetInvoiceSchema 返回的内容。

请注意有关内容的以下关键点:

  • 必须提供类型并使用类型识别参数数据类型。

  • 在 Power Automate 设计器中使用摘要和说明识别开发者的参数。

  • 可以提供x-ms-visibility扩展属性指示您认为应始终显示本参数的位置(值“重要”)或是否需要用户操作才能将其显示给开发者,比如在流卡上选择高级链接(值“高级”)。 本信息为动态检索,因此可能因可用的上下文信息而异。

  • 必要数组提供所需参数列表。

配置动态架构扩展

要配置 x-ms-dynamic-schemax-ms-dynamic-properties 扩展,您必须直接编辑自定义连接器的 OpenAPI 定义。 目前,自定义连接器设计器不支持编辑这些值。

下图展示导入 API 提供的 OpenAPI 定义后 AddInvoice 参数配置的样式。

以上示例展示 AddInvoice 将 CreateInvoiceRequest 对象作为输入。 属性由引用的所有发票属性共享定义 #/definitions/Invoice 定义。

要实施对动态架构扩展的调用,您可将属性替换为经过配置的扩展。

将调用 GetInvoiceSchema 操作根据 TypeId 参数获取列表,替代硬编码属性列表。

在自定义连接器上实施动态架构,可为开发者阐明需要用于操作的参数。