Mises à jour et contrôle de version
Les connecteurs personnalisés publiés au moyen de la certification ou créés en tant qu’open source peuvent toujours être mis à jour. Le processus de mise à jour est presque identique à la publication initiale. La principale différence réside dans le fait que vous devez tenir compte de vos utilisateurs existants lors de la planification de vos mises à jour. Les changements cassants apportés à la définition de votre connecteur, même si elles sont minimes, peuvent affecter les utilisateurs existants.
Les déclencheurs et les actions d’un connecteur peuvent évoluer et changer au fil du temps, à mesure que des fonctionnalités sont ajoutées ou développées dans l’API sous-jacente. Certains changements sont simplement additifs et ne rompent pas nécessairement le contrat qui existe entre les applications et les flux qui utilisent votre connecteur. L’ajout de nouveaux paramètres, le renvoi de plus de données ou l’autorisation d’entrées plus flexibles peuvent entrer dans cette catégorie. Cependant, de nombreux changements peuvent rompre le contrat décrit dans la spécification OpenAPI.
Voici des exemples de changements cassants :
suppression de paramètres,
interruption de prise en charge de certaines entrées,
modification de la signification et du comportement d’une entrée, d’une sortie ou de l’opération.
L’API décrite par votre connecteur personnalisé doit également éviter ces changements cassants. Dans les cas où différents groupes gèrent la définition du connecteur et l’API, une coordination doit avoir lieu pour assurer leur synchronisation.
Pour faire évoluer en toute sécurité un connecteur personnalisé et une API, assurez-vous de suivre un modèle qui peut être parcouru par les utilisateurs du connecteur. C’est la responsabilité du connecteur, et donc aussi de l’API, de maintenir la compatibilité descendante, de communiquer l’intention et de délimiter les attributs de contrôle de versions. C’est la responsabilité du concepteur d’outils d’autoriser l’utilisation du connecteur pour afficher ou masquer les opérations qui sont déconseillées, qui ont expiré ou pour lesquelles des versions plus récentes peuvent être disponibles. De cette manière, les opérations peuvent évoluer et se développer au fil du temps sans provoquer de fragilité excessive sur les applications qui en dépendent.
Annoter les actions du connecteur
À l’aide de la configuration OpenAPI, vous pouvez annoter les actions sur votre connecteur afin qu’il exprime l’utilisation prévue lorsqu’il est présenté dans la zone de conception. Par exemple, en ajoutant l’extension OpenAPI x-ms-api-annotation à l’action GetInvoice, vous avez indiqué que son statut est de type Version préliminaire.
De ce fait, lorsque cette action est présentée dans le concepteur de flux de cloud Power Automate, il affiche (version préliminaire) après le nom de l’action.
Nouvelles versions d’une action
À un moment donné de la durée de vie d’une action, vous vous rendrez peut-être compte que vous devez introduire un changement cassant. La meilleure chose à faire est de créer une version de l’action. Les utilisateurs existants de l’action d’origine ne seront pas affectés, mais les nouveaux utilisateurs pourront profiter de la nouvelle version. Une pratique courante consiste à indiquer la version dans le résumé. La capture d’écran suivante montre à quoi devrait ressembler ce processus.
Désapprobation d’une action
Après avoir introduit votre nouvelle action, vous souhaiterez peut-être déconseiller l’ancienne action afin qu’elle ne soit plus utilisée dans les nouvelles applications et les nouveaux flux. Une excellente première étape consisterait à marquer l’ancienne action comme avancée dans la section Visibilité. Si vous avez des actions marquées comme importantes, vous devez vous demander si la nouvelle action V2 doit également être marquée comme importante. Les deux changements de visibilité encourageront l’utilisation de la nouvelle action en la plaçant plus haut dans la liste des actions.
Vous pouvez également indiquer dans le résumé ou la description un indice de la désapprobation à venir. Par exemple, vous pouvez remplacer Obtenir une facture par Obtenir une facture (déconseillé). Ce choix permet d’annoncer en douceur la désapprobation sans la cacher aux utilisateurs. L’objectif est d’aider les utilisateurs du connecteur à s’y retrouver dans les changements que vous avez apportés.
Pour masquer l’action sur l’écran des nouveaux utilisateurs sans interrompre les utilisateurs existants, vous pouvez marquer l’action comme déconseillée dans la configuration OpenAPI. Vous pouvez effectuer ce changement en modifiant directement la définition OpenAPI avec l’éditeur Swagger. Pour indiquer qu’une action est déconseillée, ajoutez la commande suivante à la configuration de l’opération :
deprecated: true
Une fois le connecteur publié, cette commande masquera l’action et empêchera les utilisateurs de la sélectionner dans de nouveaux flux.
Il existe de nombreuses raisons d’adhérer au contrôle de versions des actions. En premier lieu, cela permet de garantir que les clients tels que Logic Apps et Power Automate continueront à fonctionner correctement lorsque les utilisateurs intégreront des actions de connecteur dans leurs flux. Les actions doivent faire l’objet d’un contrôle de versions à l’aide des méthodes ci-dessus chaque fois que l’une des conditions suivantes est vraie :
une nouvelle révision d’une action est ajoutée ;
une action existante ajoute ou supprime des paramètres ;
une opération existante modifie considérablement l’entrée ou la sortie.
Dans certaines situations, vous pouvez éviter le contrôle de versions, mais vous devez dans ce cas rester prudent et effectuer de nombreux tests pour vous assurer de ne pas négliger les cas limites où les applications et les flux des utilisateurs peuvent être interrompus de manière inattendue.
Vous pouvez (prudemment) éviter le contrôle de version si :
une nouvelle action est ajoutée ;
un nouveau paramètre facultatif est ajouté à une action existante ;
une action existante modifie subtilement le comportement.
Nous vous recommandons de faire preuve de la plus grande prudence et de créer une révision lorsque vous apportez des modifications non négligeables à une définition de connecteur ou à une API sous-jacente.