Befehlsbot in Teams

Artikel
06/27/2023

Mit Microsoft Teams können Sie einfache und sich wiederholende Aufgaben in einer Unterhaltung automatisieren. Sie können einen Befehlsbot erstellen, der auf einfache Befehle reagieren kann, die in Chats mit adaptiven Karten gesendet werden. Sie können im Teams Toolkit eine Befehlsbotvorlage erstellen, die auf Chatbefehle reagiert, indem Sie die Benutzeroberfläche mithilfe einer adaptiven Karte anzeigen. Dadurch können Benutzer Nachrichten in Teams senden, und Ihre App kann nach Bedarf eine Antwort bereitstellen.

Die Befehlsbotvorlage wird mithilfe des TeamsFx SDK erstellt, das einen einfachen Satz von Funktionen über die Microsoft Bot Framework bereitstellt. Der Befehlsbot kann in verschiedenen Szenarien verwendet werden, z. B. zum Überprüfen von Ticket-status und Abrufen von Hilfeinformationen.

Vorteile

Automatisiert einfache und sich wiederholende Aufgaben mit einem Chatbefehl.
Vereinfacht das Programmiermodell mit dem TeamsFx SDK, das auf dem Bot Framework SDK basiert.
Unterstützt reguläre Ausdrücke für die Verarbeitung von Befehlen.

Installation des Befehlsbots

Je nach erforderlichem Bereich muss ein Befehlsbot in einem Team, einem Gruppenchat oder als persönliche App installiert werden. Sie müssen das Installationsziel auswählen, bevor Sie den Bot zu Ihrer App hinzufügen.

Auswahl der Installationsoption

Weitere Installationsoptionen finden Sie unter Konfigurieren von Standardinstallationsoptionen. Informationen zum Deinstallieren finden Sie unter Entfernen einer App aus Teams.

Befehl und Antwort

Die TeamsFx-Befehls- und Antwortbots werden mithilfe des Bot Framework SDK erstellt. Das Bot Framework SDK bietet einen integrierten Nachrichtenhandler für die Verarbeitung der Aktivität eingehender Nachrichten. Daher müssen Sie das Bot Framework-Konzept verstehen, z. B. das ereignisgesteuerte Konversationsmodell. Das TeamsFx SDK bietet eine Befehls-Antwort-Abstraktionsschicht, mit der sich benutzer auf die Verarbeitung der Befehlsanforderung gemäß den geschäftlichen Anforderungen konzentrieren können, ohne sich mit dem Bot Framework SDK vertraut zu machen.

TeamsFx SDK ruft Bot Framework-Middleware ab, um die Integration mit den zugrunde liegenden Aktivitätshandlern zu verarbeiten. Wenn der empfangene Nachrichtentext mit dem in einem TeamsFxBotCommandHandler instance bereitgestellten Befehlsmuster übereinstimmt, verarbeitet die Middleware die eingehende Nachrichtenaktivität und ruft die entsprechende handlerCommandReceived Funktion auf. Die Middleware ruft auf context.sendActivity , um die von der handlerCommandReceived Funktion zurückgegebene Befehlsantwort an den Benutzer zu senden.

Anpassen der Initialisierung

Sie müssen erstellen ConversationBot , um auf den Befehl in einem Chat zu reagieren. Sie können mit Ihrem Adapter initialisieren oder nach der ConversationBot Initialisierung anpassen.

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);
});

Anpassen des Adapters

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

Hinzufügen von Befehl und Antwort

Sie können die folgenden Schritte ausführen, um Befehle und Antworten hinzuzufügen:

1. Hinzufügen einer Befehlsdefinition im Manifest

Sie können die Manifestvorlagendatei appPackage\manifest.json wie folgt bearbeiten, um die title Eigenschaften und description für doSomething den commands Befehl im Array zu aktualisieren:

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

Weitere Informationen finden Sie unter App-Manifest.

2. Antworten mit einer adaptiven Karte

