Créer un connecteur personnalisé de A à Z

  • Article

Cet article fait partie d’une série de tutoriels sur la création et l’utilisation de connecteurs personnalisés dans Azure Logic Apps, Microsoft Power Automate et Microsoft Power Apps.

Notes

Assurez-vous de lire la présentation du connecteur personnalisé pour comprendre le processus.

Pour créer un connecteur personnalisé, vous devez décrire l’API à laquelle vous souhaitez vous connecter pour que le connecteur comprenne les opérations et les structures de données de l’API. Dans cette rubrique, vous créez un connecteur personnalisé à partir de zéro, sans utiliser de Collection Postman ni de définition OpenAPI pour décrire l’opération sur le sentiment de l’API d’analyse de texte Azure Cognitive Services (notre exemple pour cette série). Au lieu de cela, vous décrivez le connecteur complètement dans l’assistant de connecteur personnalisé.

Pour d’autres façons de décrire une API, accédez aux rubriques suivantes :

Notes

Vous pouvez actuellement créer un connecteur personnalisé à partir de zéro dans Power Automate et Power Apps. Pour le service Logic Apps, vous devez commencer avec au moins une définition OpenAPI de base ou une collection Postman.

Conditions préalables

Lancer l’assistant de connecteur personnalisé

  1. Connectez-vous à Power Apps ou Power Automate.

  2. Dans le volet de gauche, sélectionnez Données > Connecteurs personnalisés.

  3. Sélectionnez Nouveau connecteur personnalisé > Créer à partir d’un espace vide.

  4. Entrez le nom du connecteur personnalisé, puis sélectionnez Continuer.

    Paramètre active
    Titre du connecteur personnalisé SentimentDemo

Étape 1 : Mettre à jour des informations générales

À ce stade, nous allons afficher l’interface utilisateur de Power Automate, mais les étapes sont essentiellement les mêmes pour les technologies. Nous signalerons toute différence.

Sous l’onglet Général, vous pouvez effectuer les opérations suivantes :

  1. Dans le champ Description, saisissez une valeur significative. Cette description apparaîtra dans les détails du connecteur personnalisé et permettra aux autres utilisateurs de déterminer si le connecteur peut leur être utile.

  2. Mettez à jour le champ Hôte avec l’adresse de l’API d’analyse de texte. Le connecteur utilise l’hôte de l’API et l’URL de base pour déterminer comment appeler l’API.

    Paramètre active
    Description Utilise l’API Sentiment d’analyse de texte Cognitive Services pour déterminer si le texte est positif ou négatif
    Host westus.api.cognitive.microsoft.com

Étape 2 : Spécifier le type d’authentification

Plusieurs options sont disponibles pour l’authentification dans les connecteurs personnalisés. Les API Cognitive Services utilisent l’authentification par clé API, c’est donc ce qui est spécifié pour ce didacticiel.

  1. Dans l’onglet Sécurité sous Type d’authentification, sélectionnez Clé API.

  2. Sous Clé API, spécifiez une étiquette, un nom et un emplacement de paramètre. Spécifiez une étiquette explicite, car c’est ce qui s’affichera lorsqu’un utilisateur établira sa première connexion avec le connecteur personnalisé. Le nom et l’emplacement du paramètre doivent correspondre à ce que l’API attend. Sélectionnez Se connecter.

    Paramètre active
    Étiquette du paramètre Clé API
    Nom du paramètre Ocp-Apim-Subscription-Key
    Emplacement du paramètre En-tête

  3. En haut de l’Assistant, vérifiez que le nom est défini sur SentimentDemo, puis sélectionnez Créer un connecteur.

Étape 3 : Créer la définition du connecteur

L’Assistant Connecteur personnalisé vous propose de nombreuses options permettant de définir le fonctionnement de votre connecteur, ainsi que son exposition dans les applications logiques, les flux et les applications. Nous expliquerons l’interface utilisateur et couvrirons quelques options dans cette section, mais nous vous encourageons également à explorer par vous-même.

Créer une action

