构建消息扩展

消息扩展使用户能够通过 Microsoft Teams 客户端中的按钮和表单与 Web 服务互动。 用户可以从撰写消息区域、命令框或直接从消息的外部系统中搜索或启动操作。 这些交互的结果可以作为格式丰富的卡返回到 Teams 客户端。

重要

消息扩展在 政府社区云 (GCC) 、GCC-High 和国防部 (DOD) 环境中提供。

本文档概述了消息扩展、在各种方案中执行的任务、消息扩展的功能、操作和搜索命令以及链接展开。

下图显示了可从中调用消息扩展的位置：

注意

@mentioning 不支持撰写框中的消息扩展。

桌面设备

移动设备

使用消息扩展的应用场景

应用场景	示例
你需要一个外部系统来执行操作并将结果返回给你的对话。	保留资源并允许通道知道保留的时间段。
你需要在外部系统中搜索某些内容，并与对话共享结果。	在 Azure DevOps 中搜索工作项，并将其作为自适应卡片与组共享。
你需要完成涉及外部系统中多个步骤或大量信息的复杂任务，并与对话共享结果。	在跟踪系统中根据 Teams 消息创建漏洞，将该漏洞分配给用户，并向会话线程发送包含该漏洞详细信息的卡片。

了解消息扩展的工作原理

消息扩展由托管的 Web 服务和应用清单组成，该清单指定在 Teams 客户端中调用 Web 服务的位置。 Web 服务利用 Bot Framework 的消息传送架构和安全通信协议，因此必须在 Bot Framework 中将 Web 服务注册为机器人。

注意

尽管可以手动创建 Web 服务，但我们建议使用 Bot Framework SDK 来处理协议。

在应用清单 (以前称为 Teams 应用清单) ，使用最多 10 个不同的命令定义单个消息扩展。 每个命令定义一个类型，例如操作或搜索，以及客户端中调用它的位置。 调用位置包括撰写消息区域、命令栏和消息。 调用时，Web 服务会收到一条 HTTPS 消息，其中包含包含所有相关信息的 JSON 有效负载。 使用 JSON 有效负载进行响应，以通知 Teams 客户端下一次要启用的交互。

消息扩展命令类型

消息扩展命令有两种类型：操作命令和搜索命令。 消息扩展命令类型定义可供 Web 服务使用的 UI 元素和交互流。 某些交互（如身份验证和配置）可用于这两种命令类型。

操作命令

操作命令用于向用户显示用于收集或显示信息的模式弹出窗口。 当用户提交表单时，Web 服务会通过直接将消息插入对话或撰写消息区域来做出响应。 随后，用户可以提交消息。 对于更复杂的工作流，可以将多个表单链接在一起。

操作命令是从撰写消息区域、命令框或消息触发的。 从消息调用命令时，发送到机器人的初始 JSON 有效负载包括从中调用该命令的整个消息。 下图显示了 TeamsJS v1.x) 中称为任务模块的消息扩展操作命令对话框 (：

搜索命令

搜索命令允许用户通过搜索框手动搜索外部系统的信息，或者通过将指向受监视域的链接粘贴到撰写邮件区域并将搜索结果插入邮件中来搜索信息。 在简单的搜索命令流中，初始调用消息包括用户提交的搜索字符串。 你将以一个卡片列表和卡片预览回复。 Teams 客户端为用户呈现卡片预览列表。 当用户从列表中选择一张卡片时，全尺寸的卡片会被插入到消息撰写区域。

卡片是从撰写消息区域或命令框触发的，但不是从消息触发的。 无法从消息触发它们。 下图显示了消息扩展搜索命令对话框：

注意

有关卡片的详细信息，请参阅 什么是卡片。

链接展开

注意

仅基于机器人的消息扩展支持链接展开。

将 URL 粘贴到撰写消息区域中时，将调用 Web 服务。 此功能称为链接展开。 当包含特定域的 URL 粘贴到撰写消息区域时，可以订阅接收调用。 Web 服务可以将 URL 展开到详细的卡，从而提供比标准网站预览卡更多的信息。 可以添加按钮以允许用户在不离开 Teams 客户端的情况下立即执行操作。 以下图像显示链接在消息扩展中粘贴时的链接展开功能：

构建消息扩展

若要生成消息扩展，如果还没有消息扩展，有两种方法：

• 使用 API (基于 API 的) 生成消息 扩展：可以从现有 API 轻松创建消息扩展。 此方法需要 OpenAPI 说明 (OAD) 文档。

• 使用 Bot Framework (基于机器人的) 生成消息扩展 ：如果需要一对一对话体验，可以从机器人创建新的消息扩展。

下表可帮助你选择消息扩展类型以开始使用：

基于 API 的消息扩展

• 更简单、更快速地创建和维护。
• 消息扩展使用 API。
• 机器人逻辑不需要其他代码或资源。
• 非常适合消息扩展只需与 Web 服务通信且不需要任何复杂逻辑或状态管理的方案。
• 流量已私有化，因为它们不依赖于 Azure 机器人基础结构。
• 支持搜索命令。

基于机器人的消息扩展

• 更灵活。
• 消息扩展使用 Bot Framework。
• 可以利用机器人的全部功能。
• 非常适合消息扩展需要与多个服务通信、管理复杂逻辑或用户交互或跨会话维护状态的方案。
• 支持操作命令、搜索命令和链接展开。

选择一个选项以开始生成消息扩展：

代码示例

示例名称	说明	.NET	Node.js	Python	清单
具有基于操作命令的消息扩展	此示例演示如何定义操作命令、创建对话和响应对话提交操作。	View	View	View	View
具有基于搜索命令的消息扩展	此示例演示如何生成基于搜索的消息扩展。 它会搜索 nuget 包，并在基于搜索的消息扩展中显示结果。	View	View	View	View
消息扩展操作预览	此示例演示如何使用 Bot Framework v4 在消息传递扩展中使用操作预览。	View	View	不适用	View
任务计划的消息扩展操作	此示例演示如何通过消息扩展操作命令计划任务，以及如何在计划的日期和时间获取提醒卡。	View	View	不适用	View