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 ao longo do Microsoft Bot Framework. O bot de comando pode ser utilizado em diferentes cenários, como verificar status de pedidos de suporte 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 ou numa conversa de grupo ou como uma aplicação pessoal, consoante o âmbito necessário. Durante a instalação, pode selecionar o âmbito onde pretende adicionar e utilizar o bot:

• Para abrir o bot no âmbito pessoal, selecione Abrir.

• Para abrir o bot num âmbito partilhado, selecione o canal, o chat ou a reunião necessários a partir da lista e percorra a caixa de diálogo para selecionar Ir.

  

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 a sua card 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 a Designer cartão ajustável para ajudar a estruturar visualmente a IU do Cartão Ajustável. Para obter mais informações sobre como enviar uma card Adaptável com dados dinâmicos, veja Build command and response using Adaptive card (Comando de criação e resposta com card Adaptá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 do acionador palavra-chave. Além de palavra-chave correspondência, 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 a card 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 o processador de comandos existe, por exemplo, myCommandHandler.ts. Importe o ficheiro JSON do modelo de Cartão Adaptável.
3. Modele os seus dados de card.
4. Utilize MessageBuilder.attachAdaptiveCard no modelo com dados de card 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 no Microsoft Visual Studio Code (VS Code) extensão do Teams Toolkit ou o comando teamsfx add api-connection na CLI do TeamsFx pode ser utilizado para iniciar o código 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 card 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 card.

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.

Exemplo de código

A tabela seguinte fornece um exemplo de código simples para criar uma capacidade de comando para um bot:

Nome de exemplo	Descrição	JavaScript
Extensão de Mensagem de Comando de Pesquisa do Teams	Este exemplo mostra como incorporar uma aplicação básica de Extensão de Mensagem numa aplicação do Microsoft Teams	View

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