La première chose à faire est de créer une action qui appelle l’opération sur le sentiment de l’API d’analyse de texte.

  1. Dans l’onglet Définition, le volet de gauche affiche les actions, déclencheurs (pour Logic Apps et Power Automate) et références définis pour le connecteur. Sélectionnez Nouvelle action.

    Il n’y a pas de déclencheurs dans ce connecteur. Pour vous documenter sur les déclencheurs pour les connecteurs personnalisés, accédez à Utiliser un Webhook pour Azure Logic Apps et Power Automate.

  2. La zone Général affiche des informations sur l’action ou le déclencheur actuellement sélectionné. Ajoutez un résumé, une description et un ID d’opération pour cette action.

    Paramètre active
    Synthèse Renvoie un score numérique représentant le sentiment détecté
    Description L’API retourne un score numérique compris entre 0 et 1. Les scores proches de 1 indiquent un sentiment positif, tandis que les scores proches de 0 indiquent un sentiment négatif.
    ID d’opération DetectSentiment

    Laissez la propriété Visibilité définie sur aucun. Cette propriété pour les opérations et les paramètres dans une application ou un flux logique a les options suivantes :

    • aucune : s’affiche normalement dans l’application logique ou le flux
    • Avancé : caché sous un autre menu
    • interne : masqué pour l’utilisateur
    • importante : s’affiche toujours pour l’utilisateur en premier

  3. La zone Demande affiche des informations basées sur la demande HTTP pour l’action. Sélectionnez Importer à partir de l’exemple.

  4. Spécifiez les informations nécessaires pour vous connecter à l’API, spécifiez le corps de la requête (présenté après l’image suivante), puis sélectionnez Importer. Nous vous fournissons ces informations, mais pour une API publique, vous obtenez généralement ces informations à partir de documents tels que API d’analyse de texte (v2.0).

    Paramètre active
    Verbe PUBLICATION
    URL <https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment>
    Body Utilisez le code JSON suivant

    Exemple :

    {
  "documents": [
    {
      "language": "string",
      "id": "string",
      "text": "string"
    }
  ]
}

  5. La zone Réponse affiche des informations basées sur la réponse HTTP pour l’action. Sélectionnez Ajouter la réponse par défaut.

  6. Spécifiez le corps de la réponse, puis sélectionnez Importer. Comme pour le corps de la requête, nous vous fournissons ces informations d’après l’illustration, mais elles se trouvent généralement dans la documentation de l’API.

    Exemple :

    {
 "documents": [
   {
     "score": 0.0,
     "id": "string"
   }
 ],
 "errors": [
   {
     "id": "string",
     "message": "string"
   }
 ]
}

  7. La zone Validation affiche tous les problèmes détectés dans la définition de l’API. Vérifiez le statut, puis dans le coin supérieur droit de l’assistant, sélectionnez Mettre à jour le connecteur.

Mettre à jour la définition

Nous allons modifier quelques éléments pour que le connecteur soit plus convivial une fois utilisé dans une application logique, un flux ou une application.

  1. Dans la zone Requête, choisissez corps, puis sélectionnez Modifier.

  2. Dans la zone Paramètre, vous voyez maintenant les trois paramètres que l’API attend : id, language et text. Sélectionnez id, puis Modifier.

  3. Dans la zone Propriété de schéma, mettez à jour des valeurs pour le paramètre, puis sélectionnez Retour.

    Paramètre active
    Civilité ID
    Description Un identificateur pour chaque document que vous envoyez
    Default value 1
    Obligatoire Oui

  4. Dans la zone Paramètre , sélectionnez langue > Modifier, puis répétez le processus qui vous avez utilisé pour id aux étapes 2 et 3 de cette procédure, avec les valeurs suivantes.

    Paramètre active
    Civilité Langage
    Description Le code de langue de 2 ou 4 caractères correspondant au texte
    Default value en
    Obligatoire Oui

  5. Dans la zone Paramètre , sélectionnez texte > Modifier, puis répétez le processus qui vous avez utilisé pour id aux étapes 2 et 3 de cette procédure, avec les valeurs suivantes.

    Paramètre Valeur
    Titre Texte
    Description Le texte à analyser pour détecter le sentiment
    Valeur par défaut Aucune
    Obligatoire Oui

  6. Dans la zone Paramètre, sélectionnez Retour pour revenir à l’onglet principal Définition.

  7. Dans le coin supérieur droit de l’assistant, sélectionnez Mettre à jour le connecteur.

Étape 4 : (Facultatif) Activer votre connecteur en tant que plug-in d’IA

Utilisez l’onglet Plug-in d’IA (version préliminaire) pour un connecteur uniquement si vous prévoyez de certifier votre connecteur. Pour qu’un connecteur puisse être utilisé comme plug-in d’IA, il doit être certifié.

