构建消息扩展

项目
09/25/2024

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

重要

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

本文概述了消息扩展、用例、功能、操作和搜索命令以及链接展开。

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

注意

@mentioning 不支持撰写框中的消息扩展。
与外部用户的群组聊天不支持消息扩展选项。

桌面设备
移动设备

屏幕截图显示消息扩展调用 Teams 桌面上的位置。

使用消息扩展的应用场景

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

了解消息扩展的工作原理

消息扩展由托管的 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 客户端的情况下立即执行操作。以下图像显示链接在消息扩展中粘贴时的链接展开功能：

展开链接

链接展开