Bot de commande dans Teams

Article
06/27/2023

Microsoft Teams vous permet d’automatiser des tâches simples et répétitives dans une conversation. Vous pouvez créer un bot de commande qui peut répondre à des commandes simples envoyées dans des conversations avec des cartes adaptatives. Vous pouvez créer un modèle de bot de commande dans teams Toolkit qui répond aux commandes de conversation en affichant l’interface utilisateur à l’aide d’une carte adaptative. Cela permet aux utilisateurs d’envoyer des messages dans Teams et votre application peut fournir une réponse si nécessaire.

Le modèle de bot de commande est généré à l’aide du Kit de développement logiciel (SDK) TeamsFx, qui fournit un ensemble simple de fonctions sur le Microsoft Bot Framework. Le bot de commande peut être utilisé dans différents scénarios, tels que la vérification des status de ticket et la récupération d’informations d’aide.

Avantages

Automatise les tâches simples et répétitives avec une commande de conversation.
Simplifie le modèle de programmation avec le Kit de développement logiciel (SDK) TeamsFx, basé sur le Kit de développement logiciel (SDK) Bot Framework.
Prend en charge les expressions régulières pour le traitement des commandes.

Installation du bot de commande

Un bot de commande doit être installé dans une équipe, une conversation de groupe ou en tant qu’application personnelle, en fonction de l’étendue requise. Vous devez sélectionner la cible d’installation avant d’ajouter le bot à votre application.

sélection de l’option d’installation

Pour plus d’options d’installation, consultez Configurer les options d’installation par défaut. Pour la désinstallation, consultez Supprimer une application de Teams.

Commande et réponse

Les bots de commande et de réponse TeamsFx sont créés à l’aide du Kit de développement logiciel (SDK) Bot Framework. Le Kit de développement logiciel (SDK) Bot Framework fournit un gestionnaire de messages intégré pour gérer l’activité des messages entrants, ce qui vous oblige à comprendre le concept de Bot Framework, tel que le modèle de conversation piloté par les événements. Le Kit de développement logiciel (SDK) TeamsFx fournit une couche d’abstraction de commande-réponse pour permettre aux utilisateurs de se concentrer sur la gestion de la demande de commande en fonction des besoins de l’entreprise, sans apprendre le Kit de développement logiciel (SDK) Bot Framework.

Le Kit de développement logiciel (SDK) TeamsFx extrait l’intergiciel Bot Framework pour gérer l’intégration avec les gestionnaires d’activités sous-jacents. Si le texte du message reçu correspond au modèle de commande fourni dans un TeamsFxBotCommandHandler instance, le middleware gère l’activité de message entrant et appelle la fonction correspondantehandlerCommandReceived. Le middleware appelle context.sendActivity pour envoyer la réponse de commande retournée par la handlerCommandReceived fonction à l’utilisateur.

Personnaliser l’initialisation

Vous devez créer ConversationBot pour répondre à la commande dans une conversation. Vous pouvez initialiser avec ConversationBot votre adaptateur ou personnaliser après l’initialisation.

JavaScript/TypeScript
C#

/** JavaScript/TypeScript: src/internal/initialize.js(ts) **/
const commandApp = new ConversationBot({
  // The bot id and password to create CloudAdapter.
  // See https://aka.ms/about-bot-adapter to learn more about adapters.
  adapterConfig: {
    MicrosoftAppId: config.botId,
    MicrosoftAppPassword: config.botPassword,
    MicrosoftAppType: "MultiTenant",
  },
  command: {
    enabled: true,
    commands: [new HelloWorldCommandHandler()],
  },
});

builder.Services.AddSingleton<HelloWorldCommandHandler>();
builder.Services.AddSingleton(sp =>
{
    var options = new ConversationOptions()
    {
        Adapter = sp.GetService<CloudAdapter>(),
        Command = new CommandOptions()
        {
            Commands = new List<ITeamsCommandHandler> { sp.GetService<HelloWorldCommandHandler>() }
        }
    };

    return new ConversationBot(options);
});

Personnaliser l’adaptateur

// Create your own adapter
const adapter = new CloudAdapter(...);

// Customize your adapter, e.g., error handling
adapter.onTurnError = ...

const bot = new ConversationBot({
    // use your own adapter
    adapter: adapter;
    ...
});

// Or, customize later
bot.adapter.onTurnError = ...

Ajouter une commande et une réponse

