Présentation
Les connecteurs personnalisés Microsoft Power Platform décrivent l’authentification, les actions, les déclencheurs et leurs paramètres à l’aide de définitions OpenAPI (également appelé Swagger). La spécification OpenAPI vous permet de définir des extensions qui augmentent la définition de base pour gérer des scénarios spécifiques. Microsoft a défini plusieurs extensions à la définition OpenAPI afin de vous permettre de configurer des fonctionnalités spécifiques prises en charge par les connecteurs personnalisés.
Vous pouvez identifier chaque extension en recherchant x-ms-<name> dans les définitions OpenAPI. Vous avez probablement déjà utilisé certaines de ces définitions lorsque vous avez configuré un connecteur personnalisé avec le concepteur, par exemple lors de la saisie d’un résumé dans le paramètre d’une action qui utilise l’extension x-ms-summary pour stocker la valeur dans la définition. Plusieurs extensions peuvent être modifiées uniquement soit directement au moyen de l’éditeur Swagger du concepteur, soit en exportant les définitions du connecteur, puis en les modifiant et en les réimportant. Vous pouvez consulter une liste complète des extensions prises en charge par les connecteurs personnalisés.
Ce module explique les extensions suivantes et leur utilisation :
x-ms-capabilities : utilisée sur le connecteur et la définition du niveau de fonctionnement pour indiquer les fonctionnalités proposées.
x-ms-encoding : spécifie le codage d’un paramètre de chemin d’accès.
x-ms-dynamic-values et x-ms-dynamic-list : fournit une liste d’options permettant à l’utilisateur de sélectionner les paramètres d’entrée pour une opération.
x-ms-dynamic-schema : vous permet de rendre les paramètres et la réponse dynamiques en fonction des résultats du schéma extrait à partir d’une opération sur l’API.
Le principal cas d’utilisation de la configuration de ces extensions consiste à améliorer la convivialité du connecteur. Par exemple, sans valeurs dynamiques, les créateurs doivent connaître les valeurs de schéma internes non conviviales ou les chaînes pour les paramètres de type/de recherche. Grâce à la configuration de valeurs dynamiques, vous aidez les créateurs en leur fournissant une liste déroulante conviviale d’options à sélectionner.
Gardez à l’esprit que certaines extensions nécessitent également une prise en charge par l’API. Par exemple, un schéma dynamique nécessite que l’API prenne en charge une opération d’extraction du schéma. Si vous ne contrôlez pas l’API, il peut ne pas être possible de configurer ces types d’extensions.
Configurer des extensions
Même si certaines extensions OpenAPI sont configurées lorsque vous utilisez des définitions à l’aide du concepteur, les extensions abordées dans ce module ne le sont pas. Pour configurer ces extensions, vous devez adopter l’une des approches suivantes :
Importer un fichier OpenAPI : lorsque vous importez un fichier OpenAPI, il peut contenir des extensions Microsoft OpenAPI.
CLI des connecteurs Microsoft Power Platform : à l’aide de l’outil en ligne de commande paconn, vous pouvez télécharger le fichier de définition d’API et le modifier à l’aide de votre éditeur JSON préféré. Une fois les modifications terminées, vous pouvez utiliser paconn pour charger les définitions modifiées dans votre environnement. Cette approche est recommandée lorsque vous devez apporter d’autres modifications au fichier Propriétés de l’API pour les paramètres de connexion, par exemple.
Microsoft Power Platform CLI : grâce à l’outil en ligne de commande, vous pouvez télécharger le fichier de définition d’API pour les connecteurs personnalisés utilisant des solutions et le modifier à l’aide de votre éditeur JSON préféré. Une fois les modifications terminées, la CLI vous permet de charger les définitions modifiées dans votre solution. Cette approche est recommandée lorsque vous devez apporter d’autres modifications au fichier Propriétés de l’API pour les paramètres de connexion et que le connecteur personnalisé se trouve dans une solution.
Éditeur Swagger intégré : le concepteur de connecteurs personnalisés dispose d’un éditeur OpenAPI intégré, qui est le moyen le plus rapide d’ajouter des extensions OpenAPI.
Utiliser l’éditeur Swagger
Vous pouvez rendre l’éditeur Swagger visible en activant le bouton bascule Éditeur Swagger à partir de l’une des étapes du concepteur personnalisé.
Une fois l’éditeur activé, la définition OpenAPI en YAML (YAML Ain’t Markup Language) s’affiche à gauche, et des messages de validation (le cas échéant) et une liste d’opérations s’affichent à droite.
Si vous ne connaissez pas YAML, il s’agit d’une norme de sérialisation de données conviviale qui vous permet d’apporter des modifications à du contenu YAML, de l’enregistrer et de le faire consommer par le runtime du connecteur.
La plupart des modifications que vous apportez sont associées à un exemple à partir duquel commencer. Pour en savoir plus sur les modifications apportées dans YAML, consultez d’autres connecteurs se trouvant dans le référentiel GitHub des connecteurs Microsoft Power Platform. Par exemple, si vous souhaitez implémenter une extension x-ms-capability, vous pouvez effectuer une recherche dans le référentiel et découvrir sa configuration pour d’autres connecteurs.
Lorsque vous utilisez l’éditeur, il est préférable d’apporter de légères modifications ciblées. L’éditeur vérifie votre syntaxe au fil de votre saisie et vous indique en temps réel si une erreur a été commise et où elle se trouve.
Conseils relatifs à l’utilisation de YAML dans l’éditeur Swagger :
L’indentation est importante : l’indentation fait partie des spécifications YAML ; par conséquent, observez comment l’indentation permet de fournir des détails de configuration supplémentaires.
Accolades ouvertes et fermées {} : si vous disposez d’une accolade ouverte {, vous devez disposer d’une accolade fermée }.
Parenthèses ouvertes et fermées [] : si vous disposez d’une parenthèse ouverte, vous devez disposer d’une parenthèse fermé.
Ctrl+F pour Rechercher : ce raccourci clavier vous permet d’effectuer une recherche dans le contenu YAML.
Ctrl+Z pour Annuler : si vous constatez que vous avez commis une erreur, annulez votre dernière modification à l’aide du raccourci clavier Ctrl+Z.
Dans le reste de ce module, vous allez découvrir comment certaines des extensions Microsoft OpenAPI vous permettent d’améliorer la convivialité de vos connecteurs personnalisés.