Avant d’activer votre connecteur en tant que plug-in d’IA, assurez-vous de bien comprendre le cas d’utilisation pour les scénarios de plug-in d’IA et d’avoir examiné d’autres considérations telles que la prise en charge, les meilleures pratiques et les recommandations. Pour plus d’informations : Créer un plug-in d’IA de connecteur (version préliminaire)

  1. Dans le volet de navigation de gauche, sélectionnez Connecteurs personnalisés.

    Si vous ne voyez pas Connecteurs personnalisés, sélectionnez Plus > Découvrir tout > Connecteurs personnalisés. L’option apparaît dans le volet de navigation de gauche.

  2. Dans le coin supérieur droit, sélectionnez une option dans le menu Nouveau connecteur personnalisé.

  3. Assurez-vous d’avoir terminé l’étape 1, l’étape 2 et l’étape 3 dans cet article.

  4. Sélectionnez l’onglet Plug-ins d’IA (version préliminaire).

  5. Dans la section Manifeste du plug-in, saisissez les détails pour activer ce connecteur comme plug-in d’IA.

    Capture d’écran des champs de la page « Manifeste du plug-in ».

    Champ Description
    Manifeste du plug-in : nom Nom du plug-in d’IA.
    Manifeste du plug-in : description Description du plug-in d’IA. Pour plus d’informations : Créer un plug-in d’IA de connecteur (version préliminaire)
    Manifeste du plug-in : e-mail du contact Adresse e-mail du contact pour ce plug-in d’IA.
    Manifeste du plug-in : URL des informations légales Un emplacement accessible au public où les informations légales liées à votre plug-in d’IA sont publiées.

  6. Faites défiler jusqu’à la section Détails des actions du plug-in et saisissez les détails de l’action pour chaque action dans le plug-in d’IA de votre connecteur.

    Capture d’écran des champs de la page « Détails de l’action du plug-in ».

    Champ Description
    Détails de l’action du plug-in : résumé Résumé de chaque action du plug-in d’IA que les utilisateurs peuvent effectuer.
    Détails de l’action du plug-in : description Description de chaque action que les utilisateurs peuvent effectuer concernant cette étape d’action spécifique du plug-in d’IA.
    Case à cocher : activer comme opération du plug-in de copilote Lorsque la case est cochée, l’opération du plug-in d’IA est activée.
    Case à cocher : confirmation de l’utilisateur requise ? Lorsque la case est cochée, la confirmation de l’utilisateur est requise.

    Conseil

    Si vous avez besoin d’aide pour définir vos actions, activez le bouton bascule Éditeur Swagger.

  7. Faites défiler jusqu’à la section Paramètre et saisissez les détails du paramètre pour le plug-in d’IA de votre connecteur.

    Capture d’écran des champs de la page « Paramètres ».

    Champ Description
    Paramètre : nom Nom du paramètre. Utilisez des noms identifiables tels que Identificateur du compte au lieu de ID.
    Paramètre : description Description du paramètre. Utilisez une explication descriptive telle que Date de naissance d’un contact au format JJ/MM/AAAA au lieu de b_date. Ces noms et descriptions aident les LLM (grands modèles de langage) à interagir efficacement avec le plug-in d’IA.
    Paramètre : résumé Informations récapitulatives sur le paramètre.
    Paramètre : valeur par défaut Valeur par défaut du paramètre.

  8. Dans la section Demande sous les sections Plug-in d’IA (version préliminaire), sélectionnez le paramètre d’entrée, puis saisissez un description.

Étape 5 : (Facultatif) Utiliser la prise en charge du code personnalisé

Le code personnalisé transforme les charges utiles des demandes et des réponses au-delà de la portée des modèles de stratégie existants. Les transformations incluent l’envoi de requêtes externes pour récupérer des données supplémentaires. Lorsque le code est utilisé, il prévaut sur la définition sans code. Cela signifie que le code s’exécutera et que nous n’enverrons pas la requête au back-end.

Notes

  • Cette étape est facultative. Vous pouvez compléter l’expérience sans code pour créer votre connecteur en ignorant cette étape et en allant à Étape 6 : Tester le connecteur.
  • La prise en charge du code personnalisé est disponible dans la version préliminaire publique.

Vous pouvez soit coller votre code, soit télécharger un fichier avec votre code. Votre code doit :

  • Être écrit en C#.
  • Avoir un temps d’exécution maximal de cinq secondes.
  • Avoir une taille de fichier ne dépassant pas 1 Mo.

