响应搜索命令

重要

本部分中的代码示例基于 v4.6 及更高版本的 Bot Framework SDK。 如果要查找早期版本的文档,请参阅文档的 Resources 文件夹中 的消息扩展 - v3 SDK 部分。

用户提交搜索命令后,Web 服务会收到一 composeExtension/query 条调用消息,其中包含具有 value 搜索参数的 对象。 调用是使用以下条件触发的:

  • 在搜索框中输入字符时。
  • initialRun应用清单 中设置为 true,一旦调用搜索命令,就会立即收到调用消息。 有关详细信息,请参阅 默认查询

本文档指导你如何以卡片和预览的形式响应用户请求,以及 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&#x27;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 或缩略图卡。
  • 从 对象的基本 titletextimage 属性中提取 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 }
        }
    });
}

默认查询

如果在清单中将 设置为 initialRuntrue ,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

后续步骤

另请参阅