Créer un connecteur personnalisé à partir d’une définition OpenAPI

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 ce sujet, vous créez un connecteur personnalisé à l’aide d’une définition OpenAPI qui décrit l’API Sentiment d’analyse de texte Cognitive Services (notre exemple pour cette série).

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

Conditions préalables

• Une définition OpenAPI qui décrit l’exemple d’API. Lors de la création d’un connecteur personnalisé, la définition OpenAPI doit être inférieure à 1 Mo. La définition OpenAPI doit être au format OpenAPI 2.0 (anciennement appelé Swagger).

  S’il existe plusieurs définitions de sécurité, le connecteur personnalisé sélectionne la définition de sécurité supérieure. La création de connecteurs personnalisés ne prend pas en charge les informations d’identification du client (par exemple, l’application et le mot de passe) dans la définition de sécurité OAuth.

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

• L’un des abonnements suivants :

  • Azure, si vous utilisez Logic Apps
  • Power Automate
  • Power Apps

• Si vous utilisez Logic Apps, commencez par créer un connecteur personnalisé Azure Logic Apps.

Importer la définition OpenAPI

Vous êtes maintenant prêt à utiliser la définition OpenAPI que vous avez téléchargée. Toutes les informations requises sont contenues dans la définition, et vous pouvez consulter et mettre à jour ces informations tout au long de l’assistant de connecteur personnalisé.

Commencez par importer la définition OpenAPI pour Logic Apps ou pour Power Automate et Power Apps.

Importez la définition OpenAPI pour Logic Apps

1. Accédez au Portail Azure et ouvrez le connecteur Logic Apps que vous avez créé dans Créer un connecteur personnalisé Azure Logic Apps.

2. Dans le menu de votre connecteur, choisissez Connecteur Logic Apps, puis sélectionnez Modifier.

   

3. Sous Général, sélectionnez Charger un fichier OpenAPI, puis accédez à la définition OpenAPI que vous avez créée.

   

Importer la définition OpenAPI pour Power Automate et Power Apps

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é, puis choisissez Importer un fichier OpenAPI.

   

4. Entrez un nom pour le connecteur personnalisé, accédez à la définition OpenAPI que vous avez téléchargée ou créée, puis sélectionnez Continuer.

   

   Paramètre	active
   Titre du connecteur personnalisé	SentimentDemo

Vérifier les détails généraux

À ce stade, nous allons afficher l’interface utilisateur de Power Automate, mais les étapes sont essentiellement les mêmes pour les trois technologies. Nous signalerons toute différence. Dans cette partie de le sujet, nous examinerons principalement l’interface utilisateur et vous montrerons comment les valeurs correspondent aux sections du fichier OpenAPI.

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

2. Dans la page Général, vérifiez les informations importées à partir de la définition OpenAPI, y compris l’hôte de l’API et l’URL de base de l’API. Le connecteur utilise l’hôte de l’API et l’URL de base pour déterminer comment appeler l’API.

   

   Notes

   Pour plus d’informations sur la connexion aux API locales, accédez à Connectez-vous aux API locales à l’aide de la passerelle de données.

   La section suivante de la définition OpenAPI contient des informations pour cette page de l’interface utilisateur :

     "info": {
       "version": "1.0.0",
       "title": "SentimentDemo",
       "description": "Uses the Cognitive Services Text Analytics Sentiment API to determine whether text is positive or negative"
     },
     "host": "westus.api.cognitive.microsoft.com",
     "basePath": "/",
     "schemes": [
       "https"
     ]
   

Vérifier 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é dans la définition OpenAPI.

Sur la page Sécurité, consultez les informations d’authentification de la clé API.

L’étiquette s’affiche lorsque quelqu’un établit une première connexion avec le connecteur personnalisé ; vous pouvez sélectionner Modifier et modifier cette valeur. L’emplacement et le nom du paramètre doivent correspondre à ce que l’API attend, dans ce cas, Ocp-Apim-Subscription-Key et Header.

La section suivante de la définition OpenAPI contient des informations pour cette page de l’interface utilisateur :

  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  }

Vérifiez la définition du connecteur

La page Définition de 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. Pour plus d’informations sur la définition d’objets à partir de zéro dans cette interface utilisateur, accédez à Créer la définition de connecteur.