Pour obtenir des instructions et des exemples d’écriture de code, accédez à Écrire du code dans des connecteurs personnalisés.

Pour les questions fréquemment posées sur le code personnalisé, accédez à la FAQ sur les codes personnalisés.

  1. Dans l’onglet Code, insérez votre code personnalisé en utilisant l’une des options suivantes :

    • Copier/coller
    • Sélectionner le bouton Charger.

    Si vous choisissez de charger votre code personnalisé, seuls les fichiers avec une extension .cs ou .csx seront disponibles.

    Capture d’écran de Charger votre code personnalisé.

    Important

    Actuellement, nous ne prenons en charge que la mise en surbrillance syntaxique dans l’éditeur de code. Assurez-vous de tester votre code localement.

  2. Après que vous avez collé ou chargé votre code, sélectionnez la bascule en regard de Code désactivé pour activer votre code. Le nom de la bascule devient Code activé.

    Vous pouvez activer ou désactiver votre code à tout moment. Si la bascule est Code désactivé, votre code sera supprimé.

  3. Sélectionnez les actions et les déclencheurs à appliquer à votre code personnalisé en sélectionnant une option dans le menu déroulant. Si aucune opération n’est sélectionnée, les actions et déclencheurs sont appliqués à toutes les opérations.

    Capture d’écran de Sélectionner des actions et des déclencheurs.

Étape 6 : Tester le connecteur

Maintenant que vous avez créé le connecteur, testez-le pour vous assurer qu’il fonctionne correctement. Les tests ne sont actuellement disponibles que dans Power Automate et Power Apps.

Important

Lorsque vous utilisez une clé API, nous vous recommandons de ne pas tester le connecteur immédiatement après l’avoir créé. Il peut falloir quelques minutes jusqu’à ce que le connecteur soit prêt à se connecter à l’API.

  1. Dans l’onglet Test, sélectionnez Nouvelle connexion.

  2. Entrez la clé API à partir de l’API Analyse de texte, puis sélectionnez Créer une connexion.

    Notes

    Pour les API qui nécessitent l’authentification du porteur, ajoutez Porteur et un espace avant la clé API.

  3. Revenez à l’onglet Test et effectuez l’une des opérations suivantes :

    • (Dans Power Automate) Vous êtes redirigé vers l’onglet Test. Sélectionnez l’icône d’actualisation pour vérifier que les informations de connexion sont mises à jour.

      Capture d’écran Actualiser la connexion.

    • (Dans Power Apps) Vous retournez à la liste des connexions disponibles dans l’environnement actuel. Dans le volet de gauche, sélectionnez Données > Connecteurs personnalisés. Sélectionnez le connecteur que vous avez créé, puis revenez à l’onglet Test.

  4. Dans l’onglet Test, entrez une valeur pour le champ texte (les autres champs utilisent les valeurs par défaut que vous avez définies précédemment), puis sélectionnez Opération de test.

  5. Le connecteur appelle l’API et vous pouvez consulter la réponse, qui inclut le score de sentiment.

    Capture d’écran de la réponse du connecteur.

(Pour les utilisateurs de l’interface de ligne de commande) Pratiques recommandées

  • Téléchargez tous vos connecteurs personnalisés et utilisez Git ou tout autre système de gestion de code source pour enregistrer les fichiers.

  • En cas de mise à jour incorrecte, redéployez le connecteur en réexécutant la commande de mise à jour avec le jeu de fichiers correct à partir du système de gestion de code source.

  • Testez le connecteur personnalisé et le fichier de paramètres dans un environnement de test avant de les déployer dans l’environnement de production.

  • Vérifiez toujours que l’environnement et l’ID de connecteur sont corrects.

Étapes suivantes

Maintenant que vous avez créé un connecteur personnalisé et défini ses comportements, vous pouvez l’utiliser depuis :

Vous pouvez également partager un connecteur au sein de votre organisation ou le faire certifier afin que les personnes extérieures à votre organisation puissent l’utiliser.

Fournir des commentaires

Nous apprécions grandement les commentaires sur les problèmes liés à notre plateforme de connecteurs ou les idées de nouvelles fonctionnalités. Pour fournir des commentaires, accédez à Soumettre des problèmes ou obtenir de l’aide avec les connecteurs et sélectionnez votre type de commentaire.