重要
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. Thestatic_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 thedata_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
}
]
此組合會產生下列調適型卡片。
動態回應範本
如果您的 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陣列中的transactionson each 物件設定為 或$.templates.debit$.templates.credit。
此外掛程式資訊清單和 API 回應的組合會產生下列自適性卡片。
當 API 回應中的陣列為空時,防止出現空白的自適性卡片
當 API 回應中的陣列屬性是空的,且範本不包含處理該案例的條件邏輯時,自適性卡片可能會呈現空白。
下列範例顯示陣列不包含任何項目的 recommendations API 回應:
{"answer":"","recommendations":[],"followUpMessage":""}
在此情況下:
- recommendations 陣列沒有項目。
- 自適性卡片範本會嘗試逐一查看陣列,而不檢查資料是否可用。
若要防止呈現空白卡片,請將範本繫結至正確的陣列屬性,並新增條件式邏輯來控制呈現。
使用以下方法 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 來驗證各種檢視區寬度。 此程式可確保調適型卡片能以最佳狀態運作,並在所有平台上提供一致的體驗。 套用下列最佳做法:
- 盡可能避免使用多欄版面配置。 即使在最窄的檢視區寬度下,單欄版面配置也往往呈現良好。
- 除非圖像是小圖示或虛擬人偶,否則請勿將文字和影像元素放在同列。
- 避免將固定寬度指派給調適型卡片內的元素;相反地,請允許它們根據視口寬度調整大小。 不過,您可以為圖示和虛擬人偶等小影像指定固定寬度。
相關內容
- 自適性卡片設計工具 ,可在視覺化工具中設計和測試自適性卡片。
- 自適性卡片文件
- 外掛程式資訊清單參考