使用自适应卡的通用操作

自适应卡的通用操作提供了一种为 Teams 和 Outlook 实施基于自适应卡的方案的方法。 本文档涵盖以下主题:

有关在 Teams 中使用自适应卡的通用操作的快速入门指南

  1. Action.Submit 的所有实例替换为 Action.Execute 以更新 Teams 上的现有方案。

  2. 如果要使用自动刷新模型或方案需要用户特定视图,请向自适应卡添加 refresh 子句。

    注意

    指定 属性 userIds 以标识哪些用户获取自动更新。

  3. 处理机器人中的 adaptiveCard/action 调用请求。

  4. 使用调用请求的上下文来响应为用户创建的卡片。

    注意

    每当机器人因处理 Action.Execute 而返回新卡片时,响应必须符合响应格式。

自适应卡的通用操作架构

自适应卡片架构版本 1.5 中引入了自适应卡片的通用操作。 若要有效地使用自适应卡片, version 自适应卡片的 属性必须设置为 1.5。

注意

version 属性设置为 1.5 会使自适应卡片与平台或应用程序的旧客户端(如 Outlook 和 Teams)不兼容,因为它们不支持自适应卡片的通用操作。

如果将卡版本设置为小于 1.5,并使用属性 和 refreshAction.Execute,则会发生以下情况:

Client 行为
Teams 卡片停止工作。 卡片不会刷新,也不会 Action.Execute 呈现,具体取决于 Teams 客户端的版本。 为确保在 Teams 中实现最大兼容性,请在 fallback 属性中使用 Action.Submit 定义 Action.Execute

有关如何支持旧客户端的详细信息,请参阅向后兼容性

Action.Execute

创作自适应卡片时,请将 Action.SubmitAction.Http 替换为 Action.ExecuteAction.Execute 的架构与 Action.Submit 类似。

有关详细信息,请参阅 Action.Execute 架构和属性

现在,可以使用刷新模型允许自适应卡自动更新。

刷新模型

若要自动刷新自适应卡,请定义其 refresh 属性,该属性会嵌入类型为 Action.Execute 的操作和 userIds 数组。

有关详细信息,请参阅刷新架构和属性

刷新中的用户 ID

以下是刷新中 UserIds 的功能:

  • UserIds 是一组用户 MRI,它是自适应卡中 refresh 属性的一部分。

  • userIds如果在卡的 refresh 节中将列表属性指定为 userIds: [] ,则不会自动刷新卡。 相反,在 Teams Web 客户端或桌面的三点菜单中以及 Teams 移动版(即 Android 或 iOS)的长按上下文菜单中向用户显示“刷新卡”选项,以手动刷新卡。 或者,如果方案涉及 <Teams 群组聊天或频道中的 =60 个成员,则可以选择完全跳过userIds刷新属性。 如果组或频道有 <=60 个用户,Teams 客户端会自动为所有用户调用刷新调用。

  • 添加 UserIds 属性是因为 Teams 中的频道可以包含大量成员。 如果所有成员同时查看频道,则无条件的自动刷新会导致对机器人进行多次并发调用。 必须始终包含 userIds 属性,以确定哪些用户必须获得自动刷新,最多 60 (六十)个用户 MRI

  • 可以提取 Teams 对话成员的用户 MRI。 有关如何在自适应卡的刷新部分中添加 userIds 列表的详细信息,请参阅提取名单或用户个人资料

可以使用以下示例获取个人聊天、群组聊天或频道的用户 MRI:

  1. 使用 TurnContext

    userMRI= turnContext.Activity.From.Id

  2. 使用 GetMemberAsync 方法

    var member = await TeamsInfo.GetMemberAsync(turnContext, turnContext.Activity.From.Id, cancellationToken);var userMRI = member.Id;

  • 示例 Teams 用户 MRI 为 29:1bSnHZ7Js2STWrgk6ScEErLk1Lp2zQuD5H2qQ960rtvstKp8tKLl-3r8b6DoW0QxZimuTxk_kupZ1DBMpvIQQUAZL-PNj0EORDvRZXy8kvWk

注意

在 Outlook 中忽略 userIds 属性,并且始终自动激活 refresh 属性。 Outlook 中没有缩放问题,因为用户在不同时间查看卡片。

下一步是使用 adaptiveCard/action 调用活动来了解执行 Action.Execute 后必须发出的请求。

adaptiveCard/action 调用活动

在客户端中执行 Action.Execute 时,会对机器人进行新类型的调用活动 adaptiveCard/action

有关详细信息,请参阅典型 adaptiveCard/action 调用活动的请求格式和属性

有关详细信息,请参阅典型 adaptiveCard/action 调用活动的响应格式和属性以及支持的响应类型

接下来,可以跨不同平台向旧客户端应用向后兼容性,并使自适应卡兼容。

向后兼容性

利用自适应卡的通用操作,可以设置属性来实现与较旧版本的 Outlook 和 Teams 向后兼容。

Teams

若要确保自适应卡与旧版 Teams 向后兼容,必须包括 fallback 属性并将其值设置为 Action.Submit。 此外,机器人代码必须同时处理 Action.ExecuteAction.Submit

有关详细信息,请参阅 Teams 上的向后兼容性

代码示例

示例名称 Description .NET Node.js 清单
Teams 餐饮机器人 此示例演示使用自适应卡片接受食品订单的机器人。 View NA NA
顺序工作流自适应卡片 此示例演示了机器人中顺序工作流、用户特定视图和当前自适应卡片的实现。 View View View

另请参阅