Actualizaciones y versiones
Los conectores personalizados que se publicaron mediante certificación o se crearon como código abierto aún se pueden actualizar. El proceso para realizar la actualización es casi idéntico al de la publicación inicial. La principal diferencia es que debe tener en cuenta a sus usuarios existentes al planificar sus actualizaciones. Los cambios importantes en la definición de su conector, aunque sean pequeños, pueden afectar a los usuarios existentes.
Los desencadenadores y las acciones de un conector pueden crecer y cambiar con el tiempo a medida que se agregan o amplían características en la API subyacente. Algunos cambios son meramente aditivos y no necesariamente rompen el contrato que existe entre las aplicaciones y los flujos que usan su conector. Agregar nuevos parámetros, devolver más datos o permitir entradas más flexibles puede entrar en esta categoría. Sin embargo, muchos cambios pueden romper el contrato que se describe en la especificación de OpenAPI.
Algunos ejemplos de cambios importantes incluyen:
La eliminación parámetro
Que ya no se admitan ciertas entradas
El cambio del significado y el comportamiento de una entrada, salida o la operación
La API que describe su conector personalizado también debe evitar estos cambios importantes. En los casos en que diferentes grupos mantienen la definición del conector y la API, se debe realizar una coordinación para mantenerlos sincronizados.
Para evolucionar un conector personalizado y una API de forma segura, asegúrese de seguir un patrón por el que puedan navegar los usuarios del conector. Es responsabilidad del conector, y por lo tanto también de la API, mantener la compatibilidad con versiones anteriores, comunicar la intención y delinear los atributos de control de versiones. Es responsabilidad del diseñador de herramientas permitir el uso del conector para mostrar u ocultar operaciones que estén en desuso, vencidas o que puedan tener versiones más nuevas disponibles. De esta manera, las operaciones pueden crecer y desarrollarse con el tiempo sin causar una fragilidad indebida en las aplicaciones que dependen de ellas.
Anotar acciones del conector
Al usar la configuración de OpenAPI, puede anotar las acciones en su conector para que, cuando se presente en la superficie de diseño, transmita el uso previsto. Por ejemplo, al agregar la extensión de OpenAPI x-ms-api-annotation a la acción GetInvoice, ha indicado que su estado es versión preliminar.
Como resultado, cuando esta acción se presenta en el diseñador de flujo de nube de Power Automate, se muestra (versión preliminar) después del nombre de la acción.
Nuevas versiones de una acción
En algún momento de la vida de una acción, es posible que se dé cuenta de que es necesario introducir un cambio importante. Lo mejor que puede hacer es crear una nueva versión de la acción. Los usuarios existentes de la acción original no se verán afectados, pero los nuevos usuarios pueden aprovechar la nueva versión. Una práctica habitual es indicar la versión como parte del resumen. En la siguiente captura de pantalla se muestra el aspecto que tendría este proceso.
Marcar una acción en desuso
Después de introducir su nueva acción, es posible que desee que la acción anterior pase a estar en desuso para que ya no se use en nuevas aplicaciones y flujos. Un buen primer paso sería marcar la acción anterior en la sección Visibilidad como avanzada. Si tiene acciones marcadas como importante, debe considerar si la nueva acción V2 también debe marcarse como importante. Ambos cambios de visibilidad fomentarán el uso de la nueva acción colocándola más arriba en la lista de acciones.
También puede indicar en el resumen o descripción una sugerencia de una próxima acción en desuso. Por ejemplo, podría cambiar Obtener factura por Obtener factura (en desuso). Esta opción puede anunciar suavemente su desuso sin ocultarla a los usuarios. El objetivo es ayudar a los usuarios del conector a navegar a través de los cambios que realice.
Para ocultar la acción a los nuevos usuarios pero no interrumpir a los usuarios existentes, puede marcar la acción como en desuso en la configuración de OpenAPI. Puede realizar este cambio editando directamente la definición de OpenAPI con el editor Swagger. Para indicar que una acción está en desuso, agregue el siguiente comando a la configuración de la operación:
deprecated: true
Una vez publicado el conector, este comando ocultará la acción por la que el usuario puede seleccionarlo en nuevos flujos.
Existen muchas razones para adherirse al control de versiones de acción. Principalmente, hacerlo garantizará que clientes como Logic Apps y Power Automate sigan funcionando correctamente cuando los usuarios integren acciones de conector en sus flujos. Las acciones deben versionarse mediante el uso de los métodos anteriores siempre que se cumpla una de las siguientes condiciones:
Se agrega una nueva revisión de una acción.
Una acción existente agrega o elimina parámetros.
Una operación existente cambia significativamente la entrada o la salida.
Pueden ocurrir algunas situaciones en las que puede evitar el control de versiones, pero debe tener cuidado al hacerlo y realizar muchas pruebas para asegurarse de no haber pasado por alto los casos extremos en los que las aplicaciones y los flujos de los usuarios pueden romperse inesperadamente.
Puede evitar (con precaución) el control de versiones cuando:
Se agrega una nueva acción.
Se agrega un nuevo parámetro opcional a una acción existente.
Una acción existente cambia el comportamiento sutilmente.
Le recomendamos que sea precavido y cree una revisión cuando realice cambios no triviales en la definición de un conector o en la API subyacente.