响应搜索命令

项目
03/26/2024

重要

本部分中的代码示例基于 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.
}

示例代码参考

class TeamsMessagingExtensionsSearch extends TeamsActivityHandler {
    async handleTeamsMessagingExtensionQuery(context, query) {
  // Code to handle the query.
    }
}

以下 JSON 将缩短，以突出显示最相关的部分。

{
  "type": "invoke",
  "name": "composeExtension/query",
  "value": {
    "commandId": "searchCmd",
    "parameters": [
      {
        "name": "searchKeywords",
        "value": "Toronto"
      }
    ],
    "queryOptions": {
      "skip": 0,
      "count": 25
    }
  },
...
}

响应用户请求

当用户执行查询时，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 或缩略图卡。
从对象的基本 title、 text和 image 属性中提取 attachment 。仅当未指定属性时， preview 才使用基本属性。

对于 Hero 或 Thumbnail 卡，除了调用操作，预览卡不支持其他操作，例如按钮和点击。

若要为Microsoft 365 组发送自适应卡片或连接器卡，必须包含预览版。属性preview必须是 Hero 或 Thumbnail 卡。如果未在对象中 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
      }
  };
}

示例代码参考

class TeamsMessagingExtensionsSearchBot extends TeamsActivityHandler {
    async handleTeamsMessagingExtensionQuery(context, query) {
        const searchQuery = query.parameters[0].value;
        const response = await axios.get(`http://registry.npmjs.com/-/v1/search?${ querystring.stringify({ text: searchQuery, size: 8 }) }`);

        const attachments = [];
        response.data.objects.forEach(obj => {
            const heroCard = CardFactory.heroCard(obj.package.name);
            const preview = CardFactory.heroCard(obj.package.name);
            const attachment = { ...heroCard, preview };
            attachments.push(attachment);
        });

        return {
            composeExtension: {
                type: 'result',
                attachmentLayout: 'list',
                attachments: attachments
            }
        };
    }
}

{
  "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"
                }
              ]
            }
          ]
        },
        "preview": {
          "contentType": "application/vnd.microsoft.card.thumbnail",
          "content": {
            "title": "85069: Create a cool app",
            "images": [
              {
                "url": "https://placekitten.com/200/200"
              }
            ]
          }
        }
      },
      {
        "contentType": "application/vnd.microsoft.card.adaptive",
        "content": {
          "type": "AdaptiveCard",
          "body": [
            {
              "type": "Container",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "Microsoft Corp (NASDAQ: MSFT)",
                  "size": "medium",
                  "isSubtle": true
                },
                {
                  "type": "TextBlock",
                  "text": "September 19, 4:00 PM EST",
                  "isSubtle": true
                }
              ]
            },
            {
              "type": "Container",
              "spacing": "none",
              "items": [
                {
                  "type": "ColumnSet",
                  "columns": [
                    {
                      "type": "Column",
                      "width": "stretch",
                      "items": [
                        {
                          "type": "TextBlock",
                          "text": "75.30",
                          "size": "extraLarge"
                        },
                        {
                          "type": "TextBlock",
                          "text": "▼ 0.20 (0.32%)",
                          "size": "small",
                          "color": "attention",
                          "spacing": "none"
                        }
                      ]
                    },
                    {
                      "type": "Column",
                      "width": "auto",
                      "items": [
                        {
                          "type": "FactSet",
                          "facts": [
                            {
                              "title": "Open",
                              "value": "62.24"
                            },
                            {
                              "title": "High",
                              "value": "62.98"
                            },
                            {
                              "title": "Low",
                              "value": "62.20"
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ],
          "version": "1.0"
        },
        "preview": {
          "contentType": "application/vnd.microsoft.card.thumbnail",
          "content": {
            "title": "Microsoft Corp (NASDAQ: MSFT)",
            "text": "75.30 ▼ 0.20 (0.32%)"
          }
        }
      }
    ]
  }
}

启用和处理点击操作

示例代码参考

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

示例代码参考

async handleTeamsMessagingExtensionSelectItem(context, obj) {
        return {
            composeExtension: {
                  type: 'result',
                  attachmentLayout: 'list',
                  attachments: [CardFactory.thumbnailCard(obj.Item3)]
            }
        };
    }

{
    "name": "composeExtension/selectItem",
    "type": "invoke",
    "value": {
        "Item1": "Package_Name",
        "Item2": "Version",
        "Item3": "Package Description"
    },
    .
    .
    .
}

默认查询

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

后续步骤

向消息扩展添加第三方身份验证