Créer un connecteur personnalisé à partir d’une collection Postman

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 Collection Postman qui décrit l’API Sentiment d’analyse de texte Cognitive Services (notre exemple pour cette série).

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

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

• Créer un connecteur personnalisé à partir de zéro

Conditions préalables

• Une collection Postman qui décrit l’exemple d’API :

  • Téléchargez la collection Postman que nous avons créée
    or
  • Terminez la rubrique Créer une collection Postman pour un connecteur personnalisé Notez que lorsque vous créez un connecteur personnalisé, la collection Postman doit être de taille inférieure à 1 Mo.

• 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 collection Postman

Vous êtes maintenant prêt à utiliser la collection Postman que vous avez créée ou téléchargée. Une grande partie des informations requises sont contenues dans la collection. Vous pouvez également consulter et mettre à jour ces informations au fur et à mesure que vous utilisez l’Assistant Connecteur personnalisé. Commencez par importer la collection Postman pour Logic Apps ou pour Power Automate et Power Apps.

Importer la collection Postman 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, choisissez Modifier.

   

3. En dessous de Général, choisissez Charger la collection Postman V1, puis accédez à la collection Postman que vous avez créée.

   

   L’Assistant importe la collection, puis la convertit en une définition OpenAPI nommée generatedApiDefinition.swagger.json.

Importer la collection Postman pour Power Automate et Power Apps

1. Accédez à make.powerapps.com ou à flow.microsoft.com.

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

3. Choisissez Nouveau connecteur personnalisé, puis Importer une collection Postman.

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

   

   Paramètre	active
   Titre du connecteur personnalisé	« SentimentDemo »

   L’Assistant importe la collection, puis la convertit en une définition OpenAPI nommée generatedApiDefinition.swagger.json.

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 trois technologies. Les différences seront mises en évidence.

1. Sur la page Général, passez en revue les informations qui ont été importées à partir de la collection Postman, y compris l’hôte et l’URL de base pour l’API. Le connecteur utilise l’hôte et l’URL de base pour déterminer comment appeler l’API.

   Notes

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

2. Mettez à jour la description pour qu’elle soit explicite. Cette description s’affiche dans les détails du connecteur personnalisé et permet aux autres utilisateurs de comprendre comment votre connecteur pourrait leur être utile.

   Paramètre	valeur
   Description	« Utilise l’API Sentiment d’analyse de texte Cognitive Services pour déterminer si le texte est positif ou négatif »

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é d’API.

1. Sur la page Sécurité sous Type d’authentification, choisissez Clé API.

2. Sous Clé API, spécifiez une étiquette, un nom et un emplacement de paramètre. Choisissez une étiquette descriptive et explicite. Ce texte sera affiché aux utilisateurs pour qu’ils puissent effectuer des connexions à l’aide de votre connecteur personnalisé. L’emplacement et le nom du paramètre doivent correspondre à ce que l’API attend (dans ce cas, il s’agit de l’en-tête que vous avez spécifié dans Postman). Sélectionnez Se connecter.

   

   Paramètre	valeur
   É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.

Vérifier et mettre à jour 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 flows 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.

Vérifier l’interface utilisateur et la définition

Avant de passer à certaines étapes spécifiques de la page Définition, jetons d’abord un œil à l’interface utilisateur.

1. Cette zone 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 collection Postman 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é. Ces informations proviennent de la collection Postman. 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 :

   • importante : s’affiche toujours pour l’utilisateur en premier
   • aucune : s’affiche normalement dans l’application logique ou le flux
   • avancée : initialement masqués sous un menu supplémentaire
   • interne : non présentés à l’utilisateur

3. La zone Requête affiche des informations en fonction de la requête HTTP incluse dans la collection Postman. 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.

4. La zone Réponse affiche des informations en fonction de la réponse HTTP qui est incluse dans la collection Postman. 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.

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

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

1. Dans la zone Général, mettez à jour le résumé sur « Renvoie un score numérique représentant le sentiment détecté ».

2. Dans la zone Requête, choisissez corps, puis Modifier.

3. Dans la zone Paramètre, vous voyez maintenant les trois paramètres que l’API attend : id, language et text. Choisissez ID, puis Modifier.

4. Dans la zone Propriété de schéma, mettez à jour les valeurs du paramètre, puis choisissez Retour.

   

   Paramètre	valeur
   Titre	« ID »
   Description	« Un identificateur pour chaque document que vous envoyez »
   Valeur par défaut	« 1 »
   Obligatoire	« Oui »

5. Dans la zone Paramètre, choisissez Langue, puis Modifier et répétez le processus utilisé ci-dessus avec les valeurs suivantes.

   Paramètre	valeur
   Titre	« Langue »
   Description	« Le code de langue de 2 ou 4 caractères correspondant au texte »
   Valeur par défaut	« en »
   Obligatoire	« Oui »

6. Dans la zone Paramètre, choisissez Texte, puis Modifier et répétez le processus utilisé ci-dessus avec les valeurs suivantes.

   Paramètre	valeur
   Titre	"Texte"
   Description	« Le texte à analyser pour détecter le sentiment »
   Valeur par défaut	Aucun(e)
   Obligatoire	« Oui »

7. Dans la zone Paramètre, choisissez Retour pour revenir à la page de définition principale.

8. En haut à droite de l’Assistant, sélectionnez Mettre à jour le connecteur.

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, choisissez 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 Test :

   • 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 êtes renvoyé à la liste des connexions disponibles dans l’environnement actuel. En haut à droite, sélectionnez l’icône 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.

   

Limitations

Dans Power Automate et Power Apps, si vous mettez à jour un connecteur personnalisé existant à l’aide d’une collection Postman, vous devrez refaire toutes les personnalisations précédentes avant d’enregistrer le connecteur. Par exemple, vous devrez reconfigurer le type d’authentification, les valeurs par défaut des paramètres des actions, etc.

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