Usar un esquema dinámico
Cuando configura una acción en un conector personalizado, también puede configurar parámetros. Estos parámetros se configuran importando una definición de OpenAPI o una solicitud de ejemplo. Independientemente del enfoque usado, la lista de parámetros es fija. Cuando se usa esa acción, al creador se le presentará la lista estática de parámetros según lo definido por el conector. Este enfoque es apropiado para muchos escenarios porque los parámetros de la lista son fijos y no varían. En algunos casos, los parámetros que deben presentarse para la entrada son variables.
Los casos de uso más habituales son:
La lista de parámetros varía según un tipo, como una categoría o un tipo de factura.
El estado del registro podría determinar qué parámetros se pueden cambiar. Por ejemplo, un pedido enviado podría tener diferentes parámetros disponibles que un pedido no enviado.
La lista de parámetros podría reducirse por motivos de seguridad.
Una implementación de acción habitual en algunos tipos de datos diferentes. Por ejemplo, la API podría implementar una acción Crear que se aplica a cuentas, contactos, pedidos o facturas. Los parámetros de entrada serán definidos por el tipo de objeto que seleccione el creador.
Los conectores personalizados admiten estos escenarios al permitirle configurar extensiones OpenAPI de esquema dinámico. Cuando se configuran las extensiones OpenAPI de esquema dinámico, el runtime del conector personalizado llamará a una operación para recuperar el esquema que define los parámetros que deben estar visibles para esa acción determinada. Los datos del esquema pueden incluir otras opciones, como el nombre para mostrar y la descripción del parámetro.
En el ejemplo de la API Contoso Invoicing, después de que se importase la definición de OpenAPI, la acción se asemejaba a la siguiente imagen cuando se usó en un flujo de Power Automate.
En la imagen anterior se muestran parámetros que no son relevantes para agregar una factura de pedido de compra frente a una factura de pedido de no compra. Además, no todos los campos de la factura son entradas válidas para la creación de la factura. Por ejemplo, createDate es un campo que establece la API y no debe formar parte de la entrada del usuario. Una vez que haya implementado valores dinámicos para el id. de tipo de factura y un esquema dinámico para los otros parámetros, la acción se parecerá a la siguiente imagen.
A medida que el creador cambia el tipo de factura de un pedido de compra a un pedido de no compra, el parámetro Pedido de compra está oculto o visible según corresponda.
El runtime del conector personalizado admite dos extensiones diferentes que se pueden usar para configurar un esquema dinámico. Ambos cumplen el mismo objetivo, donde la extensión x-ms-dynamic-schema es la versión 1 y x-ms-dynamic-properties es la versión 2. Si tiene que admitir flujos más antiguos mediante su acción, puede configurar ambas versiones en su conector personalizado. Si solo admite nuevos flujos, puede configurar solo la extensión x-ms-dynamic-properties.
Compatibilidad de API
Para poder configurar un esquema dinámico, la API subyacente debe brindar soporte definiendo la operación que devuelve el esquema. Si la API aún no tiene una acción adecuada y no posee la capacidad de modificar la API o de solicitar los cambios, es posible que no pueda implementar un esquema dinámico.
La operación que devuelve el esquema puede tomar uno o varios parámetros que se pasan del runtime del conector personalizado. Estos parámetros pueden ser constantes o pueden representar otros datos que se recopilan en la tarjeta de acción. La API puede usar esos datos para filtrar la lista de parámetros que se devuelven como parte del esquema. En el ejemplo anterior, Tipo de factura se pasa como parámetro a la operación para obtener el esquema dinámico.
La respuesta de la operación que se usa para un esquema dinámico debe ser un esquema JSON válido. En el siguiente ejemplo se muestra lo que devuelve la API de Contoso GetInvoiceSchema.
Observe los siguientes puntos clave sobre el contenido:
Se debe proporcionar el tipo y se usa para identificar el tipo de datos del parámetro.
El resumen y la descripción se usan en el diseñador de Power Automate para identificar los parámetros al creador.
Se puede proporcionar la propiedad de la extensión x-ms-visibility para indicar dónde cree que se debe mostrar siempre este parámetro (valor "importante") o si se requiere una acción del usuario para revelarlo al creador, como seleccionar vínculo avanzado en una tarjeta de flujo (valor "avanzado"). Debido a que esta información se recupera dinámicamente, puede variar según la información de contexto que esté disponible.
La matriz requerida proporciona la lista de parámetros requeridos.
Configurar la extensión de esquema dinámico
Para configurar las extensiones x-ms-dynamic-schema o x-ms-dynamic-properties, debe editar directamente la definición de OpenAPI del conector personalizado. Actualmente, la compatibilidad con el diseñador de conectores personalizados no está disponible para editar estos valores.
En la siguiente imagen, se muestra qué aspecto tenía la configuración del parámetro AddInvoice después de que se importara la definición de OpenAPI proporcionada por la API.
En el ejemplo anterior se muestra que AddInvoice toma un objeto CreateInvoiceRequest como entrada. Las propiedades se definen mediante un número/definiciones/factura al que se hace referencia, que es una definición compartida de todas las propiedades de la factura.
Para implementar la llamada a la extensión del esquema dinámico, puede reemplazar las propiedades con la extensión configurada.
En lugar de tener una lista de propiedades codificadas de forma rígida, se llamará a la operación GetInvoiceSchema para obtener la lista basada en el parámetro typeId.
Al implementar un esquema dinámico en su conector personalizado, puede aclararle al creador qué parámetros deben usarse para la acción.