Usar las extensiones de OpenAPI
Esta unidad explora cómo usar las extensiones de Microsoft OpenAPI x-ms-capabilities y x-ms-url-encoding en sus conectores personalizados.
La extensión x-ms-capabilities le ayuda a configurar qué capacidades ofrece el conector en el nivel de conector y nivel de operación. Actualmente, los conectores personalizados de Microsoft Power Platform se pueden configurar para las siguientes opciones:
chunkTransfer: nivel de operación
testConnection: nivel de conector
Habilitar la transferencia de fragmentos
Al gestionar mensajes, el tiempo de ejecución del conector limita el contenido del mensaje a un tamaño máximo. Este límite ayuda a reducir la sobrecarga que se crea al almacenar y procesar mensajes grandes. Para ayudar a manejar los mensajes que superan este límite, los conectores pueden dividir un mensaje grande en fragmentos de mensajes más pequeños. De esa manera, aún puede transferir contenido de gran tamaño. Cuando se comunica con otros servicios a través de conectores, el tiempo de ejecución puede consumir mensajes grandes, pero solo en fragmentos. Esta condición significa que los conectores también deben admitir la fragmentación, y el intercambio de mensajes HTTP subyacente entre el conector y estos servicios debe utilizar la fragmentación.
Para que un conector personalizado utilice la transferencia de fragmentos, se requieren los siguientes parámetros:
La API debe admitir la fragmentación. Para obtener más información, consulte Control de mensajes fragmentados de conectores.
Su conector personalizado debe habilitar la extensión de la capacidad de transferencia de fragmentos en la acción.
El fabricante que utiliza la acción de su conector debe habilitar la transferencia de fragmentos para el paso de flujo.
En su definición de conector personalizado, agregaría la siguiente lógica a la definición de operaciones para las que desea habilitar la transferencia de fragmentos.
{chunkTransfer: true}
Si estuviera trabajando con el archivo apiDefinition.swagger.json descargado en lugar del editor YAML, haría el cambio que se muestra en la siguiente captura de pantalla.
Una vez realizado este cambio, la indicación del cambio no se mostrará en el diseñador de conectores personalizados. Sin embargo, cuando la acción se usa en un flujo, la siguiente opción Permitir fragmentación aparecerá en la configuración del paso.
Suponiendo que la API lo admita, después de que se haya habilitado la fragmentación, los mensajes grandes ahora funcionarían y se transferirían mediante fragmentación.
Configurar la prueba de conexión
De forma predeterminada, cuando crea una conexión mediante un conector personalizado, no se comprueba la conexión como válida o no. Por ejemplo, si proporcionó una URL de host no válida o una clave de API no válida, podría crear una conexión, pero eventualmente fallaría cuando se usara la conexión. Al usar la extensión OpenAPI testConnection, puede especificar una operación en su conector personalizado que se ejecutará durante la creación de la conexión para validar la configuración proporcionada.
Para implementar la prueba de conexión, debe tener una operación simple definida en su conector personalizado que devuelva HTTP 200 (éxito). Esta operación puede ser una existente que ya haya configurado o puede crear una específicamente para probar la conexión. Si configura una operación de prueba específica, le recomendamos que la marque como interna para que los usuarios no intenten usarla. También puede pasar parámetros estáticos a la operación. Por ejemplo, si su acción tomó un parámetro $ top para limitar el número de registros devueltos, puede utilizar parámetros para limitar los resultados a un registro.
El siguiente ejemplo muestra la operación ListInvoices definida y cómo se utilizará para probar la conexión y muestra la configuración de la extensión testConnection.
La edición de apiDefinition.swagger.json sería similar a la siguiente imagen.
Configurar la codificación de ruta
La extensión x-ms-url-encoding se aplica a los parámetros que se incluyen en la ruta de la URL de la solicitud.
Por ejemplo, puede definir una acción para devolver clientes por país o región con la siguiente solicitud:
https://myapi.myservice.com/customers/{country}
En esta acción, país se convertirá en un parámetro que será suministrado por el usuario del conector. Debido a que estos parámetros son parte de la ruta, deben estar codificados como URL. De forma predeterminada, los parámetros de ruta tienen una única URL codificada. Sin embargo, en ciertos escenarios, la API subyacente puede esperar que los parámetros estén codificados con URL doble para resolver posibles ambigüedades que son introducidas por ciertos caracteres como el signo arroba (@), la barra (/), la barra invertida (\), etc.
Para configurar la codificación doble en un parámetro de ruta, debe agregar la siguiente opción al parámetro:
x-ms-url-encoding: double
Considere la API que tiene dos métodos que devuelven el parámetro de ruta de entrada, excepto que uno de ellos usa codificación doble, como se muestra en la siguiente imagen.
Cuando ejecuta un flujo de Microsoft Power Automate que llama a ambas acciones con una entrada compleja, la codificación doble pasa el mismo valor de texto a la API, con la diferencia de que ahora tiene codificación doble.
Esta extensión simplifica el control de los parámetros cuando la API espera una codificación de URL doble porque un usuario del conector no necesita codificar los parámetros de la ruta al llamar a las acciones.