响应搜索命令
重要
本部分中的代码示例基于 v4.6 及更高版本的 Bot Framework SDK。 如果要查找早期版本的文档,请参阅文档的 Resources 文件夹中 的消息扩展 - v3 SDK 部分。
用户提交搜索命令后,Web 服务会收到一 composeExtension/query
条调用消息,其中包含具有 value
搜索参数的 对象。 调用是使用以下条件触发的:
本文档指导你如何以卡片和预览的形式响应用户请求,以及 Microsoft Teams 发出默认查询的条件。
请求参数位于 value
请求中的 对象中,其中包括以下属性:
属性名称 | 用途 |
---|---|
commandId |
用户调用的命令的名称,与应用清单中声明的命令之一相匹配。 |
parameters |
参数数组。 每个参数对象都包含参数名称以及用户提供的参数值。 |
queryOptions |
分页参数:skip :跳过此查询的计数count :要返回的元素数。 |
protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken)
{
// Code to handle the query.
}
响应用户请求
当用户执行查询时,Microsoft Teams 向服务发出同步 HTTP 请求。 此时,代码有 5
几秒钟的时间向请求提供 HTTP 响应。 在此期间,服务可以执行更多查找,或者执行处理请求所需的任何其他业务逻辑。
服务必须响应结果与用户查询匹配。 响应必须指示 的 HTTP 状态代码 200 OK
以及具有以下属性的有效应用程序或 JSON 对象:
属性名称 | 用途 |
---|---|
composeExtension |
顶级响应信封。 |
composeExtension.type |
响应类型。 支持以下类型:result :显示搜索结果列表auth :提示用户进行身份验证config :提示用户设置消息扩展message :显示纯文本消息 |
composeExtension.attachmentLayout |
指定附件的布局。 用于 类型的 result 响应。 支持以下类型: list :包含缩略图、标题和文本字段的卡片对象列表grid :缩略图图像网格 |
composeExtension.attachments |
有效附件对象的数组。 用于 类型的 result 响应。 支持以下类型: application/vnd.microsoft.card.thumbnail application/vnd.microsoft.card.hero application/vnd.microsoft.teams.card.o365connector application/vnd.microsoft.card.adaptive |
composeExtension.suggestedActions |
建议的操作。 用于 类型 auth 为 或 config 的响应。 |
composeExtension.text |
要显示的消息。 用于 类型的 message 响应。 |
配置响应
配置响应是服务器或应用程序返回的数据,用于在消息传送平台中配置和启用消息扩展。 以下代码是消息扩展配置的示例:
{
"name": "composeExtension/submitAction",
"type": "invoke",
"timestamp": "2024-03-08T14:10:47.575Z",
"localTimestamp": "2024-03-08T19:40:47.575+05:30",
"id": "f:7dfe18de-94e3-9f38-5d44-adeb31cd8243",
"channelId": "msteams",
"serviceUrl": "https://smba.trafficmanager.net/amer/",
"from": {
"id": "29:1PBlnIsEROUYzpFjULDVodMHrnpujmfhBdQAf0pcO1EkaDkhI0_Pj_ql-jZUYOGdSc3_KcqaIIjzbleraVJ2Z3g",
"name": "MOD Administrator",
"aadObjectId": "ce9def33-d7fc-444c-8728-be1f95e6b6f2"
},
"conversation": {
"isGroup": true,
"conversationType": "groupChat",
"tenantId": "4ad59956-0f88-4b88-a9d0-570b6eb4e66b",
"id": "19:1dd50ba7-e5bd-46ea-b34e-80a415148de7_ce9def33-d7fc-444c-8728-be1f95e6b6f2@unq.gbl.spaces"
},
"recipient": {
"id": "28:9a2b01fc-88c1-40e1-bf87-5079c8e35626",
"name": "PSDAzureBot"
},
"entities": [
{
"locale": "en-GB",
"country": "GB",
"platform": "Web",
"timezone": "Asia/Calcutta",
"type": "clientInfo"
}
],
"channelData": {
"tenant": {
"id": "4ad59956-0f88-4b88-a9d0-570b6eb4e66b"
},
"source": {
"name": "compose"
}
},
"value": {
"commandId": "razorView",
"commandContext": "compose",
"data": {
"Title": "Welcome to RazorView!",
"DisplayData": " Today's date is 8-3-2024, Friday"
},
"context": {
"theme": "default"
}
},
"locale": "en-GB",
"localTimezone": "Asia/Calcutta"
}
以下响应是在用户与 compose 扩展交互时出现的配置响应:
{
"composeExtension": {
"type": "config",
"suggestedActions": {
"actions": [
{
"type": "openUrl",
"value": "https://7a03-2405-201-a00c-7191-b472-ff64-112d-f806.ngrok-free.app"
}
]
}
}
}
响应卡类型和预览
注意
邮件扩展搜索结果不支持填充。
Teams 支持以下卡片类型:
若要更好地了解和概述卡片,请参阅 什么是卡片。
若要了解如何使用缩略图和主图卡类型,请参阅 添加卡片和卡片操作。
有关 Microsoft 365 组的连接器卡的详细信息,请参阅 将连接器卡用于 Microsoft 365 组。
结果列表显示在Microsoft Teams UI 中,每个项目的预览。 预览是通过以下两种方式之一生成的:
-
preview
在 对象中使用attachment
属性。 附件preview
只能是 Hero 或缩略图卡。 - 从 对象的基本
title
、text
和image
属性中提取attachment
。 仅当未指定属性时,preview
才使用基本属性。
对于“英雄”或“缩略图”卡片,除了调用操作外,预览卡不支持其他操作,例如按钮和点击。
若要发送 Microsoft 365 组的自适应卡片或连接器卡,必须包含预览版。 属性 preview
必须是 Hero 卡或缩略图卡。 如果未在 对象中 attachment
指定预览属性,则不会生成预览。
对于 Hero 和 Thumbnail 卡片,无需指定预览属性,默认情况下会生成预览。
响应示例
protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken)
{
var text = query?.Parameters?[0]?.Value as string ?? string.Empty;
// Searches NuGet for a package.
var obj = JObject.Parse(await (new HttpClient()).GetStringAsync($"https://azuresearch-usnc.nuget.org/query?q=id:{text}&prerelease=true"));
var packages = obj["data"].Select(item => (item["id"].ToString(), item["version"].ToString(), item["description"].ToString()));
// We take every row of the results and wrap them in cards wrapped in in MessagingExtensionAttachment objects.
// The Preview is optional, if it includes a Tap, that will trigger the OnTeamsMessagingExtensionSelectItemAsync event back on this bot.
var attachments = packages.Select(package => new MessagingExtensionAttachment
{
ContentType = HeroCard.ContentType,
Content = new HeroCard { Title = package.Item1 },
Preview = new HeroCard { Title = package.Item1, Tap = new CardAction { Type = "invoke", Value = package } }.ToAttachment()
})
.ToList();
// The list of MessagingExtensionAttachments must we wrapped in a MessagingExtensionResult wrapped in a MessagingExtensionResponse.
return new MessagingExtensionResponse
{
ComposeExtension = new MessagingExtensionResult
{
Type = "result",
AttachmentLayout = "list",
Attachments = attachments
}
};
}
启用和处理点击操作
protected override Task<MessagingExtensionResponse> OnTeamsMessagingExtensionSelectItemAsync(ITurnContext<IInvokeActivity> turnContext, JObject query, CancellationToken cancellationToken)
{
// The Preview card's Tap should have a Value property assigned, this will be returned to the bot in this event.
var (packageId, version, description, projectUrl, iconUrl) = query.ToObject<(string, string, string, string, string)>();
var card = new ThumbnailCard
{
Title = "Card Select Item",
Subtitle = description
};
var attachment = new MessagingExtensionAttachment
{
ContentType = ThumbnailCard.ContentType,
Content = card,
};
return Task.FromResult(new MessagingExtensionResponse
{
ComposeExtension = new MessagingExtensionResult
{
Type = "result",
AttachmentLayout = "list",
Attachments = new List<MessagingExtensionAttachment> { attachment }
}
});
}
默认查询
如果在清单中将 设置为 initialRun
true
,Microsoft Teams 会在用户首次打开消息扩展时发出 默认 查询。 服务可以使用一组预填充的结果来响应此查询。 当搜索命令需要身份验证或配置、显示最近查看的项目、收藏夹或不依赖于用户输入的任何其他信息时,这非常有用。
默认查询具有与任何常规用户查询相同的结构, name
字段设置为 initialRun
,并将 value
设置为 true
,如以下 对象所示:
{
"type": "invoke",
"name": "composeExtension/query",
"value": {
"commandId": "searchCmd",
"parameters": [
{
"name": "initialRun",
"value": "true"
}
],
"queryOptions": {
"skip": 0,
"count": 25
}
},
⋮
}
代码示例
示例名称 | Description | .NET | Node.js | 清单 |
---|---|---|---|---|
Teams 消息扩展搜索 | 此示例演示如何生成基于搜索的消息扩展。 它会搜索 nudget 包,并在基于搜索的消息扩展中显示结果。 | View | View | View |
Teams 消息扩展身份验证和配置 | 此示例显示了一个消息扩展,该扩展具有配置页、接受搜索请求并在用户登录后返回结果。 它还展示了零应用安装链接展开以及普通链接展开 | View | View | View |