从Microsoft Entra受保护的 API 返回产品数据

4 分钟

在本单元中，你将了解如何在基于搜索的消息扩展响应中从 API 返回数据。

处理搜索查询

当用户输入搜索查询时，机器人服务将向消息传递扩展终结点发送请求。请求包含用户输入的搜索查询。使用搜索查询在外部系统中搜索可在搜索结果中使用的数据。

在 OnTeamsMessagingExtensionQueryAsync 方法中使用 MessagingExtensionQuery 对象的 Query 属性访问用户输入的搜索查询。 MessagingExtensionQuery 对象的 Parameters 属性包含调用消息扩展时传递给该扩展的参数。 Parameters 属性是键值对的列表，其中包含每个参数的名称和值。

自适应卡片模板

自适应卡片是一种声明性格式，用于创建与平台无关的 UI 组件，这些组件在不同平台和设备之间提供一致的用户体验。

自适应卡片模板是定义自适应卡片结构的 JSON 文件。使用自适应卡片模板可以在单独的文件中定义卡的结构，并在运行时将数据绑定到卡。

当用户选择搜索结果时，可以使用自适应卡片模板创建嵌入在邮件撰写区域中的搜索结果内容。

以下代码片段显示了自适应卡片模板的基本示例：

{
  "type": "AdaptiveCard",
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.5",
  "body": [
    {
      "type": "TextBlock",
      "text": "${name}",
      "wrap": true,
      "style": "heading"
    }
  ]
}

自适应卡片模板使用快速绑定将数据绑定到卡。使用 AdaptiveCardTemplate 对象的 Expand 方法将数据绑定到卡。 Expand 方法将模板中的快速绑定替换为对象中的数据。快速绑定包含在中 ${}。例如， ${name} 是呈现卡时替换为属性值的name快速绑定。

以下代码片段演示如何创建 AdaptiveCardTemplate 对象、将数据绑定到卡并将扩展的模板反序列化为 JSON 对象：

var cardJson = await File.ReadAllTextAsync(Path.Combine(".", "Resources", "card.json"), cancellationToken);
var template = new AdaptiveCardTemplate(cardJson);
var expandedTemplate = template.Expand({ name: "Product" });
var content = JsonConvert.DeserializeObject(expandedTemplate);

首先从文件读取自适应卡片模板并创建 AdaptiveCardTemplate 对象。然后，使用 Expand 方法将数据绑定到卡。 Expand 方法将模板中的快速绑定替换为对象中的数据。最后，将扩展的模板反序列化为 JSON 对象，该对象可在 MessagingExtensionAttachment 对象的 Content 属性中使用。

消息扩展响应

消息扩展必须始终向用户搜索查询返回响应。 MessagingExtensionResponse 对象用于向用户返回响应。向用户返回结果时，响应中包含 composeExtension 对象。 composeExtension 对象包含一个 MessagingExtensionResult 对象，该对象包含要向用户显示的结果。

以下代码片段演示如何向用户返回响应：

return new MessagingExtensionResponse
{
    ComposeExtension = new MessagingExtensionResult
    {
        Type = "result",
        AttachmentLayout = "list",
        Attachments = attachments
    }
};

MessagingExtensionResult 对象的 Attachments 属性包含 MessagingExtensionAttachment 对象的列表。

每个 MessagingExtensionAttachment 对象都表示向用户显示的搜索结果。 MessagingExtensionAttachment 对象包含以下属性：

ContentType：附件的内容类型。
内容：表示当用户选择搜索结果时嵌入到邮件撰写区域中的卡的附件内容。
预览：表示搜索结果中显示的卡的附件预览。

以下代码片段演示如何创建 MessagingExtensionAttachment 对象的列表，其中包含每个搜索结果的自适应卡片和预览卡：

var attachments = products.Select(product =>
{
    var expandedTemplate = template.Expand(product);

    return new MessagingExtensionAttachment
    {
        ContentType = AdaptiveCard.ContentType,
        Content = JsonConvert.DeserializeObject(content),
        Preview = new ThumbnailCard
        {
            Title = product.Name,
            Subtitle = product.Category,
            Images = [new() { Url = product.ImageUrl }]
        }.ToAttachment()
    };
}).ToList();

从Microsoft Entra受保护的 API 返回产品数据

处理搜索查询

自适应卡片模板

消息扩展响应

反馈