使用动态值列表扩展

  • 4 分钟

您在为自定义连接器上的操作配置参数时，默认情况下，创建者要通过一个简单的文本框输入参数值。 如果名为发票类型 ID 的添加发票操作中有一个参数，则创建者的体验将类似于下图所示。

“添加发票”操作的屏幕截图，其中的“发票类型 ID”是一个简单的文本框。

创建者需要了解发票类型 ID 字段的正确值，在本例中为以下值。

值 标签
1 采购订单
2 非采购订单

创建者需要输入 1，指示发票属于采购订单类型。 为了简化 OpenAPI 定义，您应支持枚举关键字。 您可使用创建者可从中选择的值列表来定义枚举。

您可通过编辑参数配置来使用自定义连接器设计器来配置枚举。 在配置方面，如果您从下拉列表类型区域选择了静态，系统会提示您提供一个用逗号分隔的值列表。 以下屏幕截图显示了发票类型 ID 配置的外观。

显示配置静态值列表的屏幕截图。

您还可使用 Swagger 编辑器并添加枚举，如下图所示。

显示在 YAML 中配置的静态列表的屏幕截图。

此外，如果看一看 Power Automate 中的创建者体验，您会发现其与下图类似。

显示所用静态列表的屏幕截图。

在改进体验的同时，仍需要创建者了解 1 或 2 两个值的含义。 您可以在参数描述中给出这些值的含义，帮助简化创建者的流程。 对于自我描述数据最好使用枚举法，比如，您有一个代表到期天数的参数，如果能枚举出 30、60、90 这样的数字，则该参数在理解和使用起来都会变得比较简单。 枚举的另一个局限性在于，如果 API 添加了新的允许值，您就必须编辑自定义连接器的枚举定义并发布更新后的连接器版本。 为了进一步提升体验，Microsoft 添加了 OpenAPI 扩展 x-ms-dynamic-values。

配置动态值

您可在参数上配置 x-ms-dynamic-values 扩展，以便从基础 API 检索值列表。

这种方法的好处有：

  • 除了用户可以看到的值之外，您还可配置一个标签。

  • 返回的值始终为 API 中的正确值。

  • API 可以基于每个用户或每个连接的安全性或其他需求来修整值列表。

  • 可以向 API 传递其他参数值，以便对返回的列表进行筛选。

  • 一个字段的输出可用作另一个 API 调用的输入参数，以便可以生成依赖性选项，比如国家/地区和省/自治区/直辖市列表。

您所处理的 API 必须提供返回有效值数组及其描述（可选）的操作。 为支持发票类型 ID 的上一个示例，API 提供了可返回以下数据的 ListInvoiceTypes 操作。

展示从 API 获取动态值操作输出的屏幕截图。

在发票类型 ID 参数的自定义连接器设计器中，您可通过选择 Dynamic，然后指定操作 ID及值以及 Value display name 属性来配置 x-ms-dynamic-values 扩展。 以下屏幕截图显示了发票类型 ID 的配置。

显示配置动态值操作的屏幕截图。

除此之外，您还可使用 Swagger 编辑器来配置 x-ms-dynamic-values 扩展。

展示所配置的动态值操作的组成的屏幕截图。

如果要在扩展中配置参数，需要使用 Swagger 编辑器或下载和编辑 JSON 文件。

现在，配置好扩展后，创建者在使用本操作时，便可获得更加用户友好的体验。

显示下拉值列表的屏幕截图，其中带有已配置的动态值操作。

除了 x-ms-dynamic-values 扩展外，Microsoft 还实施了名为 x-ms-dynamic-list 的新扩展。 从概念上讲，这两项扩展实现了同一个目标，即将操作参数转变成了可供用户选择的下拉列表。 可以将 x-ms-dynamic-values 扩展视为版本 1，将 x-ms-dynamic-list 扩展视为版本 2。 如果您仍支持旧的现有流，建议您在定义中同时实施这两项扩展。 如果您仅支持新创建的流，则只要使用 x-ms-dynamic-list。 x-ms-dynamic-list 扩展改进了操作参数架构，因而可以解析一些不明确的引用。 例如，如果请求正文中带有路径参数 ID 和参数 ID，则您可通过 x-ms-dynamic-list 说明来区分这两个参数，而 x-ms-dynamic-values 不支持本 API。

要配置 x-ms-dynamic-list 扩展，您必须直接变更 OpenAPI 定义，因为自定义连接器设计器仅可配置 x-ms-dynamic-values。 下图显示了 x-ms-dynamic-values 配置，其中还添加了 x-ms-dynamic-list 配置。

显示两个扩展在配置上的区别的屏幕截图。

为自定义连接器的参数配置动态值可提高自定义连接器对创建者的用户友好性。