链接展开
重要
本部分中的代码示例基于 v4.6 及更高版本的 Bot Framework SDK。 如果要查找早期版本的文档，请参阅文档的 Resources 文件夹中 的消息扩展 - v3 SDK 部分。
本文档指导你如何使用开发人员门户和手动将链接展开添加到应用清单。 通过链接展开，当具有特定域的 URL 粘贴到撰写消息区域中时，应用可以注册以接收调用活动。
invoke 包含粘贴到撰写消息区域的完整 URL，你可以使用用户可展开的卡片进行响应，从而提供其他信息或操作。 其工作原理类似于搜索命令，其中 URL 充当搜索词。 现在，无需安装应用即可将链接展开添加到 Microsoft Teams。
注意
- 链接展开结果缓存 30 分钟。
- 链接展开支持自适应卡片 1.3 及更早版本。
- 链接展开不需要消息扩展命令。 如果在应用清单中定义
messagehandlerscomposeExtensions，则无需添加commands。 有关详细信息，请参阅 撰写扩展。 - 对于移动客户端，仅对不需要身份验证的链接支持链接展开。
下图是 Teams 桌面和移动客户端中链接展开的示例：
若要详细了解链接展开，请参阅以下视频：
将链接展开添加到应用清单
要将链接展开添加到应用清单，请将新的 messageHandlers 数组添加到应用清单 JSON 的 composeExtensions 节。 可以通过开发人员门户或手动添加数组。 域列表可以包含通配符，例如 *.example.com ，与域的一个段完全匹配。 如果需要匹配 a.b.example.com，请使用 *.*.example.com。
注意
确保不直接或通过通配符添加不在你的控制范围中的域。 例如， yourapp.onmicrosoft.com 有效，但 *.onmicrosoft.com 无效。 顶级域是禁止的，例如 、 *.com*.org。
使用开发人员门户添加链接展开
从 Microsoft Teams 客户端打开 开发人员门户 ，然后选择“ 应用 ”选项卡。
注意
如果未在 Teams 客户端中添加开发人员门户应用，则必须添加该应用。
加载应用清单。
选择“应用功能”下的“消息传递扩展”，然后选择“选择现有机器人”或“创建新机器人”。
选择“保存”。
选择“预览链接”部分下的“添加域”，然后输入有效域。
选择“添加”。 下图说明了此流程:
手动添加链接展开
注意
如果通过Microsoft Entra ID添加身份验证，请使用机器人在 Teams 中展开链接。
首先，必须将数组添加到 messageHandlers 应用清单，并使消息扩展能够与链接交互。 以下示例说明了如何手动添加链接展开:
...
{
"composeExtensions": [
{
"botId": "abc123456-ab12-ab12-ab12-abcdef123456",
"messageHandlers": [
{
"type": "link",
"value": {
"domains": [
"*.trackeddomain.com"
]
}
}
]
}
]
}
...
有关完整的清单示例，请参阅 清单参考。
处理 composeExtensions/queryLink 调用
将域添加到应用清单后，必须更新 Web 服务代码来处理请求 invoke 。 使用收到的 URL 以搜索服务并创建卡片响应。 如果使用多个卡片进行响应，则仅使用第一个卡片响应。
注意
来自机器人的响应必须包含 属性 preview 。
支持以下卡片类型:
有关详细信息，请参阅 操作类型调用。
以下代码是请求的示例 invoke ：
以下是发送到机器人的 invoke 示例:
{
"type": "invoke",
"name": "composeExtension/queryLink",
"value": {
"url": "https://theurlsubmittedbyyouruser.trackeddomain.com/id/1234"
}
}
响应示例：
{
"composeExtension":
{
"type": "result",
"attachmentLayout": "list",
"attachments":
[
{
"contentType": "application/vnd.microsoft.card.adaptive",
"preview":
{
"contentType": "application/vnd.microsoft.card.adaptive",
"content": << Card Payload >>
},
"contentType": "application/vnd.microsoft.card.adaptive",
"content": << Card Payload >>
}
]
}
}
网站链接的微功能
在 Microsoft Teams 中共享内容的最常见方法是通过链接。 对于任何链接，Teams 会通过图像、标题和说明等信息将链接预览展开到自适应卡片中。
无需在 Microsoft Teams 中安装应用，即可显示链接的丰富展开预览。 以 JSON-LD 格式将 schema.org 元数据添加到网站，并使用与产品匹配的微功能模板。 Teams 使用这些模板为 Microsoft Teams 中的链接展开丰富的预览。
启用链接的丰富展开预览
如果已将 schema.org 添加到网站，可以通过将链接粘贴到 Teams 消息撰写区域中来查看链接的丰富展开预览。
如果尚未将 schema.org 添加到网站，可以按照以下步骤手动检查丰富的展开预览体验：
将 JSON-LD 格式的 schema.org 元数据添加到网站。
在网站中，检查支持的
@type属性，并在脚本标记application/ld+json下复制元数据。打开 自适应卡片设计器 并创建新文件。
在 示例数据编辑器中，粘贴网站中的 json 元数据。
检查微功能模板，并在 CARD PAYLOAD 编辑器中添加模板代码。
如果需要，请在 示例数据编辑器中将模板中的新属性添加到网站元数据。
若要预览自适应卡片展开体验，请选择“ 预览模式”。
有关详细信息，请参阅 网站链接的微功能。
链接展开的零安装
零安装链接展开有助于在用户发现或安装 Teams 中的应用之前为共享链接展开预览。 可以使用新 invoke 请求匿名展开卡片，或者在用户安装应用或进行身份验证之前为用户创建预身份验证的自适应卡片预览。
下图提供了一个顺序流来启用和使用零安装链接展开：
启用零安装链接展开
若要使应用为零安装链接展开做好准备，请执行以下步骤：
在清单架构中，将 属性
supportsAnonymizedPayloads设置为 true。设置应用以处理新
invoke请求composeExtensions/anonymousQueryLink。新
invoke请求的示例：
invoke请求有效负载的示例：{ "name":"composeExtension/anonymousQueryLink", "type":"invoke", "timestamp":"2021-12-02T08:12:21.148Z", "localTimestamp":"2021-12-02T00:12:21.148-08:00", "id":"f:43d59e15-6114-bd53-08c3-b232aa648ec1", "channelId":"msteams", "serviceUrl":"https://smba.trafficmanager.net/amer/", "from":{ "id":"redacted", "name":"redacted" }, "conversation":{ "isGroup":true, "conversationType":"groupChat", "tenantId":"redacted", "id":" redacted", "name":" redacted" }, "recipient":{ "id":"28:85fa138c-7654-4236-86eb-466160687029", "name":"test bot" }, "entities":[ { "locale":"en-US", "country":"US", "platform":"Mac", "timezone":"America/Los_Angeles", "type":"clientInfo" } ], "channelData":{ "tenant":{ "id":" redacted" }, "source":{ "name":"compose" } }, "value":{ "url":"https://test.test.com/test" }, "locale":"en-US", "localTimezone":"America/Los_Angeles" }响应
composeExtensions/anonymousQueryLink有效负载。对于非身份验证方案：必须使用 as
result和 卡 发送回响应type。 使用以下模板：{ "composeExtension": { "type": "result", "attachmentLayout": "list", "attachments": [ { "contentType": "application/vnd.microsoft.teams.card.o365connector", "content": { "sections": [ { "activityTitle": "[85069]: Create a cool app", "activityImage": "https://placekitten.com/200/200" }, { "title": "Details", "facts": [ { "name": "Assigned to:", "value": "[Larry Brown](mailto:larryb@example.com)" }, { "name": "State:", "value": "Active" } ] } ] } } ] } }对于身份验证方案：必须使用 附件中的可选预身份验证卡将响应
type与 asauth一起发回。 使用以下模板：{ "composeExtension": { "type": "auth", "attachmentLayout": "list", "attachments": [ { "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.5", "actions": [], "body": [ { "type": "TextBlock", "size": "medium", "weight": "bolder", "text": "Zero-install test app" }, { "type": "TextBlock", "text": "Link your account with this app for a full experience", "wrap": true } ] } ] } }
仅限身份验证) 的预身份验证卡 (：创建卡预览，为未安装应用的用户展开链接。 可以创建预先模板化卡或添加相关占位符字段供用户更新。 用户甚至可以在安装应用之前了解该应用。
可以创建自定义卡并添加相关字段。 用户可以根据字段填写所需的信息。 下图演示了自定义卡预览：
下图演示了默认预览卡：
注意
将链接粘贴到邮件撰写区域中后，Teams 会将链接展开到卡并提示用户登录到应用。 如果用户未登录到应用，则链接不会在聊天中以卡的形式发布。
优点和限制：
如何测试零安装链接展开
测试零安装链接展开时，不要将应用安装为个人应用。 而是将应用上传到 Teams。
注意
不要直接从 Microsoft Visual Studio 调试器运行测试应用。
若要测试零安装链接展开，请执行以下步骤：
登录到 Teams 管理中心。
在左窗格中，选择“ Teams 应用>”“管理应用”。
选择“ + 上传新应用”。
选择“上传”。
选择“ 打开 ”以上传测试应用程序的 zip 文件。
应用上传成功后，转到为组织生成的Teams>应用>。
可以通过在
composeExtensions/anonymousQueryLink应用程序中实现匿名QueryLink 请求的方法中设置断点来测试调用请求。
删除链接展开缓存
当用户在会议中共享链接时，Teams 应用会展开指向自适应卡片的链接。 链接展开结果在 Teams 中缓存 30 分钟。 可以更新应用以设置缓存策略并删除应用的缓存。 当应用的链接在 Teams 中的不同上下文中共享时，此操作可帮助你在自适应卡片中显示不同的内容。
若要删除链接展开缓存，请在 属性下suggestedActions使用 type as setcachepolicy 更新机器人。 Teams 不会使用 缓存应用链接 "type": "setCachePolicy"的结果。
属性的 suggestedActions 以下 JSON 有效负载示例：
"suggestedActions": {
"actions": [
{
"type": "setCachePolicy",
"value": "{\"type\":\"no-cache\"}"
}
]
},
分步指南
按照 分步指南 使用机器人在 Teams 中展开链接。
代码示例
| 示例名称 | 说明 | .NET | Node.js | 清单 |
|---|---|---|---|---|
| 零个安装链接展开。 | 此示例演示如何将基于搜索的消息传递扩展与配置页配合使用。 此示例还具有零安装链接展开功能。 | View | View | View |