Vous pouvez effectuer les étapes suivantes pour ajouter une commande et des réponses :

1. Ajouter une définition de commande dans le manifeste

Vous pouvez modifier le fichier appPackage\manifest.json de modèle manifeste pour mettre à jour les title propriétés et description de doSomething la commande dans le commands tableau comme suit :

"commandLists": [
  {
    "commands": [
        {
            "title": "helloWorld",
            "description": "A helloworld command to send a welcome message"
        },
        {
            "title": "doSomething",
            "description": "A sample do something command"
        }
    ]
  }
]

Pour plus d'informations, voir app manifest

2. Répondre avec une carte adaptative

Vous pouvez définir votre carte au format JSON pour répondre avec une carte adaptative. Créez un fichier dans le chemin d’accès suivant pour JavaScript ou TypeScript et .NET comme suit :

Pour JavaScript ou TypeScript : src/adaptiveCards/doSomethingCommandResponse.json
Pour .NET : Resources/DoSomethingCommandResponse.json

Ajoutez le code JSON suivant à et DoSomethingCommandResponse:doSomethingCommandResponse.json

    {
           "type": "AdaptiveCard",    
           "body": [
               {
                   "type": "TextBlock",
                   "size": "Medium",
                   "weight": "Bolder",
                   "text": "Your doSomething Command is added!"
               },
         {
                   "type": "TextBlock",
                   "text": "Congratulations! Your hello world bot now includes a new DoSomething Command",
                   "wrap": true
         }
      ],
      "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
      "version": "1.4"
    }

Répondez avec du texte brut ou avec une carte adaptative. Vous pouvez utiliser la Designer de carte adaptative pour vous aider à concevoir visuellement l’interface utilisateur de votre carte adaptative. Pour plus d’informations sur l’envoi d’une carte adaptative avec des données dynamiques, consultez Générer une commande et une réponse à l’aide de la carte adaptative.

3. Gérer la commande

Voici les gestionnaires de commandes JavaScript, TypeScript et C# pour gérer la commande :

Le Kit de développement logiciel (SDK) TeamsFx fournit une classe TeamsFxBotCommandHandlerpratique à gérer lorsqu’une commande est déclenchée à partir d’un message de conversation Teams. Créez un fichier dans le chemin d’accès src/doSomethingCommandHandler.js.

Ajoutez le code suivant au doSomethingCommandHandler.js fichier :

const doSomethingCard = require("./adaptiveCards/doSomethingCommandResponse.json");
const { AdaptiveCards } = require("@microsoft/adaptivecards-tools");
const { CardFactory, MessageFactory } = require("botbuilder");

class DoSomethingCommandHandler {
  triggerPatterns = "doSomething";

  async handleCommandReceived(context, message) {
    // verify the command arguments which are received from the client if needed.
    console.log(`App received message: ${message.text}`);

    const cardData = {
      title: "doSomething command is added",
      body: "Congratulations! You have responded to doSomething command",
    };

    const cardJson = AdaptiveCards.declare(doSomethingCard).render(cardData);
    return MessageFactory.attachment(CardFactory.adaptiveCard(cardJson));
  }
}

module.exports = {
  DoSomethingCommandHandler,
};

Ajoutez le code suivant au doSomethingCommandHandler.ts fichier :

/** TypeScript **/
import { Activity, CardFactory, MessageFactory, TurnContext } from "botbuilder";
import {
 CommandMessage,
 TeamsFxBotCommandHandler,
 TriggerPatterns,
 MessageBuilder,
} from "@microsoft/teamsfx";
import doSomethingCard from "./adaptiveCards/doSomethingCommandResponse.json";
import { AdaptiveCards } from "@microsoft/adaptivecards-tools";
import { CardData } from "./cardModels";

export class DoSomethingCommandHandler implements TeamsFxBotCommandHandler {
 triggerPatterns: TriggerPatterns = "doSomething";

 async handleCommandReceived(
   context: TurnContext,
   message: CommandMessage
 ): Promise<string | Partial<Activity>> {
   // verify the command arguments which are received from the client if needed.
   console.log(`App received message: ${message.text}`);

   const cardData: CardData = {
     title: "doSomething command is added",
     body: "Congratulations! You have responded to doSomething command",
   };

   const cardJson = AdaptiveCards.declare(doSomethingCard).render(cardData);
   return MessageFactory.attachment(CardFactory.adaptiveCard(cardJson));
 }
}

