Utilizar la lista dinámica de extensión de valores

Completado

Al configurar un parámetro para una acción en un conector personalizado, la opción predeterminada del creador es introducir el valor del parámetro en un cuadro de texto sencillo. Si tuviera un parámetro en una acción Agregar factura denominada Id. de tipo de factura, la experiencia del creador sería similar a la siguiente imagen.

El creador necesitaría conocer los valores correctos para el campo Id. de tipo de factura que, para este ejemplo, son los siguientes valores.

Valor Etiqueta
1 Pedido de compra
2 Pedido sin compra

Un creador tendría que introducir 1 para indicar que la factura es de tipo Pedido de compra. Para facilitar la definición de OpenAPI, debe admitir la palabra clave enumeración. Puede definir una enumeración con una lista de valores entre los que el creador puede elegir.

Puede configurar una enumeración mediante el diseñador de conectores personalizados. Para ello, debe editar la configuración del parámetro. En la configuración, si selecciona Estática en el área Tipo de lista desplegable, podrá proporcionar una lista de valores separados por comas. En la siguiente captura de pantalla se muestra el aspecto de la configuración Id. de tipo de factura.

También puede usar el editor Swagger y agregar la enumeración, tal y como se muestra en la siguiente imagen.

Además, si observa la experiencia del creador en Power Automate, ahora se parecería a la siguiente imagen.

Si bien la experiencia se mejora, aún requiere que el creador sepa cuál es el valor de 1 o 2. Puede describir el significado de estos valores en la descripción del parámetro para ayudar a simplificar el proceso para los creadores. El uso de enumeraciones es la mejor opción para describir automáticamente datos, como si tuviera un parámetro para Días de vencimiento y utilizara una enumeración para 30,60,90 que sería fácil de entender y usar. Otra limitación del uso de la enumeración es que si la API agrega nuevos valores permitidos, debe editar la definición de enumeración del conector personalizado y publicar la versión actualizada del conector. Para mejorar aún más la experiencia, Microsoft agregó la extensión OpenAPI x-ms-dynamic-values.

Configurar valores dinámicos

Puede configurar la extensión x-ms-dynamic-values en un parámetro para tener la lista de valores recuperados de la API subyacente.

Las ventajas de este enfoque son:

  • Puede configurar una etiqueta que el usuario ve junto con el valor.

  • Los valores devueltos siempre representan los valores correctos de la API.

  • La API puede recortar la lista de valores en función de la seguridad u otras necesidades según el usuario o la conexión.

  • Se pueden pasar otros valores de parámetros a la API para permitir el filtrado de la lista devuelta.

  • La salida de un campo se puede utilizar como parámetro de entrada para otra llamada de API, lo que permite crear opciones dependientes, como listas de países o regiones y estados.

La API con la que está trabajando debe proporcionar una operación que devuelva una matriz de valores válidos y, opcionalmente, sus descripciones. Para apoyar el ejemplo anterior de Id. de tipo de factura, la API proporcionó una operación ListInvoiceTypes que devolvió los siguientes datos.

En el diseñador de conectores personalizados para el parámetro Id. de tipo de factura, puede configurar la extensión x-ms-dynamic-values. Para ello, seleccione Dinámico y luego especifique un Id. de operación y las propiedades Valor y Nombre para mostrar del valor. En la siguiente captura de pantalla se muestra la configuración de Id. de tipo de factura.

También puede configurar la extensión x-ms-dynamic-values con el editor Swagger.

Es necesario usar el editor Swagger o descargar y editar el archivo JSON si está configurando parámetros en la extensión.

Ahora, con la extensión configurada, el creador podrá disfrutar de una experiencia más fácil de usar cuando use la acción.

Además de la extensión x-ms-dynamic-values, Microsoft también ha implementado una extensión más reciente denominada x-ms-dynamic-list. Conceptualmente, ambos logran el mismo objetivo de hacer que el parámetro de la acción sea una lista desplegable entre la que el usuario puede seleccionar. Tenga en cuenta la extensión x-ms-dynamic-values como versión 1, y la extensión x-ms-dynamic-list como versión 2. Si admite flujos existentes más antiguos, le recomendamos que implemente ambos en su definición. Si solo admite flujos recién creados, utilice solo x-ms-dynamic-list. La extensión x-ms-dynamic-list mejora el esquema de los parámetros de acción, lo que permite resolver algunas referencias ambiguas. Por ejemplo, si una solicitud tiene un Id. de parámetro de ruta y un Id. de parámetro como parte del cuerpo de la solicitud, la especificación x-ms-dynamic-list le permite diferenciar los dos parámetros mientras que x-ms-dynamic-values no podría admitir esta API.

Para configurar la extensión x-ms-dynamic-list, debe cambiar directamente la definición de OpenAPI, ya que el diseñador de conectores personalizados solo configura x-ms-dynamic-values. En la siguiente imagen se muestra la configuración x-ms-dynamic-values que también ha agregado una configuración x-ms-dynamic-list.

La configuración de valores dinámicos en los parámetros para un conector personalizado puede hacer que el conector personalizado sea más fácil de usar para los creadores.