Bot de comando no Teams

O Microsoft Teams permite automatizar tarefas simples e repetitivas em uma conversa. Você pode criar um bot de comando que pode responder a comandos simples enviados em chats com Cartões Adaptáveis. Você pode criar um modelo de bot de comando no Teams Toolkit que responde aos comandos de chat exibindo a interface do usuário usando um Cartão Adaptável. Isso permite que os usuários enviem mensagens no Teams e seu aplicativo pode fornecer uma resposta conforme necessário.

O modelo de bot de comando é criado usando o SDK do TeamsFx, que fornece um conjunto simples de funções no Microsoft Bot Framework. O bot de comando pode ser usado em diferentes cenários, como verificar status de tíquetes e recuperar informações de ajuda.

Vantagens

• Automatiza tarefas simples e repetitivas com um comando de chat.
• Simplifica o modelo de programação com o SDK do TeamsFx, criado no SDK do Bot Framework.
• Dá suporte a expressões regulares para o processamento de comandos.

Instalação do bot de comando

Um bot de comando precisa ser instalado em uma equipe ou um chat em grupo ou como aplicativo pessoal, dependendo do escopo necessário. Você precisa selecionar o destino de instalação antes de adicionar o bot ao seu aplicativo.

Para obter mais opções de instalação, consulte configurar opções de instalação padrão. Para desinstalar, consulte remover um aplicativo do Teams.

Comando e resposta

Os bots de resposta e comando TeamsFx são criados usando o SDK do Bot Framework. O SDK do Bot Framework fornece manipulador de mensagens interno para lidar com a atividade de mensagem de entrada, o que exige que você entenda o conceito do Bot Framework, como o modelo de conversa controlado por eventos. O SDK do TeamsFx fornece uma camada de abstração de resposta de comando para permitir que os usuários se concentrem em lidar com a solicitação de comando de acordo com a necessidade de negócios, sem aprender o SDK do Bot Framework.

O SDK do TeamsFx puxa o middleware do Bot Framework para lidar com a integração com os manipuladores de atividade subjacentes. Se o texto da mensagem recebida corresponder ao padrão de comando fornecido em uma TeamsFxBotCommandHandler instância, o middleware manipulará a atividade de mensagem de entrada e invocará a função correspondente handlerCommandReceived . O middleware chama context.sendActivity para enviar a resposta de comando retornada da handlerCommandReceived função para o usuário.

Personalizar a inicialização

Você precisa criar ConversationBot para responder ao comando em um chat. Você pode inicializar o com o ConversationBot adaptador ou personalizar após a inicialização.

JavaScript/TypeScript

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

C#

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

Personalizar adaptador

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

Adicionar comando e resposta

Você pode executar as seguintes etapas para adicionar comando e respostas:

1. Adicionar uma definição de comando no manifesto

Você pode editar o arquivo appPackage\manifest.json de modelo de manifesto para atualizar as title propriedades e description para doSomething o comando na matriz da commands seguinte maneira:

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

Para obter mais informações, consulte o manifesto do aplicativo.

2. Responder com um cartão adaptável

Você pode definir seu cartão no formato JSON para responder com um Cartão Adaptável. Crie um novo arquivo no seguinte caminho para JavaScript ou TypeScript e .NET da seguinte maneira:

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

Adicione o seguinte código JSON a doSomethingCommandResponse.json e DoSomethingCommandResponse:

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

Responda com texto sem formatação ou com um Cartão Adaptável. Você pode usar o cartão adaptável Designer para ajudar a projetar visualmente sua interface do usuário do cartão adaptável. Para obter mais informações sobre como enviar um cartão Adaptável com dados dinâmicos, consulte criar comando e resposta usando cartão adaptáveis.

3. Manipular o comando

A seguir estão os manipuladores de comando JavaScript, TypeScript e C# para manipular o comando:

JavaScript

O SDK do TeamsFx fornece uma classe TeamsFxBotCommandHandlerconveniente , para manipular quando um comando é disparado da mensagem de conversa do Teams. Crie um novo arquivo no caminho src/doSomethingCommandHandler.js.

Adicione o seguinte código ao doSomethingCommandHandler.js arquivo:

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

TypeScript

O SDK do TeamsFx fornece uma classe TeamsFxBotCommandHandlerconveniente , para manipular quando um comando é disparado da mensagem de conversa do Teams. Crie um novo arquivo no caminho src/doSomethingCommandHandler.ts.

Adicione o seguinte código ao doSomethingCommandHandler.ts arquivo:

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

C#

O SDK do TeamsFx .NET fornece uma interface ITeamsCommandHandler para o manipulador de comandos manipular quando um comando é disparado da mensagem de conversa do Teams. Crie um novo arquivo no caminho Commands/DoSomethingCommandHandler.cs.

Adicione o seguinte código ao 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);
        }
    }
}

Você pode personalizar o comando, incluindo chamar uma API, processar dados ou qualquer outro comando .

