Bot de comandos no Teams

O Microsoft Teams permite-lhe automatizar tarefas simples e repetitivas numa conversação. Pode criar um bot de comandos que possa responder a comandos simples enviados em conversas com Cartões Ajustáveis. Pode criar um modelo de bot de comandos no Teams Toolkit que responda aos comandos de chat ao apresentar a IU com um Cartão Ajustável. Isto permite que os utilizadores enviem mensagens no Teams e a sua aplicação pode fornecer uma resposta conforme necessário.

O modelo de bot de comando é criado com o SDK do TeamsFx, que fornece um conjunto simples de funções através do Microsoft Bot Framework. O bot de comando pode ser utilizado em diferentes cenários, como verificar o estado da permissão e obter informações de ajuda.

Vantagens

• Automatiza tarefas simples e repetitivas com um comando de chat.
• Simplifica o modelo de programação com o SDK teamsFx, criado com base no SDK do Bot Framework.
• Suporta expressões regulares para processar comandos.

Instalação do bot de comandos

Um bot de comandos tem de ser instalado numa equipa, numa conversa de grupo ou como aplicação pessoal, consoante o âmbito necessário. Tem de selecionar o destino da instalação antes de adicionar o bot à sua aplicação.

Para obter mais opções de instalação, veja Configurar opções de instalação predefinidas. Para desinstalar, consulte Remover uma aplicação do Teams.

Comando e resposta

Os bots de comando e resposta do TeamsFx são criados com o SDK do Bot Framework. O SDK do Bot Framework fornece um processador de mensagens incorporado para processar a atividade de mensagens recebidas, o que requer que compreenda o conceito do Bot Framework, como o modelo de conversação condicionado por eventos. O SDK do TeamsFx fornece uma camada de abstração de resposta de comandos para permitir que os utilizadores se concentrem no processamento do pedido de comando de acordo com a necessidade empresarial, sem aprender o SDK do Bot Framework.

O SDK do TeamsFx solicita middleware do Bot Framework para processar a integração com os processadores de atividade subjacentes. Se o texto da mensagem recebida corresponder ao padrão de comando fornecido numa TeamsFxBotCommandHandler instância, o middleware processa a atividade da mensagem recebida e invoca a função correspondente handlerCommandReceived . O middleware chama context.sendActivity para enviar a resposta do comando devolvida da handlerCommandReceived função ao utilizador.

Personalizar inicialização

Tem de criar ConversationBot para responder ao comando numa conversa. 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

Pode executar os seguintes passos para adicionar comandos e respostas:

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

Pode editar o ficheiro appPackage\manifest.json de modelo de manifesto para atualizar as title propriedades e description do doSomething comando na matriz da commands seguinte forma:

"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 Ajustável

Pode definir o seu cartão no formato JSON para responder com um Cartão Ajustável. Crie um novo ficheiro no seguinte caminho para JavaScript ou TypeScript e .NET da seguinte forma:

• 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 simples ou com um Cartão Ajustável. Pode utilizar o Estruturador de Cartões Ajustável para ajudar a estruturar visualmente a sua IU de Cartão Ajustável. Para obter mais informações sobre como enviar um cartão Ajustável com dados dinâmicos, veja Build command and response using Adaptive card (Criar comando e resposta com cartão ajustável).

3. Processe o comando

Seguem-se os processadores de comandos JavaScript, TypeScript e C# para processar o comando:

JavaScript

O SDK do TeamsFx fornece uma classe TeamsFxBotCommandHandlerconveniente , para processar quando um comando é acionado a partir da mensagem de conversação do Teams. Crie um novo ficheiro no caminho src/doSomethingCommandHandler.js.

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

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 processar quando um comando é acionado a partir da mensagem de conversação do Teams. Crie um novo ficheiro no caminho src/doSomethingCommandHandler.ts.

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

