Atualizações e controle de versão
Os conectores personalizados que foram publicados por meio da certificação ou criados como software livre ainda podem ser atualizados. O processo de atualização é quase idêntico ao da publicação inicial. A principal diferença é que você deve considerar os usuários existentes ao planejar as atualizações. Alterações interruptivas na definição de seu conector, mesmo se pequenas, podem afetar os usuários existentes.
Os gatilhos e as ações de um conector podem crescer e mudar ao longo do tempo, pois os recursos são adicionados ou expandidos na API subjacente. Algumas alterações são meramente aditivas e não quebram necessariamente o contrato existente entre aplicativos e fluxos que usam seu conector. Adicionar novos parâmetros, retornar mais dados ou permitir entradas mais flexíveis podem cair nessa categoria. No entanto, muitas alterações podem romper o contrato descrito na especificação OpenAPI.
Exemplos de alterações interruptivas incluem:
Remover parâmetros
Não oferecer mais suporte a certas entradas
Alterar o significado e o comportamento de uma entrada, saída ou operação
A API que o conector personalizado descreve deve evitar essas alterações interruptivas também. Nos casos em que grupos diferentes mantêm a definição do conector e a API, deve haver coordenação para mantê-los sincronizados.
Para melhorar um conector personalizado e a API com segurança, siga um padrão que possa ser empregado pelos usuários do conector. É do conector e, portanto, da API também, a responsabilidade de manter a compatibilidade com versões anteriores, comunicar a intenção e delinear os atributos de controle de versão. É responsabilidade do designer de ferramentas permitir ou não o uso do conector para mostrar ou ocultar operações que foram preteridas, desativadas ou que podem ter versões mais recentes disponíveis. Dessa forma, as operações podem crescer e desenvolver ao longo do tempo, sem causar fragilidade indevida nos aplicativos que dependem delas.
Anotar ações do conector
Usando a configuração da OpenAPI, você pode anotar as ações em seu conector para que, ao ser apresentada na superfície de design, ela transmita o uso pretendido. Por exemplo, ao adicionar a extensão da OpenAPI x-ms-api-annotation à ação GetInvoice, você indicou que seu status é de visualização.
Como resultado, quando essa ação é apresentada no designer de fluxo da nuvem do Power Automate, ela aparece (como visualização) após o nome da ação.
Novas versões de uma ação
Em algum momento do ciclo de vida de uma ação, você pode perceber que precisa introduzir uma alteração interruptiva. A melhor coisa a fazer é criar uma nova versão da ação. Os usuários existentes da ação original não serão afetados, mas os novos usuários poderão tirar proveito da nova versão. Uma prática comum é indicar a versão como parte do resumo. A captura de tela a seguir mostra como esse processo seria.
Substituição de uma ação
Depois de introduzir a nova ação, talvez seja recomendável substituir a ação antiga para que ela não seja mais usada em novos aplicativos e fluxos. Uma boa primeira etapa seria marcar a ação antiga na seção Visibilidade como avançada. Se você houver ações marcadas como importantes, considere se a nova ação V2 também deve ser marcada como importante. As duas alterações de visibilidade incentivam o uso da nova ação colocando-a em uma posição mais alta na lista de ações.
Você também pode indicar no resumo ou na descrição uma dica de substituição futura. Por exemplo, você pode alterar Obter Fatura para Obter Fatura (preterido). Essa opção pode anunciar a substituição sem ocultá-la dos usuários. O objetivo é ajudar a orientar os usuários do conector sobre as alterações feitas.
Para ocultar a ação de novos usuários sem esconder dos usuários existentes, você pode marcar a ação como preterida na configuração da OpenAPI. Você pode fazer essa alteração editando diretamente a definição de OpenAPI com o editor Swagger. Para indicar que uma ação foi preterida, adicione o seguinte comando à configuração da operação:
deprecated: true
Depois que o conector for publicado, este comando ocultará a ação dos usuários para que eles não possam selecioná-la em novos fluxos.
Existem vários motivos para aderir ao controle de versão das ações. Basicamente, isso garante que clientes, como Aplicativos Lógicos e Power Automate, continuem funcionando corretamente quando os usuários integrarem ações do conector aos seus fluxos. As ações sempre devem ter a versão controlada pelos métodos acima diante das seguintes situações:
Uma nova revisão de uma ação é adicionada.
Uma ação existente adiciona ou remove parâmetros.
Uma operação existente altera a entrada ou a saída significativamente.
Pode haver algumas situações em que você pode evitar o controle de versão, mas é preciso ter cuidado ao fazer isso e realizar vários testes para garantir que você não tenha ignorado os casos em que os aplicativos e os fluxos dos usuários podem ser rompidos inesperadamente.
É possível evitar (com cautela) o controle de versão quando:
Uma nova ação é adicionada.
Um novo parâmetro opcional é adicionado a uma ação existente.
Uma ação existente altera o comportamento sutilmente.
Recomendamos pecar pelo excesso e criar uma revisão ao fazer alterações não triviais em uma definição de conector ou API subjacente.