4. Registrar o novo comando

Cada novo comando precisa ser configurado no ConversationBot, que inicia o fluxo de conversação do modelo do bot de comando.

JavaScript/TypeScript

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

C#

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

Pressione F5 para depurar localmente ou provisionar e implantar comandos para implantar a alteração no Azure.

Personalizar o padrão de gatilho

O padrão padrão para disparar um comando é por meio de um palavra-chave definido. Você também pode coletar e processar informações adicionais recuperadas do gatilho palavra-chave. Além de palavra-chave correspondência, você também pode definir seu padrão de gatilho com expressões regulares e corresponder com message.text com mais controles.

Você pode encontrar qualquer grupo de captura no message.matches, ao usar expressões regulares. Por exemplo, se o usuário inserir reboot myMachine, message.matches[1]ele capturará myMachine. O exemplo a seguir usa a expressão regular para capturar cadeias de caracteres apó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));
  }
}

Criar comando e resposta usando o Cartão Adaptável com conteúdo dinâmico

O Cartão Adaptável fornece linguagem de modelo para permitir que os usuários renderizem conteúdo dinâmico com o mesmo layout (o modelo). Por exemplo, use o cartão adaptável para renderizar uma lista de itens, como fazer itens ou atribuir bugs que variam entre usuários diferentes.

Você pode executar as seguintes etapas para criar comando e resposta usando o Cartão Adaptável com conteúdo dinâmico:

1. Adicione o arquivo JSON do modelo de cartão adaptável em bot/adaptiveCards pasta.
2. No arquivo de código em que o manipulador commnad existe, por exemplo myCommandHandler.ts. Importe o arquivo JSON do modelo de cartão adaptável.
3. Modele seus dados de cartão.
4. Use MessageBuilder.attachAdaptiveCard no modelo com dados de cartão dinâmicos.

Se necessário, você pode adicionar novos cartões para seu aplicativo. Para obter mais informações sobre como criar diferentes tipos de Cartões Adaptáveis com uma lista ou uma tabela de conteúdo dinâmico usando ColumnSet e FactSet, consulte exemplo.

Acesso Microsoft Graph

Se você estiver respondendo a um comando que precisa acessar dados do Microsoft Graph de um usuário do Teams já conectado, poderá fazê-lo por SSO (logon único) com o token de usuário do Teams. Leia mais sobre como o Teams Toolkit pode ajudá-lo a adicionar logon único ao aplicativo teams.

Conectar-se às APIs existentes

Se você não tiver o SDK necessário e precisar invocar APIs externas em seu código, o Teams: Conectar-se a um comando de API na extensão do Kit de Ferramentas do Teams do Microsoft Visual Studio Code (VS Code) ou o comando teamsfx add api-connection na CLI do TeamsFx pode ser usado para inicializar código para chamar APIs de destino. Para obter mais informações, consulte configurar a conexão de API.

Perguntas frequentes

Como estender meu comando e resposta para notificações de suporte?

1. bot\src\internal\initialize.ts(js) Acesse e atualize sua conversationBot inicialização para habilitar o recurso de notificação.

   

2. Para personalizar o envio da notificação, consulte Enviar notificação para o destino de instalação do bot.

   1. Se você quiser adicionar rapidamente uma notificação de exemplo disparada por uma solicitação HTTP, adicione o seguinte código de exemplo em 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({});
   });
   

3. Desinstale a instalação do bot anterior do Teams e execute a depuração local para testar a notificação do bot.

4. Envie uma notificação para os destinos de instalação do bot (canal, chat em grupo ou chat pessoal) usando uma solicitação HTTP POST com URL https://localhost:3978/api/notificationde destino .

Para enviar uma notificação com Cartão Adaptável e adicionar mais gatilhos, consulte Bot de notificação no Teams.

Como estender meu bot de comando adicionando ações de cartão adaptável do bot de fluxo de trabalho?

O recurso manipulador de ação Cartão Adaptável permite que o aplicativo responda às ações do Cartão Adaptável disparadas pelos usuários para concluir um fluxo de trabalho sequencial. Um Cartão Adaptável fornece um ou mais botões no cartão para solicitar a entrada do usuário, como chamar algumas APIs. Em seguida, o Cartão Adaptável envia outro Cartão Adaptável na conversa para responder à ação cartão.

Para obter mais informações sobre como adicionar ações de Cartão Adaptável ao bot de comando, confira Bot de fluxo de trabalho no Teams.

Guias passo a passo

Siga o guia passo a passo para criar o bot de Comando do Teams.

Confira também

• Noções básicas sobre conversas
• Criar bots para o Teams
• Crie seu primeiro aplicativo de bot usando JavaScript
• Mensagens proativas
• Cartões Adaptáveis
• TeamsFx SDK
• Bot Framework SDK
• Middleware do Bot Framework
• Manipuladores de atividade de bot
• Conversas orientadas a eventos usando um manipulador de atividades