Introducción
Los conectores personalizados de Microsoft Power Platform utilizan definiciones OpenAPI (también conocidas como Swagger) para describir la autenticación, las acciones, los desencadenantes y sus parámetros. La especificación OpenAPI permite definir extensiones que aumentan la definición principal para gestionar escenarios específicos. Microsoft ha definido varias extensiones a la definición de OpenAPI para permitirle configurar características específicas que son compatibles con conectores personalizados.
Puede identificar cada extensión buscando x-ms-<name> en las definiciones de OpenAPI. Es probable que ya haya usado algunas de estas definiciones cuando configuró un conector personalizado con el diseñador, como cuando introdujo un resumen en el parámetro de una acción que usa la extensión x-ms-resumen para almacenar el valor en la definición. Varias extensiones solo se pueden editar directamente a través del editor Swagger del diseñador o exportando las definiciones del conector y luego editándolas e importándolas de nuevo. Puede encontrar una lista completa de extensiones compatibles con conectores personalizados.
Este módulo explica las siguientes extensiones y sus usos:
x-ms-capabilities: se utiliza en el conector y en la definición del nivel de operación para indicar las características que se ofrecen.
x-ms-encoding: especifica la codificación de un parámetro de ruta.
x-ms-dynamic-values y x-ms-dynamic-list: proporcionan una lista de opciones para que el usuario seleccione los parámetros de entrada para una operación.
x-ms-dynamic-schema: permite hacer que los parámetros y la respuesta sean dinámicos en función de los resultados del esquema que se recuperan de una operación en la API.
El caso de uso principal para configurar estas extensiones es hacer que el conector sea más fácil de usar. Por ejemplo, sin valores dinámicos, los creadores tendrían que conocer los valores o cadenas de esquemas internos no adecuados para los parámetros de tipo o búsqueda. Al configurar valores dinámicos, está contribuyendo a proporcionar una lista desplegable fácil de usar para que los fabricantes la seleccionen.
Tenga en cuenta que algunas extensiones también requieren compatibilidad con la API. Por ejemplo, el esquema dinámico requiere que la API admita una operación para recuperar el esquema. En los casos en los que no controle la API, es posible que no sea posible configurar este tipo de extensiones.
Configurar extensiones
Si bien algunas extensiones de OpenAPI se configuran a medida que trabaja con definiciones mediante el diseñador, no es el caso de las extensiones que se tratan en este módulo. Para configurar estas extensiones, debe utilizar uno de los siguientes enfoques:
Importar OpenAPI: cuando importa un archivo OpenAPI, puede contener extensiones Microsoft OpenAPI.
CLI de conectores de Microsoft Power Platform: al usar la herramienta de línea de comandos paconn, puede descargar el archivo de definición de API y editarlo en su editor JSON favorito. Cuando haya terminado con la edición, puede usar paconn para cargar las definiciones modificadas en su entorno. Este enfoque es mejor cuando, por ejemplo, necesita realizar otros cambios en el archivo Propiedades de API para los parámetros de conexión.
Microsoft Power Platform CLI: al usar la herramienta de línea de comandos, puede descargar el archivo de definición de API para conectores personalizados que usan soluciones y editarlo en su editor JSON favorito. Cuando haya terminado con la edición, puede usar la CLI para cargar las definiciones modificadas en su solución. Este enfoque es mejor cuando necesita hacer otros cambios en el archivo Propiedades de API para los parámetros de conexión y el conector personalizado se encuentra en una solución.
Editor Swagger incorporado: el diseñador de conectores personalizados tiene un editor OpenAPI integrado, que es la forma más rápida de agregar extensiones OpenAPI.
Usar el editor Swagger
Puede hacer que el editor Swagger sea visible activando el control de alternancia Editor de Swagger en cualquiera de los pasos en el diseñador personalizado.
Cuando el editor está activado, la definición de OpenAPI en YAML Ain't Markup Language (YAML) se mostrará a la izquierda, y los mensajes de validación (si los hay) y una lista de operaciones se mostrarán a la derecha.
Si no está familiarizado con YAML, es un estándar de serialización de datos adecuado para los humanos que ayuda a realizar cambios en el contenido YAML, guardarlo y consumirlo en el tiempo de ejecución del conector.
La mayoría de los cambios que realice tendrán un ejemplo para comenzar. Un buen lugar para buscar cambios en YAML es en otros conectores que se encuentran en el Repositorio de GitHub del conector de Microsoft Power Platform. Por ejemplo, si desease implementar una extensión x-ms-capability, podría buscar en el repositorio y ver cómo lo han configurado otros conectores.
Al usar el editor, es mejor hacer cambios pequeños y enfocados. El editor comprueba su sintaxis a medida que escribe y le indica, en tiempo real, si se ha cometido un error y dónde se encuentra.
Consejos para trabajar con YAML en el editor de Swagger:
La sangría importa: la sangría es parte de las especificaciones de YAML; por lo tanto, observe cómo se usa la sangría para proporcionar más detalles de configuración.
Llaves de apertura y cierre {}: si tiene una llave de apertura {, necesita tener una de cierre }.
Corchetes de apertura y cierre []: si tiene un corchete de apertura, necesita tener uno de cierre.
Ctrl+B para Buscar: este método abreviado de teclado le permite buscar dentro de YAML.
Ctrl+Z para Deshacer: si observa que cometió un error, utilice el método abreviado de teclado Ctrl+Z para deshacer el último cambio.
En el resto de este módulo, explorará cómo usar algunas de las extensiones de Microsoft OpenAPI para que sus conectores personalizados sean más fáciles de usar.