/** 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 .NET do TeamsFx fornece uma interface ITeamsCommandHandler para o processador de comandos processar quando um comando é acionado a partir da mensagem de conversação do Teams. Crie um novo ficheiro 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);
        }
    }
}

Pode personalizar o comando, incluindo chamar uma API, processar dados ou qualquer outro comando .

4. Registar o novo comando

Cada novo comando tem de ser configurado no , que ConversationBotinicia o fluxo de conversação do modelo do bot de comandos.

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

Prima F5 para depurar localmente ou aprovisionar e implementar comandos para implementar a alteração no Azure.

Personalizar o padrão do acionador

O padrão predefinido para acionar um comando é através de uma palavra-chave definida. Também pode recolher e processar informações adicionais obtidas a partir da palavra-chave do acionador. Além da correspondência de palavras-chave, também pode definir o seu padrão de acionador com expressões regulares e corresponder message.text com mais controlos.

Pode encontrar qualquer grupo de captura em message.matches, ao utilizar expressões regulares. Por exemplo, se o utilizador introduzir reboot myMachine, message.matches[1]captura myMachine. O exemplo seguinte utiliza uma expressão regular para capturar cadeias de carateres 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 com o Cartão Ajustável com conteúdo dinâmico

O Cartão Ajustável fornece uma linguagem de modelo para permitir que os utilizadores compõem conteúdo dinâmico com o mesmo esquema (o modelo). Por exemplo, utilize o cartão adaptável para compor uma lista de itens, como itens a fazer ou atribuir erros que variam entre diferentes utilizadores.

Pode executar os seguintes passos para criar o comando e a resposta com o Cartão Adaptável com conteúdo dinâmico:

1. Adicione o ficheiro JSON do modelo de Cartão Ajustável na bot/adaptiveCards pasta .
2. No ficheiro de código onde existe o processador commnad, por exemplo myCommandHandler.ts. Importe o ficheiro JSON do modelo de Cartão Adaptável.
3. Modele os dados do cartão.
4. Utilize MessageBuilder.attachAdaptiveCard no modelo com dados de cartões dinâmicos.

Se necessário, pode adicionar novos cartões para a sua aplicação. Para obter mais informações sobre como criar diferentes tipos de Cartões Ajustáveis com uma lista ou um índice dinâmico ColumnSet com e FactSet, veja exemplo.

Acesso Microsoft Graph

Se estiver a responder a um comando que precisa de aceder aos dados do Microsoft Graph de um utilizador do Teams já com sessão iniciada, pode fazê-lo através do início de sessão único (SSO) com o token de utilizador do Teams. Leia mais sobre como o Teams Toolkit pode ajudá-lo a adicionar o início de sessão único à aplicação Teams.

Ligar a APIs existentes

Se não tiver o SDK necessário e precisar de invocar APIs externas no seu código, o comando Teams: Ligar a uma API na extensão do Teams Toolkit do Microsoft Visual Studio Code (VS Code) ou o comando teamsfx add api-connection na CLI do TeamsFx pode ser utilizado para iniciar o código do programa de arranque para chamar APIs de destino. Para obter mais informações, veja Configurar a ligação à API.

Perguntas frequentes

Como expandir o meu comando e resposta para suportar notificações?

1. Aceda a e atualize a bot\src\internal\initialize.ts(js) inicialização conversationBot para ativar a funcionalidade de notificação.

   

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

   1. Se quiser adicionar rapidamente uma notificação de exemplo acionada por um pedido 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 de grupo ou chat pessoal) através de um pedido HTTP POST com o URL de destino https://localhost:3978/api/notification.

Para enviar uma notificação com Cartão Ajustável e adicionar mais acionadores, veja Notification bot in Teams (Bot de notificação no Teams).

Como expandir o meu bot de comandos ao adicionar ações de Cartão Adaptável do bot de fluxo de trabalho?

A funcionalidade processador de ações cartão ajustável permite que a aplicação responda às ações de Cartão Adaptável acionadas pelos utilizadores para concluir um fluxo de trabalho sequencial. Um Cartão Ajustável fornece um ou mais botões no cartão para pedir a entrada do utilizador, como chamar algumas APIs. Em seguida, o Cartão Ajustável envia outro Cartão Ajustável na conversação para responder à ação do cartão.

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

Guias passo a passo

Siga o guia passo a passo para criar o Bot de Comandos 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
• Conversações condicionadas por eventos com um processador de atividades