Atualizações e controle de versão
Conectores personalizados que estão em uso por aplicativos ainda podem ser atualizados. O processo de atualização é quase idêntico ao do lançamento da versão inicial. A principal diferença é que você deve considerar o impacto sobre os usuários existentes de seu conector ao planejar as atualizações. Alterações interruptivas na definição do conector, mesmo que pequenas, pode 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, algumas das mudanças podem infringir o contrato descrito na definição do conector personalizado usando a 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, você precisa seguir um padrão que possa ser empregado pelos usuários do conector. O conector e, portanto, a API têm a responsabilidade de manter a compatibilidade com versões anteriores, comunicar a intenção e delinear os atributos de controle de versão. O designer de ferramentas permite o uso do conector para mostrar ou ocultar operações que foram preteridas ou 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, adicionando a extensão de 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. A captura de tela a seguir mostra como seria essa abordagem.
Substituição de uma ação
Em algum ponto 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 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.
Nas áreas de resumo ou descrição, você também pode indicar uma sugestão de preterição futura. Por exemplo, você pode alterar Obter Fatura para Obter Fatura (preterido). Essa mudança pode anunciar a preterição sem a ocultar dos usuários. O objetivo é ajudar a orientar os usuários do conector sobre as alterações feitas.
Para realmente 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 por meio do editor Swagger. Para indicar que uma ação foi preterida, adicione a seguinte lógica à configuração da operação:
deprecated: true
Depois que a ação for publicada, essa abordagem 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 do Microsoft Azure 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 anteriores nas 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
Podem ocorrer situações em que você possa evitar o controle de versão, mas é preciso ter cuidado ao fazer isso e realizar muitos testes para garantir que você não ignorou casos extremos em que os aplicativos e os fluxos dos usuários podem ser danificados inesperadamente.
Uma lista curta e cautelosa de quando você pode ignorar o controle de versão inclui os seguintes itens:
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ê seja cauteloso e crie uma revisão ao fazer alterações não triviais na definição de conector ou API subjacente.