响应搜索命令Respond to the search command

重要

本节中的代码示例基于 Bot 框架 SDK 的4.6 和更高版本。The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. 如果要查找早期版本的文档,请参阅文档的资源文件夹中的 "消息扩展-V3 SDK " 一节。If you're looking for documentation for earlier versions, see the Messaging Extensions - v3 SDK section in the Resources folder of the documentation.

您的 web 服务将接收composeExtension/query包含具有搜索参数的value对象的调用消息。Your web service will receive a composeExtension/query invoke message that contains a value object with the search parameters. 触发此调用:This invoke is triggered:

  • 在搜索框中输入字符时。As characters are entered into the search box.
  • 如果initialRun在应用程序清单中将设置为 true,则会在调用搜索命令后立即收到调用消息。If initialRun is set to true in your app manifest, you'll receive the invoke message as soon as the search command is invoked. 请参阅默认查询See default query.

请求参数本身位于请求的value对象中,其中包括以下属性:The request parameters itself are found in the value object in the request, which includes the following properties:

属性名称Property name 用途Purpose
commandId 用户调用的命令的名称,与应用程序清单中声明的命令之一相匹配。The name of the command invoked by the user, matching one of the commands declared in the app manifest.
parameters 参数数组。Array of parameters. 每个 parameter 对象包含参数名称,以及用户提供的参数值。Each parameter object contains the parameter name, along with the parameter value provided by the user.
queryOptions 分页参数:Pagination parameters:
skip:跳过此查询的计数skip: skip count for this query
count:要返回的元素数count: number of elements to return
protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken)
{
  //code to handle the query
}

响应用户请求Respond to user requests

当用户执行查询时,Microsoft 团队会向您的服务发出同步 HTTP 请求。When the user performs a query, Microsoft Teams issues a synchronous HTTP request to your service. 在这种情况下,您的代码有5秒的时间来提供对请求的 HTTP 响应。At that point, your code has 5 seconds to provide an HTTP response to the request. 在这段时间内,您的服务可以执行其他查找,或提供服务请求所需的任何其他业务逻辑。During this time, your service can perform additional lookup, or any other business logic needed to serve the request.

您的服务应使用与用户查询匹配的结果进行响应。Your service should respond with the results matching the user query. 响应必须指示 HTTP 状态代码200 OK ,以及具有以下正文的有效 application/json 对象:The response must indicate an HTTP status code of 200 OK and a valid application/json object with the following body:

属性名称Property name 用途Purpose
composeExtension 顶级响应信封。Top-level response envelope.
composeExtension.type 响应的类型。Type of response. 支持以下类型:The following types are supported:
result:显示搜索结果列表result: displays a list of search results
auth:要求用户进行身份验证auth: asks the user to authenticate
config:要求用户设置邮件扩展config: asks the user to set up the messaging extension
message:显示纯文本消息message: displays a plain text message
composeExtension.attachmentLayout 指定附件的布局。Specifies the layout of the attachments. 用于类型result的响应。Used for responses of type result.
目前支持以下类型:Currently the following types are supported:
list:包含缩略图、标题和文本字段的卡片对象的列表list: a list of card objects containing thumbnail, title, and text fields
grid:缩略图图像的网格grid: a grid of thumbnail images
composeExtension.attachments 有效的附件对象的数组。Array of valid attachment objects. 用于类型result的响应。Used for responses of type result.
目前支持以下类型:Currently the following types are supported:
application/vnd.microsoft.card.thumbnail
application/vnd.microsoft.card.hero
application/vnd.microsoft.teams.card.o365connector
application/vnd.microsoft.card.adaptive
composeExtension.suggestedActions 建议的操作。Suggested actions. 用于类型authconfig的响应。Used for responses of type auth or config.
composeExtension.text 要显示的消息。Message to display. 用于类型message的响应。Used for responses of type message.

响应卡片类型和预览Response card types and previews

我们支持以下附件类型:We support the following attachment types:

有关概述,请参阅什么是卡片See What are cards for an overview.

若要了解如何使用缩略图和英雄卡片类型,请参阅添加卡片和卡片操作To learn how to use the thumbnail and hero card types, see Add cards and card actions.

有关 Office 365 连接器卡的其他文档,请参阅使用 office 365 连接器卡For additional documentation regarding the Office 365 Connector card, see Using Office 365 Connector cards.

结果列表显示在 Microsoft 团队 UI 中,每个项目都有一个预览。The result list is displayed in the Microsoft Teams UI with a preview of each item. 将通过以下两种方式之一生成预览:The preview is generated in one of two ways:

  • attachment对象preview中使用属性。Using the preview property within the attachment object. preview附件只能是一个英雄或缩略图卡片。The preview attachment can only be a Hero or Thumbnail card.
  • 从附件的基本titletextimage属性中提取。Extracted from the basic title, text, and image properties of the attachment. 仅当未设置该preview属性且这些属性可用时,才使用这些属性。These are used only if the preview property is not set and these properties are available.

您可以仅通过其 preview 属性在结果列表中显示自适应卡片或 Office 365 连接器卡片的预览。You can display a preview of an Adaptive Card or Office 365 Connector card in the result list simply by its preview property. 如果结果已经是英雄或缩略图卡片,则无需执行此步骤。This is not necessary if the results are already hero or thumbnail cards. 如果使用预览附件,则它必须是英雄或缩略图卡片。If you use the preview attachment, it must be either a Hero or Thumbnail card. 如果未指定 preview 属性,卡片的预览将会失败,并且不会显示任何内容。If no preview property is specified, the preview of the card will fail and nothing will be displayed.

响应示例Response example

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
      }
  };
}

默认查询Default query

如果在清单initialRuntrue设置为,Microsoft 团队会在用户第一次打开邮件扩展时发出 "默认" 查询。If you set initialRun to true in the manifest, Microsoft Teams issues a "default" query when the user first opens the messaging extension. 您的服务可以使用一组预填充的结果对此查询做出响应。Your service can respond to this query with a set of pre-populated results. 当您的搜索命令需要进行身份验证或配置、显示最近查看的项目、收藏夹或任何其他不依赖于用户输入的信息时,这可能很有用。This can be useful when your search command requires authentication or configuration, displaying recently viewed items, favorites, or any other information that is not dependent on user input.

默认查询的结构与任何常规用户name查询相同,字段在下面的对象中设置initialRunvalue和设置true为。The default query has the same structure as any regular user query, with the name field set to initialRun and value set to true as in the object below.

{
  "type": "invoke",
  "name": "composeExtension/query",
  "value": {
    "commandId": "searchCmd",
    "parameters": [
      {
        "name": "initialRun",
        "value": "true"
      }
    ],
    "queryOptions": {
      "skip": 0,
      "count": 25
    }
  },
  ⋮
}

后续步骤Next Steps

添加身份验证和/或配置Add authentication and/or configuration

部署配置Deploy configuration

了解更多Learn more

在快速入门中试用:Try it out in a quickstart: