適用於 Microsoft 365 Copilot API 外掛程式的自適性卡片回應範本

重要

MCP 和 API 外掛程式可在 宣告式代理程式內提供動作。 它們不是獨立的可安裝外掛程式套件:只有包含的代理程式才能存取其功能和工具。 如需套件與動作資訊清單關係的相關資訊,請參閱 外掛程式和宣告式代理程式動作。

API 外掛程式可以使用調適型卡片回應範本來增強 Microsoft 365 Copilot 根據從 API 收到的回應產生的回應。 自適性卡片會在產生的回應中呈現引文。

API 外掛程式可以透過兩種方式定義自適性卡片回應範本:作為 外掛程式資訊清單中定義的靜態範本,或作為 API 回應的一部分傳回的動態範本。 外掛程式開發人員會使用 自適性卡片結構描述 搭配自 適性卡片範本語言來定義範本。

靜態回應範本

如果您的 API 總是傳回相同類型的項目,而且調適型卡片的格式不需要經常變更,則靜態回應範本是不錯的選擇。 在外掛程式資訊清單的物件屬性response_semantics中static_template定義靜態範本,如下列範例所示。

"functions": [
  {
    "name": "GetBudgets",
    "description": "Returns details including name and available funds of budgets, optionally filtered by budget name",
    "capabilities": {
      "response_semantics": {
        "data_path": "$",
        "properties": {
          "title": "$.name",
          "subtitle": "$.availableFunds"
        },
        "static_template": {
          "type": "AdaptiveCard",
          "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
          "version": "1.5",
          "body": [
            {
              "type": "Container",
              "$data": "${$root}",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "Name: ${if(name, name, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "text": "Available funds: ${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}",
                  "wrap": true
                }
              ]
            }
          ]
        }
      }
    }
  },
]
  • 將屬性設定為 response_semantics.data_path. This value is a [JSONPath query](https://www.rfc-editor.org/rfc/rfc9535) that indicates that the root of the JSON response contains the relevant data. The static_template.body[“$data”]property value is${$root}, which is Adaptive Card template language syntax to override any prior data scoping and break back to the root. Setting this value isn't strictly needed, since the data_path' 已設定為根目錄。
  • text第一個TextBlock的屬性使用自適性卡片範本語法${if(name, name, 'N/A')}。 這會 name 參照 API 回應中的屬性。 if函數會指定如果有值,請name使用該值,否則使用 N/A。
  • 第二個屬性使用 text [自適性卡片] 範本語法${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}。TextBlock 這會 availableFunds 參照 API 回應中的屬性。 函數會 formatNumber 將數字轉譯成有兩位小數的字串。

請考慮此靜態範本和下列 API 回應。

[
    {
        "name": "Fourth Coffee lobby renovation",
        "availableFunds": 12000
    }
]

此組合會產生下列調適型卡片。

在 Microsoft 365 Copilot 中呈現引文的調適型卡片

動態回應範本

如果您的 API 會傳回多種類型,動態回應範本是不錯的選擇。 使用動態範本,您可以為每個退回的項目指派回應範本。 一或多個動態範本會作為 API 回應的一部分傳回,回應中的資料項目會指出要使用的範本。

若要使用動態範本,請指出資料項目上的哪個屬性指定 API 外掛程式資訊清單中屬性中的 response_semantics.properties.template_selector 範本,如本範例所示。

{
  "name": "GetTransactions",
  "description": "Returns details of transactions identified from filters like budget name or category. Multiple filters can be used in combination to refine the list of transactions returned",
  "capabilities": {
    "response_semantics": {
      "data_path": "$.transactions",
      "properties": {
        "template_selector": "$.displayTemplate"
      }
    }
  }
}

在此範例中, data_path 屬性設 $.transactions為 ,表示卡片的資料可在 API 回應根目錄的屬性中找到 transactions 。 template_selector屬性設為 $.displayTemplate,表示陣列中transactions指定要使用範本之每個項目的屬性都是屬性displayTemplate。

屬性所指出 template_selector 的屬性包含 JSONPath 查詢,可在回應中尋找項目的範本。

請考慮此範本和下列 API 回應。

{
  "transactions": [
    {
      "budgetName": "Fourth Coffee lobby renovation",
      "amount": -2000,
      "description": "Property survey for permit application",
      "expenseCategory": "permits",
      "displayTemplate": "$.templates.debit"
    },
    {
      "budgetName": "Fourth Coffee lobby renovation",
      "amount": -7200,
      "description": "Lumber and drywall for lobby",
      "expenseCategory": "materials",
      "displayTemplate": "$.templates.debit"
    },
    {
      "budgetName": "Fourth Coffee lobby renovation",
      "amount": 5000,
      "description": "Additional funds to cover cost overruns",
      "expenseCategory": null,
      "displayTemplate": "$.templates.credit"
    }
  ],
  "templates": {
    "debit": {
      "type": "AdaptiveCard",
      "version": "1.5",
      "body": [
        {
          "type": "TextBlock",
          "size": "medium",
          "weight": "bolder",
          "color": "attention",
          "text": "Debit"
        },
        {
          "type": "FactSet",
          "facts": [
            {
              "title": "Budget",
              "value": "${budgetName}"
            },
            {
              "title": "Amount",
              "value": "${formatNumber(amount, 2)}"
            },
            {
              "title": "Category",
              "value": "${if(expenseCategory, expenseCategory, 'N/A')}"
            },
            {
              "title": "Description",
              "value": "${if(description, description, 'N/A')}"
            }
          ]
        }
      ],
      "$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
    },
    "credit": {
      "type": "AdaptiveCard",
      "version": "1.5",
      "body": [
        {
          "type": "TextBlock",
          "size": "medium",
          "weight": "bolder",
          "color": "good",
          "text": "Credit"
        },
        {
          "type": "FactSet",
          "facts": [
            {
              "title": "Budget",
              "value": "${budgetName}"
            },
            {
              "title": "Amount",
              "value": "${formatNumber(amount, 2)}"
            },
            {
              "title": "Description",
              "value": "${if(description, description, 'N/A')}"
            }
          ]
        }
      ],
      "$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
    }
  }
}
  • transactions回應中的屬性包含項目陣列。
  • templates屬性是一個物件,該物件中的每個屬性都包含一個自適性卡片範本。
  • displayTemplate陣列中的 transactions on each 物件設定為 或 $.templates.debit$.templates.credit。

此外掛程式資訊清單和 API 回應的組合會產生下列自適性卡片。

轉譯借記交易的調適型卡片。

轉譯信用卡交易的調適型卡片。

當 API 回應中的陣列為空時,防止出現空白的自適性卡片

當 API 回應中的陣列屬性是空的,且範本不包含處理該案例的條件邏輯時,自適性卡片可能會呈現空白。

下列範例顯示陣列不包含任何項目的 recommendations API 回應:

{"answer":"","recommendations":[],"followUpMessage":""}

在此情況下:

  1. recommendations 陣列沒有項目。
  2. 自適性卡片範本會嘗試逐一查看陣列,而不檢查資料是否可用。

若要防止呈現空白卡片,請將範本繫結至正確的陣列屬性,並新增條件式邏輯來控制呈現。

使用以下方法 data_path繫結至陣列:

"data_path": "$.recommendations"

僅當資料存在時才逐一查看物件:

{ "type": "ColumnSet", "$data": "${$root}", "$when": "${title != null && title != ''}" }

或者,在陣列空白時提供後援文字:

{ "type": "TextBlock", "text": "No recommendations available", "$when": "${length($root) == 0}" }

秘訣

一律驗證 data_path 並包含 $when 空陣列的條件,以防止空白的自適性卡片。

搭配使用靜態和動態範本

外掛程式可以結合靜態和動態範本的使用。 在此案例中,靜態範本會做為預設範本,如果項目不存在 template_selector 屬性,或其值未解析為 API 回應中的範本。

將網域新增至您的應用程式資訊清單

將自適性卡片使用的任何網域新增至應用程式資訊清單的 validDomains 區段。

  • 當您使用 Action.OpenUrl時,請務必在屬性中 validDomains 包含目標 URL 的網域。 如果網域未列出,Teams 會顯示訊息 URL 可能會導致不受信任的內容。
  • 您的 API 外掛程式或宣告式代理程式在調適型卡片回應中傳回的影像 URL 必須在屬性中 validDomains 列出其網域。 如果網域未列出,Microsoft 365 Copilot 不會轉譯影像。

確保跨 Microsoft 365 Copilot 中心的回應式調適型卡片

自適性卡片必須設計為可在各種介面大小上回應。 這種設計確保了無縫的用戶體驗,無論使用何種設備或平台。 若要達成此目標,請驗證不同 Microsoft 365 Copilot 中樞上的調適型卡片,包括 Teams、Word 和 PowerPoint。 此外,請透過收縮和展開 Copilot UI 來驗證各種檢視區寬度。 此程式可確保調適型卡片能以最佳狀態運作,並在所有平台上提供一致的體驗。 套用下列最佳做法:

  • 盡可能避免使用多欄版面配置。 即使在最窄的檢視區寬度下,單欄版面配置也往往呈現良好。
  • 除非圖像是小圖示或虛擬人偶,否則請勿將文字和影像元素放在同列。
  • 避免將固定寬度指派給調適型卡片內的元素;相反地,請允許它們根據視口寬度調整大小。 不過,您可以為圖示和虛擬人偶等小影像指定固定寬度。