Le SDK .NET TeamsFx fournit une interface ITeamsCommandHandler pour le gestionnaire de commandes à gérer lorsqu’une commande est déclenchée à partir d’un message de conversation Teams. Créez un fichier dans le chemin d’accès Commands/DoSomethingCommandHandler.cs.

Ajoutez le code suivant à :DoSomethingCommandHandler.cs

using MyCommandApp.Models;
using AdaptiveCards.Templating;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;
using Microsoft.TeamsFx.Conversation;
using Newtonsoft.Json;

namespace MyCommandApp.Commands
{
    public class DoSomethingCommandHandler : ITeamsCommandHandler
    {
        private readonly ILogger<HelloWorldCommandHandler> _logger;
        private readonly string _adaptiveCardFilePath = Path.Combine(".", "Resources", "DoSomethingCommandResponse.json");

        public IEnumerable<ITriggerPattern> TriggerPatterns => new List<ITriggerPattern>
        {
            new RegExpTrigger("doSomething")
        };

        public HelloWorldCommandHandler(ILogger<HelloWorldCommandHandler> logger)
        {
            _logger = logger;
        }

        public async Task<ICommandResponse> HandleCommandAsync(ITurnContext turnContext, CommandMessage message, CancellationToken cancellationToken = default)
        {
            _logger?.LogInformation($"App received message: {message.Text}");

            // Read adaptive card template
            var cardTemplate = await File.ReadAllTextAsync(_adaptiveCardFilePath, cancellationToken);

            // Render adaptive card content
            var cardContent = new AdaptiveCardTemplate(cardTemplate).Expand
            (
                new HelloWorldModel
                {
                    title: "doSomething command is added",
                    body: "Congratulations! You have responded to doSomething command",
                }
            );

            // Build attachment
            var activity = MessageFactory.Attachment
            (
                new Attachment
                {
                    ContentType = "application/vnd.microsoft.card.adaptive",
                    Content = JsonConvert.DeserializeObject(cardContent),
                }
            );

            // send response
            return new ActivityCommandResponse(activity);
        }
    }
}

Vous pouvez personnaliser la commande, notamment appeler une API, traiter des données ou toute autre commande .

4. Inscrire la nouvelle commande

Chaque nouvelle commande doit être configurée dans le ConversationBot, qui lance le flux conversationnel du modèle de bot de commande.

JavaScript/TypeScript
C#

/** Update ConversationBot  in src/internal/initialize.js(ts) **/
const commandApp = new ConversationBot({
  //...
  command: {
    enabled: true,
    commands: [ 
      new HelloWorldCommandHandler(),
      new DoSomethingCommandHandler()], // newly added command handler
  },
});

/** Update ConversationBot in Program.cs **/
builder.Services.AddSingleton<HelloWorldCommandHandler>();
builder.Services.AddSingleton<DoSomethingCommandHandler>(); // Add doSomething command handler to serrvice container
builder.Services.AddSingleton(sp =>
{
    var options = new ConversationOptions()
    {
        Adapter = sp.GetService<CloudAdapter>(),
        Command = new CommandOptions()
        {
            Commands = new List<ITeamsCommandHandler>
            { 
                sp.GetService<HelloWorldCommandHandler>(),
                sp.GetService<DoSomethingCommandHandler>(),  // Register doSomething command handler to ConversationBot
            }
        }
    };

    return new ConversationBot(options);
});

Appuyez sur F5 pour déboguer localement ou provisionner et déployer des commandes pour déployer la modification sur Azure.

Personnaliser le modèle de déclencheur

Le modèle par défaut pour déclencher une commande est via un mot clé défini. Vous pouvez également collecter et traiter des informations supplémentaires récupérées à partir du déclencheur mot clé. En plus de mot clé correspondance, vous pouvez également définir votre modèle de déclencheur avec des expressions régulières et faire correspondre par rapport message.text à d’autres contrôles.

Vous pouvez trouver n’importe quel groupe de capture dans message.matches, lorsque vous utilisez des expressions régulières. Par exemple, si l’utilisateur entre reboot myMachine, message.matches[1], il capture myMachine. L’exemple suivant utilise l’expression régulière pour capturer des chaînes après reboot:

