Atualizações e controle de versão
Você ainda pode atualizar conectores personalizados que são publicados por meio de certificação ou criados como software livre. O processo de atualização é quase idêntico à publicação inicial. A principal diferença é que você precisa 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 invalidar 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 desenvolver um conector personalizado e uma API com segurança, siga um padrão com o qual os usuários do conector possam lidar. É 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 da ferramenta decidir se permite o uso do conector para mostrar ou ocultar operações obsoletas, expiradas ou que possam ter versões mais recentes disponíveis. Como resultado, as operações podem crescer e se 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, adicionando a extensão OpenAPI x-ms-api-annotation à ação GetInvoice, você indicou que seu status é versão preliminar.
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 abordagem é 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.
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 direcionar os usuários do conector por meio das 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. Principalmente, isso garante que os clientes, como Aplicativos Lógicos e Power Automate, continuem funcionando corretamente quando os usuários integrarem as ações do conector em seus fluxos. Você deverá criar uma versão das ações usando os métodos anteriores sempre que uma das seguintes condições for verdadeira:
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
Podem ocorrer algumas situações em que você pode evitar o controle de versão, mas tenha cuidado ao fazer isso. Realize muitos testes para garantir que você não negligenciou casos extremos em que os aplicativos e os fluxos dos usuários possam ser interrompidos 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 que você tome precauções e crie uma revisão ao fazer alterações não triviais em uma definição de conector ou API subjacente.