Utiliser un schéma dynamique

Lorsque vous configurez une action sur un connecteur personnalisé, vous pouvez également configurer des paramètres. Ces paramètres sont configurés en important une définition OpenAPI ou un exemple de demande. Quelle que soit l’approche utilisée, la liste des paramètres est fixe. Lorsque cette action est utilisée, le créateur se voit présenter la liste statique des paramètres définis par le connecteur. Dans de nombreux cas, cette approche est adaptée car les paramètres de la liste sont fixes et ne varient pas. Dans d’autres cas toutefois, les paramètres qui doivent être présentés pour saisie sont variables.

Les cas d’utilisation les plus courants sont les suivants :

• La liste des paramètres varie en fonction d’un type, comme une catégorie ou un type de facture.

• L’état de l’enregistrement pourrait déterminer quels paramètres peuvent être modifiés. Par exemple, une commande expédiée peut avoir des paramètres disponibles différents d’une commande non expédiée.

• La liste des paramètres peut être réduite par la sécurité.

• La mise en œuvre d’actions commune sur quelques types de données différents. Par exemple, l’API peut implémenter une action Créer qui s’applique aux comptes, contacts, commandes ou factures. Les paramètres d’entrée sont définis par le type d’objet sélectionné par le créateur.

Les connecteurs personnalisés prennent en charge ces scénarios en vous permettant de configurer des extensions OpenAPI de schémas dynamiques. Lorsque les extensions OpenAPI de schéma dynamique sont configurées, le moteur d’exécution du connecteur personnalisé appelle une opération pour récupérer le schéma qui définit les paramètres devant être visibles pour cette action donnée. Les données de schéma peuvent inclure d’autres options telles que le nom d’affichage et la description du paramètre.

Dans l’exemple d’API Contoso Invoicing, après l’importation de la définition OpenAPI, l’action ressemblait à l’image suivante lorsqu’elle était utilisée dans un flux Power Automate.

L’image précédente montre les paramètres qui ne sont pas pertinents pour l’ajout d’une facture de commande fournisseur par rapport à une facture sans commande fournisseur. De plus, tous les champs de facture ne sont pas des entrées valides pour la création de la facture. Par exemple, createDate est un champ défini par l’API qui ne doit pas faire partie de l’entrée utilisateur. Une fois que vous avez implémenté des valeurs dynamiques pour l’ID de type de facture et le schéma dynamique pour les autres paramètres, l’action ressemblera à l’image suivante.

Au fur et à mesure que le créateur change le type de facture de commande fournisseur en commande hors fournisseur, le paramètre Commande fournisseur est masqué ou affiché selon le cas.

Le runtime du connecteur personnalisé prend en charge deux extensions différentes qui peuvent être utilisées pour configurer le schéma dynamique. Les deux atteignent le même objectif, l’extension x-ms-dynamic-schema étant la version 1 et x-ms-dynamic-properties, la version 2. Si vous devez prendre en charge des flux plus anciens avec votre action, vous pouvez configurer les deux versions sur votre connecteur personnalisé. Si vous prenez en charge uniquement les nouveaux flux, vous pouvez configurer l’extension x-ms-dynamic-properties uniquement.

Prise en charge par l’API

Pour que vous puissiez configurer le schéma dynamique, l’API sous-jacente doit le prendre en charge en définissant l’opération qui renvoie le schéma. Si l’API n’a pas déjà une action adaptée et que vous n’avez pas la possibilité de modifier l’API ou de demander les modifications, vous ne pourrez peut-être pas implémenter le schéma dynamique.

L’opération qui retourne le schéma peut prendre un ou plusieurs paramètres qui sont transmis à partir du runtime du connecteur personnalisé. Ces paramètres peuvent être des constantes ou représenter d’autres données collectées sur la carte d’action. Ces données peuvent être utilisées par l’API pour filtrer la liste des paramètres renvoyés dans le cadre du schéma. Dans l’exemple précédent, Type de facture est transmis en tant que paramètre à l’opération pour obtenir le schéma dynamique.

La réponse de l’opération utilisée pour le schéma dynamique doit être un schéma JSON valide. L’exemple suivant montre ce que l’API Contoso GetInvoiceSchema renvoie.

Notez les points clés suivants concernant le contenu :

• Le type doit être indiqué ; il est utilisé pour identifier le type de données du paramètre.

• Le résumé et la description sont utilisés dans le concepteur Power Automate pour identifier les paramètres pour le créateur.

• La propriété d’extension x-ms-visibility peut être fournie pour indiquer où vous pensez que ce paramètre doit toujours être affiché (valeur « important ») ou si une action de l’utilisateur est nécessaire pour le révéler au créateur, par exemple, cliquer sur le lien Avancé sur une carte de flux (valeur « avancé »). Étant donné que ces informations sont récupérées de manière dynamique, elles peuvent varier en fonction des informations de contexte disponibles.

• Le tableau requis fournit la liste des paramètres requis.

Configurer l’extension de schéma dynamique

Pour configurer l’extension x-ms-dynamic-schema ou x-ms-dynamic-properties, vous devez modifier directement la définition OpenAPI du connecteur personnalisé. À l’heure actuelle, la prise en charge du concepteur de connecteurs personnalisés n’est pas disponible pour modifier ces valeurs.

L’image suivante montre comment la configuration du paramètre AddInvoice s’est comportée après l’importation de la définition OpenAPI fournie par l’API :

L’exemple précédent montre que AddInvoice prend un objet CreateInvoiceRequest comme entrée. Les propriétés sont définies par une #/definitions/Invoice référencée, qui est une définition partagée de toutes les propriétés de la facture.

Pour implémenter l’appel à l’extension de schéma dynamique, vous pouvez remplacer les propriétés par l’extension configurée.

Au lieu d’avoir une liste de propriétés codées en dur, l’opération GetInvoiceSchema est appelée pour obtenir la liste en fonction du paramètre typeId.

En implémentant un schéma dynamique sur votre connecteur personnalisé, vous pouvez clarifier pour le créateur quels paramètres doivent être utilisés pour l’action.