创建消息扩展

  • 5 分钟

在本单元中，你将了解如何创建消息扩展。 你还将了解如何使用 Teams 工具包在 Microsoft Teams 中运行和调试消息扩展。

若要创建消息扩展，需要以下组件：

  • 使用 Bot Framework 将 Web 服务注册为机器人的 Azure 机器人资源
  • 用于处理用户与消息扩展交互的 Web 服务
  • 用于在 Microsoft Teams 中定义消息扩展功能的应用清单

配置 Azure 机器人资源

Azure 机器人资源用于将 Web 服务注册为 Bot Framework 的机器人。 创建 Azure 机器人资源需要Microsoft Entra应用注册。 应用注册提供了一种安全的方式来对机器人进行身份验证和授权。 Web 服务使用 Microsoft Entra 应用注册凭据向机器人服务进行身份验证。

以下代码片段演示如何使用 Bicep 创建 Azure 机器人资源：

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

终结点属性指定在 Web 服务上公开的消息传送终结点，机器人服务在用户与消息扩展交互时使用该终结点发送请求。 msaAppId 属性指定用于通过 Web 服务对机器人服务进行身份验证的Microsoft Entra应用注册 ID。

Azure 门户中的“机器人配置”屏幕的屏幕截图。

通道用于将机器人服务与消息传送平台（如 Microsoft Teams、Slack、Facebook Messenger 等）连接起来。

以下代码片段演示如何在 Azure 机器人资源上配置 Microsoft Teams 和 Microsoft 365 (Outlook 和 智能 Microsoft 365 Copilot 副驾驶®) 通道：

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'
  }
}

Azure 门户中的“机器人通道”屏幕的屏幕截图。

配置 Web 服务

Web 服务是包含消息扩展代码的 Web 应用。 Web 服务负责处理用户与消息扩展的交互，并使用 Bot Framework SDK 与机器人服务通信。

若要处理用户交互，可以实现：

  • 消息传送终结点
  • 机器人适配器
  • 机器人活动处理程序

消息传送终结点用于接收来自机器人服务的请求。 消息传送终结点在 Web 服务上公开，并将请求传递给机器人适配器进行处理。

以下代码片段演示如何配置消息传送终结点：

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

机器人适配器用于将机器人服务与 Web 服务连接。 机器人适配器负责处理来自机器人服务的传入请求并调用机器人活动处理程序。 Web 服务使用用于向 Bot Framework 注册 Azure 机器人资源的 Microsoft Entra 应用注册凭据向机器人服务进行身份验证。

以下代码片段演示如何在 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>();

若要处理用户搜索查询并返回搜索结果，请实现一个机器人活动处理程序，该处理程序继承自 Bot Framework SDK 提供的 TeamsActivityHandler 类，并重写 OnTeamsMessagingExtensionQueryAsync 方法。

以下代码片段演示如何在 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()
                        }
                ]
            }
        };
    }
}

配置搜索命令

应用清单是定义应用的元数据和配置的 JSON 文件。 它定义应用提供的功能，例如消息扩展。 应用清单包含在应用包中。 应用包是上传到 Microsoft Teams 以安装应用的 ZIP 文件。

以下代码片段演示如何在应用清单中定义搜索命令：

"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"
          }
        ]
      }
    ]
  }
]

命令可以包含一个或多个参数。 参数是在用户界面中显示的字段。 在此示例中，命令具有名为 ProductName 的单个参数。 参数是一个文本字段，用户用他们正在搜索的产品名称填充该字段。

Microsoft Teams 中基于搜索的邮件扩展返回的搜索结果的屏幕截图。

Visual Studio 的Teams工具包

适用于 Visual Studio 的 Teams 工具包是一个扩展，提供用于创建、调试和部署Microsoft Teams 应用的工具。 Teams 工具包与 Visual Studio 集成以简化开发过程，并提供用于生成Microsoft Teams 应用的无缝体验。

Teams 工具包为包含两个项目（一个 Web 服务项目和一个 Teams 应用项目）的解决方案搭建基架。 Web 服务项目包含消息扩展代码，应用项目包含应用清单和在 Microsoft Teams 中运行应用所需的其他资源。

Visual Studio 中解决方案的屏幕截图，其中包含 Web 服务项目和使用 Teams 工具包创建的 Teams 应用项目。

Teams 工具包与 Visual Studio 中的开发隧道功能集成，以启用机器人服务与本地运行的 Web 服务之间的通信。 开发隧道在计算机之外公开 Web 服务，以允许机器人服务访问它。

显示机器人服务和 Web 服务之间的开发隧道的关系图。