從受 Microsoft Entra 保護的 API 傳回產品數據

已完成

在此單元中，您將瞭解如何在以搜尋為基礎的訊息延伸模塊回應中，從 API 傳回數據。

處理搜尋查詢

當使用者輸入搜尋查詢時，Bot 服務會將要求傳送至傳訊擴充功能端點。 要求包含使用者輸入的搜尋查詢。 您可以使用搜尋查詢來搜尋外部系統中的數據，這可以在搜尋結果中使用。

您可以使用 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();