Créer un connecteur personnalisé de A à Z

Pour créer un connecteur personnalisé, vous devez définir l’API à laquelle vous souhaitez vous connecter afin que le connecteur comprenne les opérations et les structures de données de l’API. Dans cet article, vous allez créer un connecteur personnalisé à partir de zéro, sans utiliser de format de définition OpenAPI pour décrire l’opération de sentiment de l’API Analyse de texte Azure Cognitive Services (notre exemple pour cette série). Au lieu de cela, vous définissez complètement le connecteur dans l'assistant de connecteur personnalisé.

Pour connaître une autre façon de décrire une API, accédez à Créer un connecteur personnalisé à partir d’une définition OpenAPI.

Conditions préalables

• Une clé API pour l’API Analyse de texte de Cognitive Services

• L’un des abonnements suivants :

  • Power Automate
  • Power Apps

Lancer l’assistant de connecteur personnalisé

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

2. Dans le volet de gauche, sélectionnez Solutions.

3. Modifiez ou créez une solution non managée pour votre connecteur personnalisé. Découvrez comment créer une solution.

4. Sélectionnez la liste déroulante Nouveau connecteur personnalisé , puis sélectionnez Créer à partir d’un champ vide.

5. Entrez le nom du connecteur, comme SentimentDemo. Sélectionnez Continuer pour ouvrir votre Assistant Connecteur où vous remplissez ces cinq sections dans Power Automate :

   • General

   • Security

   • Definition

   • Code (facultatif)

   • Test

     

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

Vous fournissez des informations de connecteur telles que l’icône, la description, le schéma, l’hôte et l’URL de base dans la section Général . Procédez comme suit :

1. Sélectionnez l’icône Charger le connecteur ou Charger dans la zone d’icône pour charger une image PNG ou JPG de votre icône de connecteur. Assurez-vous qu’il est inférieur à 1 Mo. Vous pouvez également désigner une couleur d’arrière-plan pour votre icône.

2. Dans le champ Description, saisissez une valeur significative. Cette description apparaît dans les détails du connecteur personnalisé et elle permet aux autres utilisateurs de décider si le connecteur peut leur être utile.

3. Sélectionnez le schéma d’URL de votre connecteur, HTTPS ou HTTP.

4. 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

5. Mettez à jour l’URL de base, le point de départ de tous les appels d’API vers un service spécifique.

6. Sélectionnez Sécurité en bas pour accéder à la section suivante.

É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 la section Sécurité , sous Type d’authentification, sélectionnez Clé API dans la liste déroulante.

2. Sous Clé API, spécifiez une étiquette de paramètre, un nom et un emplacement. Spécifiez une étiquette significative, car cela s’affiche lorsque quelqu’un établit une connexion avec le connecteur personnalisé. Le nom et l’emplacement du paramètre doivent correspondre à ce que l’API attend.

   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.

4. Sélectionnez Définition en bas pour accéder à la section suivante.

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

L’Assistant Connecteur personnalisé vous offre de nombreuses options pour décrire la façon dont votre connecteur fonctionne et comment il est exposé dans des applications logiques, des flux, des applications et des agents. Vous pouvez définir des actions, des déclencheurs, des références et des stratégies. Nous expliquons l’interface utilisateur et couvrons quelques options dans cette section, mais nous vous encourageons également à les 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. Sous l’onglet Définition , le volet gauche affiche toutes les actions, déclencheurs (pour Logic Apps, Power Automate et Copilot Studio), les références et les stratégies définies pour le connecteur.

1. Sélectionnez Nouvelle action.

2. Dans la zone Général, 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 :

   • aucun : s’affiche normalement dans l’application logique ou le flux
   • avancé : masqué sous un autre menu
   • interne : masqué pour l’utilisateur
   • important : s’affiche toujours pour l’utilisateur en premier

3. Dans la zone Requête, 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 demande (fourni après la table), 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 l’exemple JSON.

   Exemple :

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

5. Dans la zone Réponse, sélectionnez Ajouter une réponse par défaut.

6. Spécifiez le corps de la réponse, puis sélectionnez Importer. Comme nous l’avons fait pour le corps de la demande, nous vous fournissons ces informations, mais elles sont généralement fournies dans la documentation de l’API.

   Exemple :

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

   La zone Validation affiche tous les problèmes détectés dans la définition de l’API.

7. Résolvez tous les problèmes. Vous devriez voir une coche verte lorsque la validation de la définition réussit.

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

Mettre à jour la définition

Changeons quelques éléments afin que le connecteur soit plus convivial lorsqu’une personne l’utilise dans Logic Apps, Power Automate, Power Apps ou Copilot Studio.

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
   Valeur par défaut	1
   Obligatoire	Oui

4. Dans la zone Paramètre, sélectionnez langue>Modifier, puis répétez le processus que vous avez utilisé pour id pour ajouter les valeurs language suivantes :

   Paramètre	active
   Civilité	Langage
   Description	Le code de langue de 2 ou 4 caractères correspondant au texte
   Valeur par défaut	en
   Obligatoire	Oui

5. Dans la zone Paramètre, sélectionnez texte>Modifier, puis répétez le processus que vous avez utilisé pour id et language pour ajouter les valeurs text suivantes :

   Paramètre	active
   Civilité	Text
   Description	Le texte à analyser pour détecter le sentiment
   Valeur par défaut	None
   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.

8. Sélectionnez Code en bas pour accéder à la section suivante.

Étape 4 : (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écute et que nous n’envoyons pas la demande au backend.

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 sont disponibles.

   

   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 le bouton bascule est Code désactivé, votre code est 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.

   

Étape 5 : 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.

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.

   Nonte

   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.

     

   • (Dans Power Apps) Vous retournez à la liste des connexions disponibles dans l’environnement actuel. Dans le volet de gauche, sélectionnez 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.

   Le connecteur appelle l’API.

5. Examinez la réponse, qui comprend le score de sentiment.

   

Pratiques recommandées pour les utilisateurs de CLI

• 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 à partir de :

• Power Automate
• Power Apps
• Applications logiques
• Copilot Studio

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.

• Partager votre connecteur
• Certifier votre connecteur

Fournir des commentaires

Nous apprécions grandement les commentaires sur les problèmes liés à notre plate-forme 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.