Utiliser les extensions OpenAPI
Cette unité explore l’utilisation des extensions Microsoft OpenAPI x-ms-capabilities et x-ms-url-encoding dans vos connecteurs personnalisés.
L’extension x-ms-capabilities vous permet de configurer les fonctionnalités offertes par le connecteur au niveau du connecteur et de l’opération. À l’heure actuelle, les connecteurs personnalisés Microsoft Power Platform peuvent être configurés pour les options suivantes :
chunkTransfer : niveau de l’opération
testConnection : niveau du connecteur
Activer le transfert en bloc
Lors de la gestion des messages, le runtime du connecteur limite leur contenu à une taille maximale. Cette limite permet de réduire la surcharge créée par le stockage et le traitement des messages volumineux. Pour faciliter la gestion des messages dont la taille dépasse cette limite, les connecteurs peuvent segmenter un message volumineux en blocs de message plus petits. Ainsi, vous pouvez malgré tout transférer du contenu volumineux. Lors de la communication avec d’autres services au moyen de connecteurs, le runtime peut consommer des messages volumineux, mais uniquement en bloc. Cette condition signifie que les connecteurs doivent également prendre en charge la segmentation et que l’échange de messages HTTP sous-jacent entre le connecteur et ces services doit utiliser la segmentation.
Pour qu’un connecteur personnalisé utilise le transfert en bloc, les paramètres suivants sont requis :
L’API doit prendre en charge la segmentation. Pour en savoir plus, consultez Gestion des messages segmentés pour les connecteurs.
Votre connecteur personnalisé doit activer l’extension de la fonctionnalité de transfert en bloc sur l’action.
Le créateur utilisant votre action de connecteur doit activer le transfert en bloc pour l’étape de flux.
Dans votre définition de connecteur personnalisé, vous ajouteriez la logique suivante à la définition d’opérations pour laquelle vous souhaitez activer le transfert en bloc :
{chunkTransfer: true}
Si vous utilisiez le fichier apiDefinition.swagger.json téléchargé au lieu de l’éditeur YAML, vous apporteriez la modification indiquée dans la capture d’écran suivante :
Une fois cette modification effectuée, l’indication de la modification ne s’affiche pas dans le concepteur de connecteurs personnalisés. Cependant, lorsque l’action est utilisée dans un flux, l’option Autoriser la segmentation suivante s’affiche dans les paramètres de l’étape :
Une fois la segmentation activée, en supposant que l’API la prenne en charge, les messages volumineux fonctionneraient désormais et seraient transférés à l’aide de la segmentation.
Configurer un test de connexion
Par défaut, lorsque vous créez une connexion à l’aide d’un connecteur personnalisé, sa validité n’est pas vérifiée. Par exemple, si vous fournissez une URL d’hôte non valide ou une clé API non valide, vous pouvez créer une connexion, mais elle finirait par échouer lors de son utilisation. À l’aide de l’extension OpenAPI testConnection, vous pouvez spécifier une opération dans votre connecteur personnalisé qui sera exécutée lors de la création de la connexion pour valider la configuration fournie.
Pour implémenter des tests de connexion, vous devez disposer d’une opération simple définie dans votre connecteur personnalisé qui renvoie le message HTTP 200 (succès). Il peut s’agir d’une opération existante que vous avez déjà configurée ou vous pouvez en créer une spécifiquement pour tester la connexion. Si vous configurez une opération de test spécifique, nous vous recommandons de la marquer comme interne afin que les utilisateurs ne tentent pas de l’utiliser. Vous pouvez également transmettre des paramètres statiques à l’opération. Par exemple, si votre action a utilisé un paramètre $top pour limiter le nombre d’enregistrements renvoyés, vous pouvez utiliser des paramètres pour limiter les résultats à un enregistrement.
L’exemple suivant présente l’opération ListInvoices définie, son utilisation pour tester la connexion et la configuration de l’extension testConnection :
La modification du fichier apiDefinition.swagger.json ressemblerait à l’image suivante :
Configurer le codage de chemin d’accès
L’extension x-ms-url-encoding s’applique aux paramètres inclus dans le chemin d’accès à l’URL de la requête.
Par exemple, vous pouvez définir une action pour renvoyer les clients par pays/région avec la requête suivante :
https://myapi.myservice.com/customers/{country}
Dans cette action, country (pays) devient un paramètre fourni par l’utilisateur du connecteur. Comme ces paramètres font partie du chemin d’accès, ils doivent être codés URL. Par défaut, les paramètres de chemin d’accès font l’objet d’un codage URL simple. Cependant, dans certains scénarios, l’API sous-jacente peut s’attendre à ce que les paramètres fassent l’objet d’un double codage URL pour résoudre les ambiguïtés potentielles introduites par certains caractères tels que le signe arobase (@), la barre oblique (/), la barre oblique inversée (\), etc.
Pour configurer le double codage sur un paramètre de chemin d’accès, vous devez ajouter l’option suivante au paramètre :
x-ms-url-encoding: double
Tenez compte de l’API dotée de deux méthodes qui renvoient le paramètre de chemin d’entrée, sauf que l’une d’elles utilise le double codage, comme illustré dans l’image suivante :
Lorsque vous exécutez un flux Microsoft Power Automate appelant les deux actions avec une entrée complexe, le double codage transmet la même valeur textuelle à l’API, sauf qu’elle est maintenant codée en double.
Cette extension simplifie la gestion des paramètres lorsque l’API s’attend à un double codage URL, car un utilisateur de connecteur n’a pas besoin de coder les paramètres de chemin d’accès lors de l’appel des actions.