卡片操作
Microsoft Teams 中机器人和消息扩展使用的卡片支持以下活动 CardAction
类型:
注意
当CardAction
从连接器使用时,Microsoft 365 组的连接器卡的操作与 potentialActions
不同。
类型 | Action |
---|---|
openUrl |
在默认浏览器中打开 URL。 |
messageBack |
从选择按钮或点击卡片的用户向机器人发送消息和有效负载。 向聊天流发送单独的消息。 |
imBack |
从选择按钮或点击卡片的用户向机器人发送消息。 从用户发送到机器人的这一消息对所有对话参与者可见。 |
invoke |
从选择按钮或点击卡片的用户向机器人发送消息和有效负载。 此消息不可见。 |
signin |
启动 OAuth 流,允许机器人连接安全服务。 |
注意
- Teams 不支持上表中未列出的
CardAction
类型。 - Teams 不支持
potentialActions
属性。 - 卡片操作不同于 Bot Framework 或 Azure 机器人服务中建议的操作。
- 如果将卡片操作用作消息扩展的一部分,则在卡片提交到频道之前,操作将不起作用。 当卡片位于“撰写消息”框中时,操作将不起作用。
操作类型 openUrl
openUrl
操作类型指定要在默认浏览器中启动的 URL。
注意
- 机器人不会收到任何已选择按钮的通知。
- URL 不支持包含数字的计算机名称。 例如,不支持 userhostname123 等主机名。
通过 openUrl
,你可以创建具有以下属性的操作:
属性 | 说明 |
---|---|
title |
显示为按钮标签。 |
value |
此字段必须包含完整且格式正确的 URL。 |
以下代码显示 JSON 中的 openUrl
操作类型的示例:
{
"type": "openUrl",
"title": "Tabs in Teams",
"value": "https://msdn.microsoft.com/microsoft-teams/tabs"
}
操作类型 messageBack
通过 messageBack
,你可以创建具有以下属性的完全自定义操作:
属性 | 说明 |
---|---|
title |
显示为按钮标签。 |
displayText |
可选。 执行操作时由用户在聊天流中使用。 此文本不会发送到机器人。 |
value |
执行操作时发送到机器人。 可以对操作的上下文进行编码,例如唯一标识符或 JSON 对象。 |
text |
执行操作时发送到机器人。 使用此属性可简化机器人开发。 代码可以检查单个顶级属性以调度机器人逻辑。 |
的灵活性 messageBack
意味着代码不能仅仅通过使用 displayText
在历史记录中留下可见的用户消息。
以下代码显示 JSON 中的 messageBack
操作类型的示例:
{
"buttons": [
{
"type": "messageBack",
"title": "My MessageBack button",
"displayText": "I clicked this button",
"text": "User just clicked the MessageBack button",
"value": "{\"property\": \"propertyValue\" }"
}
]
}
value
属性可以是序列化的 JSON 字符串或 JSON 对象。
入站消息示例
replyToId
包含卡片操作来自的消息的 ID。 如果要更新消息,请使用它。
以下代码显示入站消息的示例:
{
"text":"User just clicked the MessageBack button",
"value":{
"property":"propertyValue"
},
"type":"message",
"timestamp":"2017-06-22T22:38:47.407Z",
"id":"f:5261769396935243054",
"channelId":"msteams",
"serviceUrl":"https://smba.trafficmanager.net/amer-client-ss.msg/",
"from":{
"id":"29:102jd210jd010icsoaeclaejcoa9ue09u",
"name":"John Smith"
},
"conversation":{
"id":"19:malejcou081i20ojmlcau0@thread.skype;messageid=1498171086622"
},
"recipient":{
"id":"28:76096e45-119f-4736-859c-6dfff54395f7",
"name":"MyBot"
},
"entities":[
{
"locale": "en-US",
"country": "US",
"platform": "Windows",
"timezone": "America/Los_Angeles",
"type": "clientInfo"
}
],
"channelData":{
"channel":{
"id":"19:malejcou081i20ojmlcau0@thread.skype"
},
"team":{
"id":"19:12d021jdoijsaeoaue0u@thread.skype"
},
"tenant":{
"id":"bec8e231-67ad-484e-87f4-3e5438390a77"
}
},
"replyToId": "1575667808184",
}
操作类型 imBack
imBack
操作会触发向机器人返回消息,就像用户在正常聊天消息中键入一样。 频道中的用户和所有其他用户都可以看到按钮响应。
通过 imBack
,你可以创建具有以下属性的操作:
属性 | 说明 |
---|---|
title |
显示为按钮标签。 |
value |
此字段必须包含聊天中使用的文本字符串,因此会发送回机器人。 这是在机器人中处理以执行所需逻辑的消息文本。 |
注意
value
字段是一个简单的字符串。 不支持格式化或隐藏字符。
以下代码显示 JSON 中的 imBack
操作类型的示例:
{
"type": "imBack",
"title": "More",
"value": "Show me more"
}
操作类型 invoke
该 invoke
操作用于调用 对话 (TeamsJS v1.x) 中称为任务模块 。
invoke
操作包含三个属性,即 type
、title
和 value
。
通过 invoke
,你可以创建具有以下属性的操作:
属性 | 说明 |
---|---|
title |
显示为按钮标签。 |
value |
此属性可以包含字符串、字符串化 JSON 对象或 JSON 对象。 |
以下代码显示 JSON 中的 invoke
操作类型的示例:
{
"type": "invoke",
"title": "Option 1",
"value": {
"option": "opt1"
}
}
当用户选择该按钮时,机器人会收到包含一些其他信息的 value
对象。
注意
活动类型是 invoke
,而不是 activity.Type == "invoke"
的 message
。
传入调用消息的示例
顶级 replyToId
属性包含卡片操作来自的消息的 ID。 如果要更新消息,请使用它。
以下代码显示传入调用消息的示例:
{
"type": "invoke",
"value": {
"option": "opt1"
},
"timestamp": "2017-02-10T04:11:19.614Z",
"localTimestamp": "2017-02-09T21:11:19.614-07:00",
"id": "f:6894910862892785420",
"channelId": "msteams",
"serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/",
"from": {
"id": "29:1Eniglq0-uVL83xNB9GU6w_G5a4SZF0gcJLprZzhtEbel21G_5h-
NgoprRw45mP0AXUIZVeqrsIHSYV4ntgfVJQ",
"name": "John Doe"
},
"conversation": {
"id": "19:97b1ec61-45bf-453c-9059-6e8984e0cef4_8d88f59b-ae61-4300-bec0-caace7d28446@unq.gbl.spaces"
},
"recipient": {
"id": "28:8d88f59b-ae61-4300-bec0-caace7d28446",
"name": "MyBot"
},
"entities": [
{
"locale": "en-US",
"country": "US",
"platform": "Web",
"type": "clientInfo"
}
],
"channelData": {
"channel": {
"id": "19:dc5ba12695be4eb7bf457cad6b4709eb@thread.skype"
},
"team": {
"id": "19:712c61d0ef384e5fa681ba90ca943398@thread.skype"
},
"tenant": {
"id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
}
},
"replyToId": "1575667808184"
}
操作类型登录
signin
操作类型启动允许机器人与安全服务连接的 OAuth 流。 有关详细信息,请参阅机器人中的身份验证流。
Teams 还支持仅由自适应卡片使用的自适应卡片操作。
以下代码显示 JSON 中的 signin
操作类型的示例:
{
"type": "signin",
"title": "Click me for signin",
"value": "https://signin.com"
}
自适应卡片操作
自适应卡片支持以下六种操作类型:
- Action.OpenUrl:打开指定的 URL。
- Action.Submit:将提交操作的结果发送到机器人。
-
Action.ShowCard:调用对话并将子卡呈现到该对话中。 仅当 设置为 popup 时
ShowCardActionMode
,才需要处理此问题。 - Action.ToggleVisibility:显示或隐藏卡中的一个或多个元素。
- Action.Execute:收集输入字段,与可选数据字段合并,并将事件发送到客户端。
- Action.ResetInputs:重置自适应卡片中输入的值。
Action.Submit
Action.Submit
type 用于收集输入、合并 data
属性以及向机器人发送事件。 当用户选择提交操作时,Teams 会向机器人发送消息活动,其中包括用户在键值对中输入的所有输入字段和卡有效负载中定义的隐藏数据。
在自适应卡片架构中 data
,Action.Submit 的 属性为 或 string
object
。 提交操作对于每个数据属性的行为不同:
-
string
:字符串提交操作会自动将消息从用户发送到机器人,并在对话历史记录中可见。 -
object
:对象提交操作会自动将用户提供的不可见消息发送到包含隐藏数据的机器人。 对象提交操作在 text 属性为空时填充活动的值属性。
Action.Submit 等效于 Bot Framework 操作。 你还可以修改自适应卡片 Action.Submit
有效负载,以支持在 Action.Submit
的 data
对象中使用 msteams
属性的现有 Bot Framework 操作。 在 下data
定义 msteams
属性时,Teams 客户端定义 的行为Action.Submit
。
msteams
如果未在架构中定义 属性,Action.Submit
则其工作方式类似于常规 Bot Framework 调用操作,其中;提交操作触发对机器人的调用,机器人使用输入字段中定义的所有输入值接收有效负载。
注意
- 机器人不会接收用户输入,除非用户通过按钮(例如 “保存” 或“ 提交”)在自适应卡片中提交其操作。 例如,机器人不会将用户操作(例如从多个选项中选择一个选项或填写表单中的字段)视为输入,除非用户提交这些操作。
- 使用 Bot Framework 操作添加到
msteams
数据不适用于自适应卡片对话框。 - Teams 不支持主要或破坏性
ActionStyle
。 - 应用有 5 秒的时间响应调用消息。
示例
下面是卡有效负载的示例Action.Submit
:
有效负载由文本输入字段 "id": "text-1"
和隐藏的数据有效负载 "hiddenKey": 123.45
组成。
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.5",
"fallbackText": "fallback text for sample 01",
"speak": "This is adaptive card sample 1",
"body": [
{
"type": "Container",
"items": [
{
"id": "text-1",
"type": "Input.Text"
}
]
}
],
"actions": [
{
"type": "Action.Submit",
"data": {
"hiddenKey": 123.45
}
}
]
}
下面是用户在输入字段中键入内容并选择“ 提交”时机器人的传入活动示例。 属性 value
在 属性中包括用户的输入, text-1
以及 属性中的 hiddenKey
隐藏数据有效负载:
{
"type": "message",
"timestamp": "2023-07-18T23:45:41.699Z",
"localTimestamp": "2023-07-18T16:45:41.699-07:00",
"id": "f:9eb18f56-2259-8fa4-7dfc-111ffff58e67",
"channelId": "msteams",
"serviceUrl": "https://smba.trafficmanager.net/amer/",
"from": {
"id": "29:1E0NZYNZFQOCUI8zM9NY_EhlCsWgNbLGTHUNdBVX2ob8SLjhltEhQMPi07Gr6MLScFeS8SrKH1WGvJSiVKThnyw",
"name": "Megan Bowen",
"aadObjectId": "97b1ec61-45bf-453c-9059-6e8984e0cef4"
},
"conversation": {
"conversationType": "personal",
"tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
"id": "a:1H-RowZ3FrIheyjTupPnoCC6JvOLB5pCWms1xwqvAJG97j61D18EuSennYZE6tyfbQrnfIN3uIcwpOx73mg10hHp_uoTMMQlXhXosIu_q7QVCaYiW6Ch3bPWAitUw4aSX"
},
"recipient": {
"id": "28:159e1c0f-15ef-4597-a8c6-44ba1fd89b78",
"name": "Mushroom"
},
"entities": [
{
"locale": "en-US",
"country": "US",
"platform": "Web",
"timezone": "America/Los_Angeles",
"type": "clientInfo"
}
],
"channelData": {
"tenant": {
"id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
},
"source": {
"name": "message"
},
"legacy": {
"replyToId": "1:1XFuAl7wF96vl6iAQk9tqus0uFrB89uujGpld-Qm-XEw"
}
},
"replyToId": "1689723936016",
"value": {
"hiddenKey": 123.45,
"text-1": "HELLO"
},
"locale": "en-US",
"localTimezone": "America/Los_Angeles"
}
操作按钮的条件启用
可以使用 conditionallyEnabled
属性禁用操作按钮,直到用户更改至少一个所需输入的值。 此属性只能与 和 Action.Execute
操作一起使用Action.Submit
。 对于有条件启用的按钮,如果 isEnabled
属性设置为 false
,则无论输入如何,都会禁用操作。
下面是属性的定义方式 conditionallyEnabled
:
属性 | 类型 | 必需 | 说明 |
---|---|---|---|
conditionallyEnabled |
Boolean | ✔️ | 控制是否仅在用户至少填充了一个必需输入时启用操作。 |
以下卡有效负载显示有条件启用的按钮:
{
"type": "AdaptiveCard",
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.5",
"body": [
{
"type": "Input.Text",
"placeholder": "Placeholder text",
"label": "Required text input",
"isRequired": true,
"id": "text"
},
{
"type": "Input.Date",
"label": "Required date input",
"isRequired": true,
"id": "date"
}
],
"actions": [
{
"type": "Action.Submit",
"title": "Submit",
"conditionallyEnabled": true
},
{
"type": "Action.Submit",
"title": "Permanently disabled button",
"isEnabled": false
}
]
}
Disabled
Enabled
表单完成反馈
可以使用自适应卡片生成表单完成反馈。 向机器人发送响应时,表单完成消息显示在自适应卡片中。 消息可以是两种类型:错误或成功:
错误:当发送到机器人的响应不成功时, 出现错误,将显示“重试” 消息。 出现此错误的原因多种多样,例如:
请求过多
同一会话上的多个并发操作
服务依赖项问题
网关超时
成功:当发送到机器人的响应成功时, 将显示“你的响应已发送到应用” 消息。
可以选择“ 关闭 ”或“切换聊天”以消除消息。
如果不想显示成功消息,请在 属性中
msTeams
feedback
将 属性hide
true
设置为 。 下面是一个示例:"content": { "type": "AdaptiveCard", "title": "Card with hidden footer messages", "version": "1.0", "actions": [ { "type": "Action.Submit", "title": "Submit", "msTeams": { "feedback": { "hide": true } } } ] }
有关机器人中的卡片和卡片的详细信息,请参阅 卡片文档。
包含 messageBack 操作的自适应卡片
若要包含 messageBack
具有自适应卡片的操作,请在 对象中包含 msteams
以下详细信息:
注意
如果需要,可以在 data
对象中包含其他隐藏属性。
属性 | 说明 |
---|---|
type |
设置为 messageBack 。 |
displayText |
可选。 执行操作时由用户在聊天流中使用。 此文本不会发送到机器人。 |
value |
执行操作时发送到机器人。 可以对操作的上下文进行编码,例如唯一标识符或 JSON 对象。 |
text |
执行操作时发送到机器人。 使用此属性可简化机器人开发。 代码可以检查单个顶级属性以调度机器人逻辑。 |
以下代码显示包含 messageBack
操作的自适应卡片的示例:
{
"type": "Action.Submit",
"title": "Click me for messageBack",
"data": {
"msteams": {
"type": "messageBack",
"displayText": "I clicked this button",
"text": "text to bots",
"value": "{\"bfKey\": \"bfVal\", \"conflictKey\": \"from value\"}"
}
}
}
包含 imBack 操作的自适应卡片
若要包含 imBack
具有自适应卡片的操作,请在 对象中包含 msteams
以下详细信息:
注意
字段 value
是不支持格式设置或隐藏字符的简单字符串。
属性 | 说明 |
---|---|
type |
设置为 imBack 。 |
value |
需要在聊天中回显的字符串。 |
以下代码显示包含 imBack
操作的自适应卡片的示例:
{
"type": "Action.Submit",
"title": "Click me for imBack",
"data": {
"msteams": {
"type": "imBack",
"value": "Text to reply in chat"
}
}
}
具有登录操作的自适应卡片
若要包含 signin
具有自适应卡片的操作,请在 对象中包含 msteams
以下详细信息:
注意
如果需要,可以在 data
对象中包含其他隐藏属性。
属性 | 说明 |
---|---|
type |
设置为 signin 。 |
value |
设置为要重定向到的 URL。 |
以下代码显示包含 signin
操作的自适应卡片的示例:
{
"type": "Action.Submit",
"title": "Click me for signin",
"data": {
"msteams": {
"type": "signin",
"value": "https://signin.com"
}
}
}
包含 invoke 操作的自适应卡片
若要包含 invoke
具有自适应卡片的操作,请在 对象中包含 msteams
以下详细信息:
注意
如果需要,可以在 data
对象中包含其他隐藏属性。
属性 | 说明 |
---|---|
type |
设置为 task/fetch 。 |
data |
设置值。 |
以下代码显示包含 invoke
操作的自适应卡片的示例:
{
"type": "Action.Submit",
"title": "submit",
"data": {
"msteams": {
"type": "task/fetch"
}
}
}
属性 | 说明 |
---|---|
type |
设置为 invoke 。 |
value |
设置要显示的值。 |
以下代码显示包含 invoke
操作和其他有效负载数据的自适应卡片的示例:
[
{
"type": "Action.Submit",
"title": "submit with object value",
"data": {
"ab": "xy",
"msteams": {
"type": "invoke",
"value": { "a": "b" }
}
}
},
{
"type": "Action.Submit",
"title": "submit with stringified json value",
"data": {
"ab": "xy",
"msteams": {
"type": "invoke",
"value": "{ \"a\": \"b\"}"
}
}
}
]
代码示例
S.No。 | 卡 | 说明 | .NET | Node.js | Python | Java | 清单 |
---|---|---|---|---|---|---|---|
1 | 自适应卡片操作 | 此示例展示了自适应卡片中支持的不同操作。 | View | View | NA | NA | View |
2 | 使用卡片 | 介绍所有卡类型,包括缩略图、音频、媒体等。在欢迎用户 + 多提示机器人的基础上,在欢迎消息中显示卡,这些按钮将路由到相应对话框。 | View | View | View | View | 不适用 |
3 | 自适应卡片 | 演示多轮次对话框如何使用卡获取名称和年龄的用户输入。 | View | View | View | View | 不适用 |
4 | 卡片格式设置 | 此示例演示有条件地启用的按钮。 | View | View | NA | NA | NA |