Build d’extensions de messages
Les extensions de message permettent aux utilisateurs d’interagir avec votre service web via des boutons et des formulaires dans le client Microsoft Teams. Les utilisateurs effectuer des recherches ou lancer des actions, dans un système externe à partir de la zone de rédaction de message, de la zone de commande ou directement d’un message. Les résultats de ces interactions peuvent être retournés au client Teams sous la forme d’un carte au format enrichi.
Importante
Les extensions de message ne sont pas disponibles dans les environnements Cloud de la communauté du secteur public (GCC), GCC-High et department of Defense (DOD).
L’article fournit une vue d’ensemble des extensions de message, des cas d’usage, des fonctionnalités, des commandes d’action et de recherche, ainsi que du déploiement de liens.
L’image suivante affiche les emplacements à partir desquels les extensions de message peuvent être appelées :
Remarque
- @mentioning les extensions de message dans la zone de composition ne sont pas prises en charge.
- Les options d’extension de message ne sont pas prises en charge pour les conversations de groupe avec des utilisateurs externes.
Scénarios dans lesquels les extensions de message sont utilisées
| Scénario | Exemple |
|---|---|
| Vous avez besoin d’un système externe pour effectuer une action et retourner le résultat à votre conversation. | Réservez une ressource et autorisez le canal à connaître l’intervalle de temps réservé. |
| Vous devez rechercher quelque chose dans un système externe et partager les résultats avec la conversation. | Recherchez un élément de travail dans Azure DevOps et partagez-le avec le groupe sous forme de carte adaptative. |
| Vous souhaitez effectuer une tâche complexe impliquant plusieurs étapes ou de grandes quantités d’informations dans un système externe et partager les résultats avec une conversation. | Créez un bogue dans votre système de suivi basé sur un message Teams, affectez ce bogue et envoyez un carte au thread de conversation avec les détails du bogue. |
Comprendre le fonctionnement des extensions de message
Une extension de message est composée d’un service web hébergé par vous et d’un manifeste d’application qui définit l’emplacement où votre service web est appelé dans le client Teams. Le service web utilise le schéma de messagerie de Bot Framework et le protocole de communication sécurisé. Vous devez donc inscrire votre service web en tant que bot dans Bot Framework.
Remarque
Bien qu’il soit possible de créer manuellement le service web, nous vous recommandons d’utiliser le Kit de développement logiciel (SDK) Bot Framework pour utiliser le protocole.
Dans le manifeste de l’application (précédemment appelé manifeste d’application Teams), une seule extension de message est définie avec jusqu’à 10 commandes différentes. Chaque commande définit un type, tel que l’action ou la recherche et les emplacements dans le client à partir desquels l’extension de message est appelée. Les emplacements d’appel incluent la zone de rédaction des messages, la barre de commandes et le message. Lors de l’appel, le service web reçoit un message HTTPS avec une charge utile JSON avec toutes les informations pertinentes. Répondez avec une charge utile JSON pour informer le client Teams de l’interaction suivante à activer.
Types de commandes d’extension de message
Il existe deux types de commandes d’extension de message, la commande d’action et la commande de recherche. Le type de commande d’extension de message définit les éléments d’interface utilisateur et les flux d’interaction disponibles pour votre service web. Certaines interactions, telles que l’authentification et la configuration, sont disponibles pour les deux types de commandes.
Commandes d’action
Les commandes d’action sont utilisées pour présenter aux utilisateurs une fenêtre contextuelle modale afin de collecter ou d’afficher des informations. Lorsque l’utilisateur envoie le formulaire, votre service web répond en insérant un message directement dans la conversation ou dans la zone de rédaction du message. Plus tard, l’utilisateur peut envoyer le message. Pour les flux de travail plus complexes, vous pouvez lier plusieurs formulaires entre eux.
Les commandes d’action sont déclenchées à partir de la zone de rédaction du message, de la zone de commande ou d’un message. Lorsque la commande est appelée à partir d’un message, la charge utile JSON initiale envoyée à votre bot inclut l’intégralité du message à partir duquel elle a été appelée. L’image suivante affiche la boîte de dialogue de commande d’action d’extension de message (appelée module de tâche dans TeamsJS v1.x) :
Commandes de recherche
Les commandes de recherche permettent aux utilisateurs de rechercher des informations dans un système externe. Pour utiliser les commandes de recherche, entrez une requête manuellement dans la zone de recherche ou insérez un lien vers un domaine surveillé dans la zone de rédaction de message, puis incorporez les résultats de la recherche dans un message. Dans un flux de commande de recherche simple, le message d’appel initial inclut la chaîne de recherche soumise par l’utilisateur. Vous répondez avec une liste de cartes et d’aperçus de cartes. Le client Teams affiche une liste d’aperçus de carte pour l’utilisateur. Lorsque l'utilisateur sélectionne une carte dans la liste, la carte en taille réelle est insérée dans la zone de composition du message.
Les cartes sont déclenchées à partir de la zone de rédaction du message ou de la zone de commande, mais pas à partir d’un message. Ils ne peuvent pas être déclenchés à partir d’un message. L’image suivante affiche la boîte de dialogue de la commande de recherche d’extension de message :
Remarque
Pour plus d’informations sur les cartes, voir ce que sont les cartes.
Déploiement de lien
Remarque
Le déploiement de liens est pris en charge uniquement pour les extensions de message basées sur un bot.
Lorsqu’une URL est collée dans la zone de rédaction du message, un service web est appelé. Cette fonctionnalité est appelée déploiement de liens. Vous pouvez vous abonner pour recevoir un message d’appel lorsque des URL contenant un domaine spécifique sont collées dans la zone de rédaction du message. Votre service web peut déployer l’URL dans un carte détaillé, en fournissant plus d’informations que les carte d’aperçu de site web standard. Vous pouvez ajouter des boutons pour permettre aux utilisateurs d’agir immédiatement sans quitter le client Teams. Les images suivantes affichent la fonctionnalité de déploiement de lien lorsqu’un lien est collé dans une extension de message :
Build d’extensions de messages
Pour générer une extension de message, si vous n’en avez pas déjà une, il existe deux façons :
Créer des extensions de message à l’aide de l’API (basée sur l’API) : vous pouvez facilement créer une extension de message à partir d’une API existante. Un document OpenAPI Description (OAD) est requis pour cette méthode.
Créer des extensions de message à l’aide de Bot Framework (basé sur un bot) : si vous souhaitez une expérience conversationnelle en un-à-un, vous pouvez créer une extension de message à partir d’un bot.
Le tableau suivant vous aide à sélectionner un type d’extension de message pour commencer :
Extension de message basée sur l’API
- Création et maintenance plus simples et plus rapides.
- L’extension de message utilise une API.
- Aucune ressource ou code supplémentaire n’est nécessaire pour la logique du bot.
- Idéal pour les scénarios où l’extension de message doit uniquement communiquer avec un service web et n’a pas besoin d’une logique ou d’une gestion d’état complexe.
- Le trafic est privatisé, car il ne dépend pas de l’infrastructure de bot Azure.
- Prend en charge les commandes de recherche.
Extension de message basé sur un bot
- Plus flexible.
- L’extension de message utilise un Bot Framework.
- Peut utiliser toutes les fonctionnalités d’un bot.
- Idéal pour les scénarios où l’extension de message doit communiquer avec plusieurs services, gérer une logique complexe ou des interactions utilisateur, ou maintenir l’état entre les sessions.
- Prend en charge les commandes d’action, les commandes de recherche et le déploiement de liens.
Sélectionnez une option pour commencer à créer une extension de message :
Exemple de code
| Exemple de nom | Description | .NET | Node.js | Python | Manifeste |
|---|---|---|---|---|---|
| Extension de message avec des commandes basées sur des actions | Cet exemple montre comment définir des commandes d’action, créer un dialogue et répondre à l’action d’envoi du dialogue. | View | View | View | View |
| Extension de message avec des commandes basées sur la recherche | Cet exemple montre comment créer une extension de message basée sur la recherche. Il recherche les packages NuGet et affiche les résultats dans l’extension de messagerie basée sur la recherche. | View | View | View | View |
| Aperçu de l’action d’extension de message | Cet exemple montre comment utiliser l’aperçu de l’action dans Les extensions de messagerie à l’aide de Bot Framework v4. | View | View | N/A | View |
| Action d’extension de message pour la planification des tâches | Cet exemple montre comment planifier une tâche à partir de la commande d’action d’extension de message et obtenir un rappel carte à une date et une heure planifiées. | View | View | N/A | View |
| Extension de message d’inventaire Northwind | Cet exemple montre comment utiliser une extension de message Teams comme plug-in dans Microsoft 365 Copilot. | N/A | View | N/A | N/A |