Sie können Ihre Karte im JSON-Format definieren, um mit einer adaptiven Karte zu antworten. Erstellen Sie eine neue Datei im folgenden Pfad für JavaScript oder TypeScript und .NET wie folgt:

Für JavaScript oder TypeScript: src/adaptiveCards/doSomethingCommandResponse.json
Für .NET: Resources/DoSomethingCommandResponse.json

Fügen Sie und den folgenden JSON-Code hinzu doSomethingCommandResponse.jsonDoSomethingCommandResponse:

    {
           "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"
    }

Antworten Sie mit Nur-Text oder mit einer adaptiven Karte. Sie können die adaptive Karten-Designer verwenden, um die Benutzeroberfläche für adaptive Karten visuell zu entwerfen. Weitere Informationen zum Senden einer adaptiven Karte mit dynamischen Daten finden Sie unter Buildbefehl und Antwort mithilfe von adaptiven Karte.

3. Behandeln des Befehls

Im Folgenden finden Sie die JavaScript-, TypeScript- und C#-Befehlshandler zum Behandeln des Befehls:

Das TeamsFx SDK bietet eine praktische Klasse TeamsFxBotCommandHandler, die behandelt werden kann, wenn ein Befehl aus einer Teams-Konversationsnachricht ausgelöst wird. Erstellen Sie eine neue Datei im Pfad src/doSomethingCommandHandler.js.

Fügen Sie der Datei den doSomethingCommandHandler.js folgenden Code hinzu:

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,
};

Fügen Sie der Datei den doSomethingCommandHandler.ts folgenden Code hinzu:

