Crie uma extensão de mensagem
Nesta unidade, irá aprender a criar uma extensão de mensagem. Também irá aprender a executar e depurar a extensão de mensagens no Microsoft Teams com o Teams Toolkit.
Para criar uma extensão de mensagem, precisa dos seguintes componentes:
- Recurso do Bot do Azure para registar o seu serviço Web como um bot com o Bot Framework
- Serviço Web para processar interações do utilizador com a extensão de mensagem
- Manifesto de aplicação para definir as capacidades de extensão de mensagens no Microsoft Teams
Configurar o recurso do Bot do Azure
O recurso do Bot do Azure é utilizado para registar o seu serviço Web como um bot no Bot Framework. É necessário um Microsoft Entra registo de aplicações para criar um recurso do Bot do Azure. O registo de aplicações fornece uma forma segura de autenticar e autorizar o bot. O serviço Web utiliza as credenciais de registo de aplicações Microsoft Entra para autenticar com o serviço de bot.
O fragmento de código seguinte mostra como criar um recurso do Bot do Azure com o 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
}
}
A propriedade do ponto final especifica o ponto final de mensagens exposto no serviço Web que o serviço de bot utiliza para enviar pedidos quando um utilizador interage com a extensão da mensagem. A propriedade msaAppId especifica o ID de registo da aplicação Microsoft Entra utilizado para autenticar o serviço de bot com o serviço Web.
Os canais são utilizados para ligar o serviço de bot a plataformas de mensagens como o Microsoft Teams, Slack, Facebook Messenger e muito mais.
O fragmento de código seguinte mostra como configurar os canais Microsoft Teams e Microsoft 365 (Outlook e Microsoft 365 Copilot) no recurso do Bot do 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'
}
}
Configurar o serviço Web
O serviço Web é uma aplicação Web que contém o código de extensão da mensagem. O serviço Web é responsável por lidar com as interações do utilizador com a extensão de mensagem e utiliza o SDK do Bot Framework para comunicar com o serviço de bot.
Para lidar com as interações do utilizador, implemente:
- Um ponto final de mensagens
- Um Adaptador de Bot
- Um Processador de Atividades de Bot
O ponto final de mensagens é utilizado para receber pedidos do serviço de bot. O ponto final de mensagens é exposto no serviço Web e transmite os pedidos para o Bot Adapter para processamento.
O fragmento de código seguinte mostra como configurar o ponto final de mensagens:
[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);
}
}
O Bot Adapter é utilizado para ligar o serviço de bot ao serviço Web. O Bot Adapter é responsável por processar pedidos recebidos do serviço de bot e invocar o processador de atividade do bot. O serviço Web autentica-se com o serviço de bot com as credenciais de registo de aplicações Microsoft Entra utilizadas para registar o recurso do Bot do Azure no Bot Framework.
O fragmento de código seguinte mostra como configurar o Bot Adapter no serviço 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 processar a consulta de pesquisa do utilizador e devolver resultados de pesquisa, implemente um Processador de Atividade de Bot que herda da classe TeamsActivityHandler fornecida pelo SDK do Bot Framework e substitua o método OnTeamsMessagingExtensionQueryAsync .
O fragmento de código seguinte mostra como configurar o Processador de Atividades do Bot no serviço 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 comando de pesquisa
O manifesto da aplicação é um ficheiro JSON que define os metadados e a configuração da aplicação. Define as funcionalidades que a aplicação fornece, como extensões de mensagens. O manifesto da aplicação está incluído no pacote de aplicação. O pacote de aplicações é um ficheiro ZIP que carrega para o Microsoft Teams para instalar a aplicação.
O fragmento de código seguinte mostra como um comando de pesquisa é definido no manifesto da aplicação:
"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"
}
]
}
]
}
]
Um comando pode conter um ou mais parâmetros. Um parâmetro é um campo que é apresentado na interface de utilizador. Neste exemplo, o comando tem um único parâmetro chamado ProductName. O parâmetro é um campo de texto que o utilizador preenche com o nome do produto que está a procurar.
Kit de ferramentas do Teams para Visual Studio
O Teams Toolkit for Visual Studio é uma extensão que fornece ferramentas para criar, depurar e implementar aplicações do Microsoft Teams. O Teams Toolkit integra-se com o Visual Studio para simplificar o processo de desenvolvimento e proporcionar uma experiência totalmente integrada para a criação de aplicações do Microsoft Teams.
O Teams Toolkit estrutura uma solução que contém dois projetos, um projeto de serviço Web e um projeto de aplicação teams. O projeto de serviço Web contém o código da extensão da mensagem e o projeto da aplicação contém o manifesto da aplicação e outros recursos necessários para executar a aplicação no Microsoft Teams.
O Teams Toolkit integra-se com a funcionalidade túneis Dev no Visual Studio para permitir a comunicação entre o serviço de bot e o serviço Web em execução local. Os túneis de programador expõem o serviço Web para além do computador para permitir que o serviço de bot o alcance.
