Bot de comandos en Teams

Microsoft Teams le permite automatizar tareas sencillas y repetitivas en una conversación. Puede crear un bot de comandos que pueda responder a comandos simples enviados en chats con tarjetas adaptables. Puede crear una plantilla de bot de comandos en el kit de herramientas de Teams que responda a los comandos de chat mediante la visualización de la interfaz de usuario mediante una tarjeta adaptable. Esto permite a los usuarios enviar mensajes en Teams y la aplicación puede proporcionar una respuesta según sea necesario.

La plantilla de bot de comandos se compila mediante el SDK de TeamsFx, que proporciona un conjunto sencillo de funciones a través de Microsoft Bot Framework. El bot de comandos se puede usar en diferentes escenarios, como comprobar el estado del vale y recuperar información de ayuda.

Ventajas

• Automatiza tareas sencillas y repetitivas con un comando de chat.
• Simplifica el modelo de programación con el SDK de TeamsFx, basado en el SDK de Bot Framework.
• Admite expresiones regulares para procesar comandos.

Instalación del bot de comandos

Un bot de comandos debe instalarse en un equipo, un chat de grupo o como aplicación personal, en función del ámbito necesario. Debe seleccionar el destino de instalación antes de agregar el bot a la aplicación.

Para obtener más opciones de instalación, consulte Configuración de opciones de instalación predeterminadas. Para la desinstalación, consulte Eliminación de una aplicación de Teams.

Comando y respuesta

Los bots de comando y respuesta de TeamsFx se compilan mediante bot framework SDK. El SDK de Bot Framework proporciona un controlador de mensajes integrado para controlar la actividad de mensajes entrantes, lo que requiere que comprenda el concepto de Bot Framework, como el modelo de conversación basado en eventos. El SDK de TeamsFx proporciona una capa de abstracción de comandos y respuestas para permitir que los usuarios se centren en controlar la solicitud de comandos según la necesidad empresarial, sin tener que aprender el SDK de Bot Framework.

El SDK de TeamsFx extrae el middleware de Bot Framework para controlar la integración con los controladores de actividad subyacentes. Si el texto del mensaje recibido coincide con el patrón de comando proporcionado en una TeamsFxBotCommandHandler instancia, el middleware controla la actividad de mensaje entrante e invoca la función correspondiente handlerCommandReceived . El middleware llama context.sendActivity a para enviar al usuario la respuesta de comando devuelta desde la handlerCommandReceived función.

Personalización de la inicialización

Debe crear ConversationBot para responder al comando en un chat. Puede inicializar con el ConversationBot adaptador o personalizarlo después de la inicialización.

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

Agregar comando y respuesta

Puede realizar los pasos siguientes para agregar comandos y respuestas:

1. Agregar una definición de comando en el manifiesto

Puede editar el archivo appPackage\manifest.json de plantilla de manifiesto para actualizar las title propiedades y description del doSomething comando de la matriz de la commands siguiente manera:

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

Para obtener más información, vea manifiesto de aplicación.

2. Responder con una tarjeta adaptable

Puede definir la tarjeta en el formato JSON para responder con una tarjeta adaptable. Cree un archivo en la siguiente ruta de acceso para JavaScript o TypeScript y .NET como se indica a continuación:

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

Agregue el siguiente código JSON a doSomethingCommandResponse.json y 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 con texto sin formato o con una tarjeta adaptable. Puede usar el Diseñador de tarjetas adaptables para ayudar a diseñar visualmente la interfaz de usuario de la tarjeta adaptable. Para obtener más información sobre cómo enviar una tarjeta adaptable con datos dinámicos, consulte Comando de compilación y respuesta mediante tarjeta adaptable.

3. Controlar el comando

A continuación se muestran los controladores de comandos de JavaScript, TypeScript y C# para controlar el comando:

JavaScript

El SDK de TeamsFx proporciona una clase TeamsFxBotCommandHandlerpráctica para controlar cuándo se desencadena un comando desde el mensaje de conversación de Teams. Cree un nuevo archivo en la ruta de acceso src/doSomethingCommandHandler.js.

Agregue el código siguiente al doSomethingCommandHandler.js archivo:

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

El SDK de TeamsFx proporciona una clase TeamsFxBotCommandHandlerpráctica para controlar cuándo se desencadena un comando desde el mensaje de conversación de Teams. Cree un nuevo archivo en la ruta de acceso src/doSomethingCommandHandler.ts.

Agregue el código siguiente al doSomethingCommandHandler.ts archivo:

/** 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#

El SDK de .NET de TeamsFx proporciona una interfaz ITeamsCommandHandler para que el controlador de comandos controle cuándo se desencadena un comando desde el mensaje de conversación de Teams. Cree un nuevo archivo en la ruta de acceso Commands/DoSomethingCommandHandler.cs.

Agregue el código siguiente a 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);
        }
    }
}

Puede personalizar el comando, incluida la llamada a una API, el procesamiento de datos o cualquier otro comando .

4. Registro del nuevo comando

Cada nuevo comando debe configurarse en , ConversationBotque inicia el flujo conversacional de la plantilla de 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);
});

Presione F5 para depurar localmente o aprovisionar e implementar comandos para implementar el cambio en Azure.

Personalización del patrón de desencadenador

El patrón predeterminado para desencadenar un comando es a través de una palabra clave definida. También puede recopilar y procesar información adicional recuperada de la palabra clave trigger. Además de la coincidencia de palabras clave, también puede definir el patrón de desencadenador con expresiones regulares y hacer coincidir message.text con con más controles.

Puede encontrar cualquier grupo de capturas en message.matches, cuando se usan expresiones regulares. Por ejemplo, si el usuario introduce reboot myMachine, message.matches[1], captura myMachine. En el ejemplo siguiente se usa la expresión regular para capturar cadenas después de 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));
  }
}

Comando de compilación y respuesta mediante tarjeta adaptable con contenido dinámico

La tarjeta adaptable proporciona el lenguaje de plantilla para permitir a los usuarios representar contenido dinámico con el mismo diseño (la plantilla). Por ejemplo, use la tarjeta adaptable para representar una lista de elementos, como elementos pendientes o asignar errores que varían entre distintos usuarios.

Puede realizar los pasos siguientes para compilar el comando y la respuesta mediante la tarjeta adaptable con contenido dinámico:

1. Agregue el archivo JSON de plantilla de tarjeta adaptable en la bot/adaptiveCards carpeta .
2. En el archivo de código donde existe el controlador commnad, por ejemplo myCommandHandler.ts, . Importe el archivo JSON de plantilla de tarjeta adaptable.
3. Modele los datos de la tarjeta.
4. Use MessageBuilder.attachAdaptiveCard en la plantilla con datos de tarjeta dinámica.

Si es necesario, puede agregar nuevas tarjetas para la aplicación. Para obtener más información sobre cómo crear diferentes tipos de tarjetas adaptables con una lista o una tabla de contenido dinámico mediante ColumnSet y FactSet, vea el ejemplo.

Obtener acceso a Microsoft Graph

Si responde a un comando que necesita acceder a los datos de Microsoft Graph de un usuario de Teams que ya ha iniciado sesión, puede hacerlo mediante el inicio de sesión único (SSO) con su token de usuario de Teams. Obtenga más información sobre cómo Teams Toolkit puede ayudarle a agregar el inicio de sesión único a la aplicación Teams.

Conexión a las API existentes

Si no tiene el SDK necesario y necesita invocar API externas en el código, la extensión Teams: Conectarse a un comando de API en Microsoft Visual Studio Code (VS Code) Teams Toolkit o el comando teamsfx add api-connection de la CLI de TeamsFx se puede usar para arrancar código para llamar a las API de destino. Para obtener más información, consulte Configuración de la conexión de API.

Preguntas más frecuentes

¿Cómo ampliar mi comando y respuesta para admitir notificaciones?

1. Vaya a y actualice conversationBot la bot\src\internal\initialize.ts(js) inicialización para habilitar la característica de notificación.

   

2. Para personalizar el envío de la notificación, consulte Envío de notificación al destino de instalación del bot.

   1. Si desea agregar rápidamente una notificación de ejemplo desencadenada por una solicitud HTTP, agregue el código de ejemplo siguiente en 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 la instalación del bot anterior de Teams y ejecute la depuración local para probar la notificación del bot.

4. Envíe una notificación a los destinos de instalación del bot (canal, chat en grupo o chat personal) mediante una solicitud HTTP POST con la dirección URL https://localhost:3978/api/notificationde destino .

Para enviar una notificación con tarjeta adaptable y agregar más desencadenadores, consulte Bot de notificación en Teams.

¿Cómo ampliar mi bot de comandos agregando acciones de tarjeta adaptable del bot de flujo de trabajo?

La característica de controlador de acciones de tarjeta adaptable permite a la aplicación responder a las acciones de tarjeta adaptable desencadenadas por los usuarios para completar un flujo de trabajo secuencial. Una tarjeta adaptable proporciona uno o varios botones en la tarjeta para solicitar la entrada del usuario, como llamar a algunas API. A continuación, la tarjeta adaptable envía otra tarjeta adaptable en la conversación para responder a la acción de la tarjeta.

Para obtener más información sobre cómo agregar acciones de tarjeta adaptable al bot de comandos, consulte Bot de flujo de trabajo en Teams.

Guía paso a paso

Siga la guía paso a paso para compilar el bot de comandos de Teams.

Vea también

• Conceptos básicos de la conversación
• Crear bots para Teams
• Cree su primera aplicación de bot con JavaScript
• Mensajes proactivos
• Tarjetas adaptables
• TeamsFx SDK
• Bot Framework SDK
• Middleware de Bot Framework
• Controladores de actividad de bots
• Conversaciones controladas por eventos mediante un controlador de actividad