/** 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));
 }
}

TeamsFx .NET SDK bietet eine Schnittstelle ITeamsCommandHandler für den Befehlshandler, der behandelt werden kann, wenn ein Befehl von einer Teams-Konversationsnachricht ausgelöst wird. Erstellen Sie eine neue Datei im Pfad Commands/DoSomethingCommandHandler.cs.

Fügen Sie dem folgenden Code hinzu 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);
        }
    }
}

Sie können den Befehl anpassen, einschließlich des Aufrufs einer API, der Verarbeitung von Daten oder eines anderen Befehls.

4. Registrieren des neuen Befehls

Jeder neue Befehl muss in ConversationBotkonfiguriert werden, wodurch der Konversationsfluss der Befehlsbotvorlage initiiert wird.

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);
});

Drücken Sie F5 , um lokal zu debuggen oder Befehle bereitzustellen, um die Änderung in Azure bereitzustellen.

Anpassen des Triggermusters

Das Standardmuster zum Auslösen eines Befehls erfolgt über eine definierte Schlüsselwort (keyword). Sie können auch zusätzliche Informationen sammeln und verarbeiten, die vom Trigger Schlüsselwort (keyword) abgerufen wurden. Zusätzlich zu Schlüsselwort (keyword) Können Sie auch Ihr Triggermuster mit regulären Ausdrücken definieren und mit weiteren Steuerelementen abgleichenmessage.text.

Sie können eine beliebige Erfassungsgruppe in message.matchesfinden, wenn Sie reguläre Ausdrücke verwenden. Wenn der Benutzer z. B. , eingibtreboot myMachine, wird erfasstmyMachine. message.matches[1] Im folgenden Beispiel wird ein regulärer Ausdruck verwendet, um Zeichenfolgen nach rebootzu erfassen:

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));
  }
}

Erstellen von Befehl und Antwort mit adaptiver Karte mit dynamischem Inhalt

Adaptive Karte bietet Vorlagensprache , mit der Benutzer dynamische Inhalte mit demselben Layout (der Vorlage) rendern können. Verwenden Sie beispielsweise die adaptive Karte, um eine Liste von Elementen zu rendern, z. B. Aufgabenelemente, oder weisen Sie Fehler zu, die je nach Benutzer variieren.

Sie können die folgenden Schritte ausführen, um Den Befehl und die Antwort mithilfe der adaptiven Karte mit dynamischem Inhalt zu erstellen:

Fügen Sie die JSON-Datei der Vorlage für adaptive Karten unter dem bot/adaptiveCards Ordner hinzu.
In der Codedatei, in der der Commnad-Handler vorhanden ist, z. B myCommandHandler.ts. . Importieren Sie die JSON-Datei der Vorlage für adaptive Karten.
Modellieren Sie Ihre Karte Daten.
Verwenden Sie MessageBuilder.attachAdaptiveCard in der Vorlage mit dynamischen Karte Daten.

Bei Bedarf können Sie neue Karten für Ihre Anwendung hinzufügen. Weitere Informationen zum Erstellen verschiedener Typen von adaptiven Karten mit einer Liste oder ein Dynamisches Inhaltsverzeichnis mit und ColumnSetFactSetfinden Sie im Beispiel.

Zugreifen auf Microsoft Graph

Wenn Sie auf einen Befehl reagieren, der auf Microsoft Graph-Daten eines bereits angemeldeten Teams-Benutzers zugreifen muss, können Sie dies durch einmaliges Anmelden (Single Sign-On, SSO) mit dessen Teams-Benutzertoken tun. Erfahren Sie mehr darüber, wie Teams Toolkit Ihnen beim Hinzufügen des einmaligen Anmeldens in der Teams-App helfen kann.

Herstellen einer Verbindung mit vorhandenen APIs

Wenn Sie nicht über das erforderliche SDK verfügen und externe APIs in Ihrem Code aufrufen müssen, können Sie den Befehl Teams: Herstellen einer Verbindung mit einer API in microsoft Visual Studio Code (VS Code) Teams Toolkit-Erweiterung oder den Befehl teamsfx add api-connection in TeamsFx CLI verwenden, um Code zum Aufrufen von Ziel-APIs zu bootstrapieren. Weitere Informationen finden Sie unter Konfigurieren der API-Verbindung.

FAQ

Wie kann ich meinen Befehl und meine Antwort auf Supportbenachrichtigungen erweitern?

Wechseln Sie zu , bot\src\internal\initialize.ts(js) und aktualisieren Sie Ihre conversationBot Initialisierung, um das Benachrichtigungsfeature zu aktivieren.
Informationen zum Anpassen des Sendens der Benachrichtigung finden Sie unter Senden von Benachrichtigungen an das Botinstallationsziel.
1. Wenn Sie schnell eine durch eine HTTP-Anforderung ausgelöste Beispielbenachrichtigung hinzufügen möchten, fügen Sie den folgenden Beispielcode in bot\src\index.ts(js)hinzu:
```
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({});
});
```
Deinstallieren Sie Ihre vorherige Botinstallation aus Teams, und führen Sie das lokale Debuggen aus, um Ihre Botbenachrichtigung zu testen.
Senden Sie eine Benachrichtigung an die Botinstallationsziele (Kanal, Gruppenchat oder persönlicher Chat), indem Sie eine HTTP POST-Anforderung mit der Ziel-URL https://localhost:3978/api/notificationverwenden.

Informationen zum Senden einer Benachrichtigung mit adaptiver Karte und hinzufügen weiterer Trigger finden Sie unter Benachrichtigungsbot in Teams.

Wie kann ich meinen Befehlsbot erweitern, indem ich Workflow-Bot-Aktionen für adaptive Karten hinzufüh?

Der Aktionshandler für adaptive Karten ermöglicht es der App, auf Aktionen für adaptive Karten zu reagieren, die von Benutzern ausgelöst werden, um einen sequenziellen Workflow abzuschließen. Eine adaptive Karte stellt eine oder mehrere Schaltflächen in der Karte bereit, um benutzereingaben zu fragen, z. B. das Aufrufen einiger APIs. Die adaptive Karte sendet dann eine weitere adaptive Karte in der Unterhaltung, um auf die Karte Aktion zu reagieren.

Weitere Informationen zum Hinzufügen von Aktionen für adaptive Karten zum Befehlsbot finden Sie unter Workflowbot in Teams.

Schrittweise Anleitung

Befolgen Sie die Schritt-für-Schritt-Anleitung zum Erstellen eines Teams Command-Bots .