Utiliser l’extension de liste dynamique de valeurs
Lorsque vous configurez un paramètre pour une action sur un connecteur personnalisé, l’expérience du créateur par défaut pour saisir la valeur du paramètre est une simple zone de texte. Si vous aviez un paramètre sur une action Ajouter une facture nommée ID du type de facture, l’expérience du créateur ressemblerait à l’image suivante :
Le créateur aurait besoin de connaître les valeurs correctes pour le champ ID du type de facture qui, pour cet exemple, sont les valeurs suivantes :
| Valeur | Libellé |
|---|---|
| 1 | Commande fournisseur |
| 2 | Commande hors fournisseur |
Un créateur aurait besoin de saisir 1 pour indiquer que la facture est de type Commande fournisseur. Pour faciliter cette définition OpenAPI, vous devez prendre en charge le mot clé enum. Vous pouvez définir une énumération avec une liste de valeurs parmi lesquelles le créateur peut faire son choix.
Vous pouvez configurer une énumération au moyen du concepteur de connecteurs personnalisé en modifiant la configuration des paramètres. Dans la configuration, si vous sélectionnez Statique dans la zone Type de liste déroulante, vous pouvez fournir une liste de valeurs séparées par des virgules. La capture d’écran suivante montre l’aspect qu’aura la configuration ID du type de facture.
Vous pouvez également utiliser l’éditeur Swagger et ajouter l’énumération, comme indiqué dans l’image suivante.
De plus, si vous avez consulté l’expérience du créateur dans Power Automate, elle ressemblerait maintenant à l’image suivante :
Bien que l’expérience soit améliorée, le créateur a toujours besoin de savoir ce que signifie la valeur 1 ou 2. Vous pouvez décrire la signification de ces valeurs dans la description des paramètres afin de simplifier le processus pour les créateurs. L’utilisation d’énumérations est préférable pour les données auto-descriptives. Par exemple, si vous avez un paramètre pour Jours dus et que vous utilisez une énumération pour 30,60,90, ce serait simple à comprendre et à utiliser. Une autre limite de l’utilisation d’énumérations est que si l’API ajoute de nouvelles valeurs autorisées, vous devez modifier la définition de l’énumération du connecteur personnalisé et publier la version mise à jour du connecteur. Pour améliorer encore l’expérience, Microsoft a ajouté l’extension OpenAPI x-ms-dynamic-values.
Configurer les valeurs dynamiques
Vous pouvez configurer l’extension x-ms-dynamic-values sur un paramètre de sorte à ce que la liste des valeurs soit extraite de l’API sous-jacente.
Les avantages de cette approche sont les suivants :
Vous pouvez configurer une étiquette que l’utilisateur voit en plus de la valeur.
Les valeurs renvoyées représentent toujours les valeurs correctes de l’API.
L’API peut réduire la liste de valeurs en fonction de la sécurité ou d’autres besoins, par utilisateur ou par connexion.
D’autres valeurs de paramètres peuvent être transmises à l’API pour permettre le filtrage de la liste renvoyée.
La sortie d’un champ peut être utilisée comme paramètre d’entrée pour un autre appel d’API, ce qui permet de créer des options dépendantes, telles que des listes de pays/régions et d’États.
L’API que vous utilisez doit fournir une opération qui renvoie un tableau de valeurs valides et, éventuellement, leurs descriptions. Pour soutenir l’exemple précédent de ID du type de facture, l’API a fourni une opération ListInvoiceTypes qui a renvoyé les données suivantes.
Dans le concepteur de connecteurs personnalisés pour le paramètre ID du type de facture, vous pouvez configurer l’extension x-ms-dynamic-values en sélectionnant Dynamique, puis en spécifiant un ID d’opération et les propriétés Valeur et Nom complet de la valeur. La capture d’écran suivante présente la configuration d’un ID de type de facture.
Vous pouvez également configurer l’extension x-ms-dynamic-values en utilisant l’éditeur Swagger.
Vous devez utiliser l’éditeur Swagger ou télécharger et modifier le fichier JSON si vous configurez des paramètres sur l’extension.
Maintenant, avec l’extension configurée, le créateur se voit offrir une expérience plus conviviale lorsqu’il utilise l’action.
Outre l’extension x-ms-dynamic-values, Microsoft a également implémenté une nouvelle extension appelée x-ms-dynamic-list. En théorie, les deux atteignent le même objectif, faire du paramètre de l’action une liste déroulante dans laquelle l’utilisateur peut effectuer une sélection. Supposons que l’extension x-ms-dynamic-values soit la version 1 et l’extension x-ms-dynamic-list, la version 2. Si vous prenez en charge des flux existants plus anciens, nous vous conseillons de mettre en œuvre les deux dans votre définition. Si vous prenez en charge uniquement les flux nouvellement créés, utilisez uniquement x-ms-dynamic-list. L’extension x-ms-dynamic-list améliore le schéma des paramètres d’action et permet de résoudre certaines références ambiguës. Par exemple, si une demande a un ID de paramètre de chemin et un ID de paramètre dans le corps de la demande, x-ms-dynamic-list permet de différencier les deux paramètres, alors que x-ms-dynamic-values ne serait pas en mesure de prendre en charge cette API.
Pour configurer l’extension x-ms-dynamic-list, vous devez modifier directement la définition OpenAPI, car le concepteur de connecteurs personnalisés configure uniquement x-ms-dynamic-values. L’image suivante montre la configuration x-ms-dynamic-values qui a également ajouté une configuration x-ms-dynamic-list.
La configuration de valeurs dynamiques sur les paramètres d’un connecteur personnalisé peut rendre le connecteur personnalisé plus convivial pour les créateurs.