1. La zone suivante affiche l’ensemble des actions, déclencheurs (pour Logic Apps et Power Automate) et références définis pour le connecteur. Dans ce cas, l’action DetectSentiment de la définition OpenAPI s’affiche. Il n’y a pas de déclencheur dans ce connecteur, mais vous pouvez vous documenter sur les déclencheurs pour les connecteurs personnalisés dans 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é. Vous pouvez modifier les informations ici, y compris la propriété Visibility pour les opérations et les paramètres dans une application logique ou un flux :

   • aucune : s’affiche normalement dans l’application logique ou le flux

   • avancée : masqué sous un menu supplémentaire

   • interne : masqué pour l’utilisateur

   • importante : s’affiche toujours pour l’utilisateur en premier

     

3. La zone Requête affiche des informations en fonction de la requête HTTP incluse dans la définition OpenAPI. Dans ce cas, le verbe HTTP est POST et l’URL est /text/analytics/v2.0/sentiment (l’URL complète de l’API est <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>). Nous allons regarder de plus près le paramètre Corps sous peu.

   

   La section suivante de la définition OpenAPI contient des informations pour les zones Général et Requête de l’interface utilisateur :

   "paths": {
     "/text/analytics/v2.0/sentiment": {
       "post": {
         "summary": "Returns a numeric score representing the sentiment detected",
         "description": "The API returns a numeric score between 0 and 1. Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment.",
         "operationId": "DetectSentiment"
   

4. La zone Réponse affiche des informations en fonction de la réponse HTTP incluse dans la définition OpenAPI. Dans ce cas, la seule réponse définie est 200 (une bonne réponse), mais vous pouvez définir des réponses supplémentaires.

   

   La section suivante de la définition OpenAPI contient certaines informations liées à la réponse :

   "score": {
    "type": "number",
    "format": "float",
    "description": "score",
    "x-ms-summary": "score"
   },
   "id": {
    "type": "string",
    "description": "id",
    "x-ms-summary": "id"
   }
   

   Cette section présente les deux valeurs renvoyées par le connecteur : id et score. Elle comprend leurs types de données et le champ x-ms-summary, qui est une extension OpenAPI. Pour plus d’informations sur cette extension et sur d’autres extensions, accédez à Étendre une définition OpenAPI pour un connecteur personnalisé.

5. La zone Validation affiche tous les problèmes détectés dans la définition de l’API. Vérifiez cette zone avant d’enregistrer un connecteur.

   

Mettre à jour la définition

La définition OpenAPI que vous avez téléchargée est un bon exemple de base, mais vous pouvez utiliser des définitions qui impliquent beaucoup de mises à jour pour que le connecteur soit plus convivial lorsqu’un utilisateur s’en sert dans une application logique, un flux ou une application. Nous allons vous montrer comment apporter une modification à la définition.

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 la description du paramètre, puis sélectionnez Retour.

   

   Paramètre	Valeur
   Description	Identificateur numérique pour chaque document que vous envoyez

4. Dans la zone Paramètre, sélectionnez Retour pour revenir à la page de définition principale.

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

Télécharger le fichier OpenAPI mis à jour

Vous pouvez créer un connecteur personnalisé à partir d’un fichier OpenAPI ou à partir de zéro (dans Power Automate et Power Apps). Quelle que soit la façon dont vous créez le connecteur, vous pouvez télécharger la définition OpenAPI que le service utilise en interne.

• Dans Logic Apps, téléchargez-la à partir du connecteur personnalisé.

  

• Dans Power Automate ou Power Apps, téléchargez à partir de la liste des connecteurs personnalisés.

  

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. Sur la page Test, sélectionnez Nouvelle connexion.

   

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

   

3. Revenez à la Page de test et effectuez l’une des opérations suivantes :

   • Dans Power Automate, vous êtes redirigé sur la page Test. Sélectionnez l’icône d’actualisation pour vérifier que les informations de connexion ont été mises à jour.

     

   • Dans Power Apps, vous retournez à la liste des connexions disponibles dans l’environnement actuel. En haut à droite, sélectionnez l’icône en forme d’engrenage, puis Connecteurs personnalisés. Sélectionnez le connecteur que vous avez créé, puis revenez à la page Test.

     

4. Sur la page 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.

   

Étapes suivantes

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

• Utiliser un connecteur personnalisé à partir d’un flux
• Utiliser un connecteur personnalisé à partir d’une application
• Utiliser un connecteur personnalisé à partir d’une application logique

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