Crear una extensión de mensajería
En esta unidad, aprenderá a crear una extensión de mensaje. También aprenderá a ejecutar y depurar la extensión de mensaje en Microsoft Teams mediante el kit de herramientas de Teams.
Para crear una extensión de mensaje, necesita los siguientes componentes:
- Recurso de Bot de Azure para registrar el servicio web como bot con Bot Framework
- Servicio web para controlar las interacciones del usuario con la extensión de mensaje
- Manifiesto de aplicación para definir las funcionalidades de extensión de mensaje en Microsoft Teams
Configuración del recurso de Bot de Azure
El recurso bot de Azure se usa para registrar el servicio web como bot con Bot Framework. Se requiere un registro de aplicación Microsoft Entra para crear un recurso de Bot de Azure. El registro de aplicaciones proporciona una manera segura de autenticar y autorizar el bot. El servicio web usa las credenciales de registro de aplicaciones Microsoft Entra para autenticarse con el servicio de bot.
En el siguiente fragmento de código se muestra cómo crear un recurso de Bot de Azure mediante Bicep:
resource botService 'Microsoft.BotService/botServices@2021-03-01' = {
kind: 'azurebot'
location: 'global'
name: 'botService'
properties: {
displayName: 'Bot Service'
endpoint: 'https://webservice.contoso.com/api/messages'
msaAppId: '00000000-0000-0000-0000-000000000000'
}
sku: {
name: botServiceSku
}
}
La propiedad endpoint especifica el punto de conexión de mensajería expuesto en el servicio web que el servicio de bot usa para enviar solicitudes cuando un usuario interactúa con la extensión de mensaje. La propiedad msaAppId especifica el identificador de registro de aplicación Microsoft Entra que se usa para autenticar el servicio de bot con el servicio web.
Los canales se usan para conectar el servicio de bot con plataformas de mensajería como Microsoft Teams, Slack, Facebook Messenger, etc.
En el siguiente fragmento de código se muestra cómo configurar los canales de Microsoft Teams y Microsoft 365 (Outlook y Microsoft 365 Copilot) en el recurso bot de Azure:
resource botServiceMsTeamsChannel 'Microsoft.BotService/botServices/channels@2021-03-01' = {
parent: botService
location: 'global'
name: 'MsTeamsChannel'
properties: {
channelName: 'MsTeamsChannel'
}
}
resource botServiceM365ExtensionsChannel 'Microsoft.BotService/botServices/channels@2022-06-15-preview' = {
parent: botService
location: 'global'
name: 'M365Extensions'
properties: {
channelName: 'M365Extensions'
}
}
Configuración del servicio web
El servicio web es una aplicación web que contiene el código de extensión de mensaje. El servicio web es responsable de controlar las interacciones del usuario con la extensión de mensaje y usa el SDK de Bot Framework para comunicarse con el servicio de bot.
Para controlar las interacciones del usuario, implemente:
- Un punto de conexión de mensajería
- Un adaptador de bot
- Un controlador de actividad de bot
El punto de conexión de mensajería se usa para recibir solicitudes del servicio de bot. El punto de conexión de mensajería se expone en el servicio web y pasa las solicitudes al adaptador de bot para su procesamiento.
El siguiente fragmento de código muestra cómo configurar el punto de conexión de mensajería:
[Route("api/messages")]
[ApiController]
public class BotController : ControllerBase
{
private readonly IBotFrameworkHttpAdapter Adapter;
private readonly IBot Bot;
public BotController(IBotFrameworkHttpAdapter adapter, IBot bot)
{
Adapter = adapter;
Bot = bot;
}
[HttpPost, HttpGet]
public async Task PostAsync()
{
await Adapter.ProcessAsync(Request, Response, Bot);
}
}
El adaptador de bot se usa para conectar el servicio de bot con el servicio web. El adaptador de bot es responsable de procesar las solicitudes entrantes del servicio de bot e invocar el controlador de actividad del bot. El servicio web se autentica con el servicio bot mediante las credenciales de registro de aplicaciones Microsoft Entra que se usan para registrar el recurso bot de Azure con Bot Framework.
El siguiente fragmento de código muestra cómo configurar el adaptador de bot en el servicio web:
// Create the Bot Framework Authentication to be used with the Bot Adapter.
var config = builder.Configuration.Get<ConfigOptions>();
builder.Configuration["MicrosoftAppType"] = "MultiTenant";
builder.Configuration["MicrosoftAppId"] = config.BOT_ID;
builder.Configuration["MicrosoftAppPassword"] = config.BOT_PASSWORD;
builder.Services.AddSingleton<BotFrameworkAuthentication, ConfigurationBotFrameworkAuthentication>();
// Create the Bot Framework Adapter with error handling enabled.
builder.Services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>();
// Create the bot as a transient. In this case the ASP Controller is expecting an IBot.
builder.Services.AddTransient<IBot, SearchApp>();
Para procesar la consulta de búsqueda del usuario y devolver los resultados de la búsqueda, implemente un controlador de actividad de bot que herede de la clase TeamsActivityHandler proporcionada por el SDK de Bot Framework e invalide el método OnTeamsMessagingExtensionQueryAsync .
El siguiente fragmento de código muestra cómo configurar el controlador de actividad del bot en el servicio web:
public class SearchApp : TeamsActivityHandler
{
protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken)
{
var text = query?.Parameters?[0]?.Value as string ?? string.Empty;
var card = await File.ReadAllTextAsync(Path.Combine(".", "Resources", "card.json"), cancellationToken);
var template = new AdaptiveCards.Templating.AdaptiveCardTemplate(card);
return new MessagingExtensionResponse
{
ComposeExtension = new MessagingExtensionResult
{
Type = "result",
AttachmentLayout = "list",
Attachments = [
new MessagingExtensionAttachment
{
ContentType = AdaptiveCard.ContentType,
Content = JsonConvert.DeserializeObject(template.Expand(new { text })),
Preview = new ThumbnailCard { Title = text }.ToAttachment()
}
]
}
};
}
}
Configurar el comando de búsqueda
El manifiesto de aplicación es un archivo JSON que define los metadatos y la configuración de la aplicación. Define las funcionalidades que proporciona la aplicación, como las extensiones de mensaje. El manifiesto de la aplicación se incluye en el paquete de la aplicación. El paquete de la aplicación es un archivo ZIP que se carga en Microsoft Teams para instalar la aplicación.
El siguiente fragmento de código muestra cómo se define un comando de búsqueda en el manifiesto de la aplicación:
"composeExtensions": [
{
"botId": "4cc3ac43-d581-403d-8bbf-ff9c0fbf3fb2",
"commands": [
{
"id": "Search",
"type": "query",
"title": "Products",
"description": "Find products by name",
"initialRun": true,
"fetchTask": false,
"context": [
"commandBox",
"compose",
"message"
],
"parameters": [
{
"name": "ProductName",
"title": "Product name",
"description": "The name of the product as a keyword",
"inputType": "text"
}
]
}
]
}
]
Un comando puede contener uno o varios parámetros. Un parámetro es un campo que se muestra en la interfaz de usuario. En este ejemplo, el comando tiene un único parámetro denominado ProductName. El parámetro es un campo de texto que el usuario rellena con el nombre del producto que está buscando.
Kit de herramientas de Teams para Visual Studio
Teams Toolkit for Visual Studio es una extensión que proporciona herramientas para crear, depurar e implementar aplicaciones de Microsoft Teams. Teams Toolkit se integra con Visual Studio para simplificar el proceso de desarrollo y proporcionar una experiencia perfecta para crear aplicaciones de Microsoft Teams.
Teams Toolkit aplica scaffolding a una solución que contiene dos proyectos, un proyecto de servicio web y un proyecto de aplicación de Teams. El proyecto de servicio web contiene el código de extensión de mensaje y el proyecto de aplicación contiene el manifiesto de aplicación y otros recursos necesarios para ejecutar la aplicación en Microsoft Teams.
Teams Toolkit se integra con la característica Dev tunnels en Visual Studio para habilitar la comunicación entre el servicio de bot y el servicio web en ejecución local. Los túneles de desarrollo exponen el servicio web más allá de la máquina para permitir que el servicio de bot llegue a él.
