Explorer les options de configuration de connecteurs personnalisés
Cette unité continue de présenter les notions élémentaires liées aux connecteurs personnalisés en examinant en détail certaines options de configuration disponibles.
Dénomination des connecteurs et informations générales
L’une des premières décisions que vous prendrez concernera le nom de votre connecteur. Celui-ci doit être unique et expliciter la nature du connecteur pour l’utilisateur. Le nom est limité à 30 caractères, mais vous pouvez apporter des précisions dans le champ Description. Le champ Couleur d’arrière-plan de l’icône peut également vous aider à définir l’identité visuelle de votre connecteur. Ces champs sont importants car ils indiquent quand l’utilisateur sélectionne le connecteur à utiliser, et ces repères visuels l’aident à travailler plus efficacement. Si vous prévoyez de soumettre votre connecteur pour certification, prenez connaissance des exigences plus strictes dans la documentation Instructions relatives à la soumission d’un connecteur à Microsoft.
Dénomination des actions et des déclencheurs
Lorsqu’un utilisateur a jeté son dévolu sur votre connecteur, il choisit une action ou un déclencheur à utiliser à partir du connecteur. Les champs ID d’opération, Résumé et Description permettent de décrire chaque action et chaque déclencheur. L’ID d’opération est utilisé en interne, il doit être unique et ne peut pas contenir d’espaces. L’utilisation d’une casse mixte telle que GetInvoice facilite la lecture de l’ID si vous recherchez un balisage pour la définition. L’absence d’espaces dans les noms peut être difficile pour les créateurs qui utilisent des lecteurs d’écran, mais l’utilisation de la casse mixte contribue à rendre vos définitions plus accessibles pour eux.
Le champ Résumé est important, car il s’affiche dans la liste des actions et des déclencheurs lorsque vous sélectionnez le déclencheur à utiliser. Nous vous conseillons d’être suffisamment explicite afin que l’utilisateur sache ce que fait l’action ou le déclencheur. Par exemple, la description de l’action GetInvoice peut être Obtenir une facture donnée au moyen de son ID. Il arrive souvent que les créateurs trouvent l’action en effectuant une recherche. Le fait d’attribuer des noms descriptifs peut les aider à trouver rapidement l’action adéquate.
L’image suivante montre où les éléments de résumé et de description sont utilisés lorsque vous sélectionnez une action ou un déclencheur.
Après avoir sélectionné une action ou un déclencheur, vous voyez les éléments de résumé et de description sur chaque carte d’action dans le concepteur.
Dans les images précédentes, notez que les modèles de dénomination sont incohérents, certains résumés de noms ayant des espaces et d’autres non. Vous pouvez corriger cette erreur en mettant à jour les champs dans le portail ou, si vous possédez l’API, vous pouvez demander au développeur de mettre à jour ce qu’il fournit dans la définition OpenAPI que vous importez. Sachez que si vous apportez manuellement des modifications dans le portail, puis réimportez la définition OpenAPI, celle-ci écrasera vos modifications.
Visibilité de l’action
Vous pouvez définir l’option Visibilité sur une action pour influencer la façon dont l’action s’affichera dans l’expérience du créateur.
Aucune : il s’agit de l’option par défaut. L’action s’affiche normalement.
Avancée : l’action est disponible, mais pas prioritaire.
Interne : l’action est masquée.
Importante : l’action est prioritaire, elle s’affiche en premier.
Par exemple, si vous importez une définition OpenAPI avec 10 actions et que vous ne voulez pas que les utilisateurs voient ou utilisent deux de ces actions au départ, vous pouvez sélectionner l’option interne pour les masquer. Cette approche est utile pour gérer les opérations permettant la prise en charge les métadonnées du connecteur dynamique. Elle permet également de masquer les actions initialement, puis de les rendre visibles plus tard, lorsque les utilisateurs les demandent. Le fait de masquer les actions fait en sorte que la liste que voient les utilisateurs soit aussi réduite que possible.
Les actions sélectionnées comme importantes sont affichées en premier. L’utilisateur doit sélectionner le connecteur pour afficher celles qui sont sélectionnés comme Aucune ou Avancée. Cette approche est la plus utile si vous avez de nombreuses actions et que beaucoup ne sont pas utilisées fréquemment.
Demande
La demande définit les paramètres et données transmis à l’opération lorsque l’action appelle l’opération sur l’API. Lorsque vous importez une définition OpenAPI, celle-ci configure les paramètres de requête de demande, des en-têtes et du corps. Vous pouvez également effectuer une importation manuelle à partir de l’exemple.
L’image suivante montre un exemple de l’aspect de l’écran lorsque vous regardez la définition.
Cette configuration est importante, car elle définit ce que l’utilisateur voit lorsqu’il utilise l’action.
En modifiant chacun des paramètres ou en demandant au développeur de l’API de fournir plus de détails, vous pouvez améliorer l’expérience utilisateur lorsque vous utilisez l’action. Un clic sur les points de suspension (…) sur chaque paramètre entraîne l’affichage de l’écran d’édition suivant.
Voici les champs et options que vous devez vérifier et modifier :
Nom : ne le modifiez pas ; ce champ doit correspondre à ce que l’API attend.
Résumé : rendez ce champ explicite ; par exemple, Datedefin deviendrait Date de fin.
Description : ce champ contient une phrase qui décrit le paramètre. Il sera utilisé comme texte d’espace réservé pour le champ.
Valeur par défaut : ce champ est une valeur par défaut facultative, mais il doit être renseigné si vous définissez la visibilité sur interne et que vous rendez le paramètre obligatoire.
Est obligatoire : vous devez définir cette option si l’API a besoin d’une valeur. Cette option active un astérisque rouge en regard du champ.
Visibilité : ce paramètre fait office d’option de visibilité sur l’action présentée précédemment. Si vous avez des paramètres qui ne sont pas utilisés souvent, sélectionnez l’option Avancée.
Type et format : vérifiez que ces champs sont adaptés, car le paramètre qui effectue des importations à partir d’exemples émet des hypothèses qui ne sont pas toujours correctes.
Type de liste déroulante : ce paramètre permet de configurer une liste statique ou dynamique de valeurs afin de rendre la sélection plus facile et plus prévisible.
L’image suivante montre un exemple d’aspect de l’écran après définition du paramètre Date de début.
Réponse
La réponse définit la réponse que vous attendez de l’API. À la différence de la demande, qui n’a qu’une seule définition, vous pouvez avoir différentes réponses en fonction du statut HTTP. Par exemple, si votre appel d’API génère une erreur, le corps contient les détails de l’erreur, au lieu de ce que votre API retourne. Vous pouvez également avoir une réponse par défaut, qui est une réponse universelle si aucune n’est disponible pour un statut HTTP donné.
Le fait de sélectionner l’une des réponses révèle les détails et, de même qu’avec une demande, vous pouvez modifier ces éléments pour faciliter l’utilisation.
Les éléments de la réponse correspondent à ce qui apparaît dans le volet Contenu dynamique.
Comme pour la demande, vérifiez que les noms et descriptions sont explicites, car ils peuvent faciliter l’utilisation des valeurs.
Validation
Notez qu’une section de validation similaire à l’image suivante apparaît en bas de l’écran.
Assurez-vous que cet écran ne présente pas d’erreurs, puis prenez le temps de résoudre les problèmes répertoriés.
Autres paramètres
D’autres paramètres tels que les déclencheurs, les références et les stratégies ne sont pas traités en profondeur dans ce module.
Les déclencheurs peuvent être configurés si l’API prend en charge les événements d’interrogation ou de webhook. Lorsqu’ils sont définis, les déclencheurs permettent d’utiliser votre connecteur comme déclencheur pour un flux Power Automate.
Les références définissent des paramètres réutilisables et sont généralement créées lorsque vous importez la définition et que celle-ci définit un paramètre réutilisable. Les références peuvent également être créées manuellement au moyen de l’éditeur Swagger intégré.
Les stratégies permettent de modifier les comportements des actions et des déclencheurs. Elles se créent à partir de l’un des modèles de stratégie prédéfinis.
Ces sujets avancés sont abordés en détail plus loin dans ce parcours d’apprentissage.
