通用操作模型概述
重要
由于服务升级,具有 全局 范围的新可操作消息提供程序的加入将暂时暂停到 2024 年 6 月 30 日。 现有的全球范围提供程序以及组织和测试范围提供程序的加入不受影响。 有关详细信息,请参阅 可操作消息的常见问题解答。
自适应卡片是与平台无关的 UI 代码段,使用轻型 JSON 格式创作,应用和服务可以共享。 自适应卡片不仅适应主机的外观,还提供丰富的交互功能。
随着自适应卡越来越受欢迎,不同的主机开始支持不同的操作模型,这导致了碎片化。 为了解决此问题,Teams、Outlook 和自适应卡片团队致力于创建跨主机兼容的新的通用机器人操作模型。 此工作导致以下结果:
- 将机器人和 Bot Framework 通用化为为 Outlook (可操作邮件) 和 Teams (机器人实现基于自适应卡片的方案)
Action.Execute
作为可操作消息) 当前使用的 (和Action.Submit
机器人) 当前使用的 (的替代Action.Http
。
架构
重要
通用操作模型在自适应卡架构版本 1.4 及更高版本中引入。 若要使用这些新功能, version
自适应卡片的 属性必须设置为 1.4 或更大,如以下示例所示。
Action.Execute
创作适用于 Outlook 的自适应卡片时,请使用 Action.Execute
来代替 Action.Http
。 下面是 JSON 有效负载中使用的Action.Execute
自适应卡示例。
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"originator":"c9b4352b-a76b-43b9-88ff-80edddaa243b",
"version": "1.4",
"body": [
{
"type": "TextBlock",
"text": "Present a form and submit it back to the originator"
},
{
"type": "Input.Text",
"id": "firstName",
"placeholder": "What is your first name?"
},
{
"type": "Input.Text",
"id": "lastName",
"placeholder": "What is your last name?"
},
{
"type": "ActionSet",
"actions": [
{
"type": "Action.Execute",
"title": "Submit",
"verb": "personalDetailsFormSubmit"
}
]
}
]
}
属性
属性 | 类型 | 必需 | 说明 |
---|---|---|---|
类型 | string |
是 | 必须是 Action.Execute 。 |
动词 | string |
否 | 一个方便的字符串,可供开发人员用来标识操作 |
data | string , object |
否 | 将结合输入字段的初始数据。 这些实质上是隐藏的属性。 |
title | string |
否 | 表示此操作的按钮或链接的标签。 |
iconUrl | uri |
否 | 要与标题一起显示在操作上的可选图标。 支持自适应卡版本 1.2+ 中的数据 URI |
style | ActionStyle |
否 | 控制操作的样式,该样式会影响操作的显示方式、说话方式等。 |
后备 | <action object> , "drop" |
否 | 描述当显示卡的客户端不支持 Action.Execute 时要执行的操作。 |
需要 | Dictionary<string> |
否 | 一系列键/值对,指示项需要具有相应最低版本的功能。 当某个功能缺失或版本不足时,将触发回退。 |
刷新机制
除了 Action.Execute
,现在还支持新的刷新机制,从而可以创建在显示时自动更新的自适应卡片。 这可确保用户始终看到最新数据。 若要允许自适应卡片在 Outlook 中自动刷新,请定义其 refresh
属性,该属性嵌入 action
类型 Action.Execute
为 的 。
属性 | 类型 | 必需 | 说明 |
---|---|---|---|
action | "Action.Execute" |
是 | 必须是 类型的 "Action.Execute" 操作实例。 |
userIds | Array<string> |
是 | 一个消息资源标识符数组, MRI (必须在 Teams 中为其启用自动刷新的用户) 。 对于 Teams,请参阅 刷新中的用户 ID 以了解详细信息。 请注意, userIds 属性在 Outlook 中将被忽略,并且 refresh 始终会自动遵循该属性。 |
示例 JSON
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"originator":"c9b4352b-a76b-43b9-88ff-80edddaa243b",
"version": "1.4",
"refresh": {
"action": {
"type": "Action.Execute",
"title": "Submit",
"verb": "personalDetailsCardRefresh"
},
"userIds": []
},
"body": [
{
"type": "TextBlock",
"text": "Present a form and submit it back to the originator"
},
{
"type": "Input.Text",
"id": "firstName",
"placeholder": "What is your first name?"
},
{
"type": "Input.Text",
"id": "lastName",
"placeholder": "What is your last name?"
},
{
"type": "ActionSet",
"actions": [
{
"type": "Action.Execute",
"title": "Submit",
"verb": "personalDetailsFormSubmit",
"fallback": "Action.Submit"
}
]
}
]
}
向后兼容性
新的Action.Execute
通用操作模型与 1.4 以下的自适应卡版本中使用的操作模型背Action.Http
道而去,该模型在自适应卡片中将操作编码为显式 HTTP 调用。 Action.Execute 模型使开发人员能够实现在 Outlook 和 Teams 中都工作的方案。 可操作的消息方案可以使用模型 Action.Http
或新 Action.Execute
模型,但不能同时使用这两者。 使用通用 Action.Execute
模型的方案必须作为机器人实现,并订阅 Outlook 可操作邮件 通道。
代码示例
浏览完文档后,即可开始尝试一些示例。