适用于智能 Microsoft 365 Copilot 副驾驶®的 API 插件的自适应卡片响应模板

API 插件可以使用自适应卡片响应模板来增强智能 Microsoft 365 Copilot 副驾驶®基于从 API 收到的响应生成的响应。 自适应卡片在生成的响应中呈现引文。

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 属性设置为 $。 此值是一个 JSONPath 查询 ，指示 JSON 响应的根包含相关数据。
• 属性 static_template.body["$data"] 设置为 ${$root}，这是自适应卡片模板语言语法，用于替代任何先前的数据范围并中断回根。 严格不需要在此处设置此值，因为 data_path 已将 设置为根。
• 第 text 一个 TextBlock 的 属性使用自适应卡片模板语法 ${if(name, name, 'N/A')}。 这将引用 name API 响应中的 属性。 函数 if 指定如果 name 具有值，则使用该值，否则使用 N/A。
• 第 text 二 TextBlock 个 的 属性使用自适应卡片模板语法 ${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}。 这将引用 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，指示卡的数据位于 transactions API 响应根的 属性中。 属性 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 设置为 $.templates.debit 或 $.templates.credit。

此插件清单和 API 响应的组合将生成以下自适应卡片。

同时使用静态模板和动态模板

插件可以结合使用静态模板和动态模板。 在此方案中，静态模板充当默认模板，如果项不存在 template_selector 属性，或者如果其值未解析为 API 响应中的模板，则使用该模板。

确保跨智能 Microsoft 365 Copilot 副驾驶®中心的响应式自适应卡片

自适应卡必须设计为跨各种图面大小做出响应。 无论使用何种设备或平台，这都能确保无缝的用户体验。 为此，请确保在不同的智能 Microsoft 365 Copilot 副驾驶®中心（包括 Teams、Word和 PowerPoint）上验证自适应卡片，并通过收缩和扩展 Copilot UI 来验证各种视区宽度。 这可确保自适应卡片以最佳方式运行，并跨所有平台提供一致的体验。 应用以下最佳做法：

• 尽可能避免使用多列布局。 即使在最窄的视区宽度下，单列布局也往往呈现良好。
• 除非图像是小图标或头像，否则不要将文本和图像元素放在同一行中。
• 避免为自适应卡内的元素分配固定宽度;而是允许他们根据视区宽度调整大小。 但是，可以为小图像（如图标和头像）分配固定宽度。

相关内容

• 自适应卡片设计器 ，用于在可视化工具中设计和测试自适应卡片。
• 自适应卡片文档
• API 插件清单参考