class HelloWorldCommandHandler {
  triggerPatterns = /^reboot (.*?)$/i; //"reboot myDevMachine";
  async handleCommandReceived(context, message) {
    console.log(`Bot received message: ${message.text}`);
    const machineName = message.matches[1];
    console.log(machineName);
    // Render your adaptive card for reply message
    const cardData = {
      title: "Your Hello World Bot is Running",
      body: "Congratulations! Your hello world bot is running. Click the button below to trigger an action.",
    };
    const cardJson = AdaptiveCards.declare(helloWorldCard).render(cardData);
    return MessageFactory.attachment(CardFactory.adaptiveCard(cardJson));
  }
}

Générer une commande et une réponse à l’aide de la carte adaptative avec du contenu dynamique

La carte adaptative fournit un langage de modèle pour permettre aux utilisateurs de restituer du contenu dynamique avec la même disposition (le modèle). Par exemple, utilisez la carte adaptative pour afficher une liste d’éléments, tels que des éléments de tâche ou affecter des bogues qui varient d’un utilisateur à l’autre.

Vous pouvez effectuer les étapes suivantes pour générer une commande et une réponse à l’aide de la carte adaptative avec du contenu dynamique :

Ajoutez votre fichier JSON de modèle de carte adaptative sous le bot/adaptiveCards dossier .
Dans le fichier de code où se trouve le gestionnaire commnad, par exemple myCommandHandler.ts. Importez le fichier JSON du modèle de carte adaptative.
Modélisez vos données carte.
Utilisez MessageBuilder.attachAdaptiveCard dans le modèle avec des données carte dynamiques.

Si nécessaire, vous pouvez ajouter de nouvelles cartes pour votre application. Pour plus d’informations sur la façon de créer différents types de cartes adaptatives avec une liste ou une table des matières dynamiques à l’aide ColumnSet de et FactSet, consultez exemple.

Accéder à Microsoft Graph

Si vous répondez à une commande qui doit accéder aux données Microsoft Graph d’un utilisateur Teams déjà connecté, vous pouvez le faire par authentification unique (SSO) avec son jeton d’utilisateur Teams. En savoir plus sur la façon dont Teams Toolkit peut vous aider à ajouter l’authentification unique à l’application Teams.

Se connecter à des API existantes

Si vous n’avez pas le KIT de développement logiciel (SDK) requis et que vous devez appeler des API externes dans votre code, vous pouvez utiliser la commande Teams : Se connecter à une API dans l’extension Microsoft Visual Studio Code (VS Code) Teams Toolkit, ou la commande teamsfx add api-connection dans TeamsFx CLI pour démarrer le code afin d’appeler des API cibles. Pour plus d’informations, consultez Configurer la connexion d’API.

Forum aux questions

Comment étendre ma commande et ma réponse aux notifications de support ?

Accédez à bot\src\internal\initialize.ts(js) et mettez à jour votre conversationBot initialisation pour activer la fonctionnalité de notification.
Pour personnaliser l’envoi de la notification, consultez Envoyer une notification à la cible d’installation du bot.
1. Si vous souhaitez ajouter rapidement un exemple de notification déclenchée par une requête HTTP, ajoutez l’exemple de code suivant dans bot\src\index.ts(js):
```
server.post("/api/notification", async (req, res) => {
  for (const target of await commandBot.notification.installations()) {
    await target.sendMessage("This is a sample notification message");
  }

  res.json({});
});
```
Désinstallez votre installation de bot précédente de Teams et exécutez le débogage local pour tester votre notification de bot.
Envoyez une notification aux cibles d’installation du bot (canal, conversation de groupe ou conversation personnelle) à l’aide d’une requête HTTP POST avec l’URL https://localhost:3978/api/notificationcible .

Pour envoyer une notification avec la carte adaptative et ajouter d’autres déclencheurs, consultez Bot de notification dans Teams.

Comment étendre mon bot de commande en ajoutant des actions de carte adaptative de bot de workflow ?

La fonctionnalité gestionnaire d’actions de carte adaptative permet à l’application de répondre aux actions de carte adaptative déclenchées par les utilisateurs pour effectuer un workflow séquentiel. Une carte adaptative fournit un ou plusieurs boutons dans le carte pour demander l’entrée de l’utilisateur, par exemple, appeler certaines API. La carte adaptative envoie ensuite une autre carte adaptative dans la conversation pour répondre à l’action carte.

Pour plus d’informations sur l’ajout d’actions de carte adaptative à un bot de commande, consultez Bot de flux de travail dans Teams.

Guide pas à pas

Suivez le guide pas à pas pour créer un bot De commande Teams.