旧版可操作邮件卡参考Legacy actionable message card reference

备注

本文档介绍了可操作邮件卡格式的原始 JSON 格式。This document describes the original JSON format for the actionable message card format. 对于通过电子邮件发送的可操作邮件,这已替换为自适应卡片格式For actionable messages sent via email, this has been replaced with the Adaptive Card format. Microsoft 建议新的可操作邮件集成使用自适应卡片格式,现有集成考虑更新为自适应卡片格式。Microsoft recommends that new actionable message integrations use the Adaptive Card format, and existing integrations consider updating to Adaptive Card format. 自适应卡格式是支持 iOS 版和 Android 版 Outlook 的必要条件。The Adaptive Card format is required to support Outlook on iOS and Android. 但是,如果通过 Office 连接器发送可操作邮件或将其发送至 Microsoft Teams 连接器,则必须继续使用邮件卡片格式。However, if you are sending actionable messages via an Office connector, or to a Microsoft Teams connector, you must continue to use the message card format.

卡片旨在提供便于阅读、一目了然的信息,以便用户可以在适当的时候非常快速地解密并加以执行。因此设计出色卡片的指导准则是“内容优于部件版式”,也就是说,卡片要直奔主题并最大程度地减少使用会分散注意力的内容,例如图标或自定义颜色。Cards are meant to provide easy to read, at-a-glance information that users can very quickly decipher and act upon when appropriate. As such, the guiding principle for designing great card is "content over chrome," which means cards are straight to the point and minimize the use of anything that would be distracting such as icons or custom colors.

卡片样本Card playground

准备好进行卡片设计试验了吗?转到卡片样本,通过它你在编辑关联的 JSON 负载时可以看到卡片的外观。Ready to experiment with your card design? Head to the Card Playground which allows you to see what your card will look like as you edit the associated JSON payload.

备注

默认情况下,卡片样本将加载自适应卡片示例。The Card Playground loads Adaptive Card examples by default. 可以通过在样本中选择“选择示例”**** 下拉列表来查找邮件卡片格式示例。You can find message card format examples by selecting the Select a sample dropdown in the playground.

设计准则Design guidelines

文本格式Text formatting

卡片的所有文本字段及其分区均可使用 Markdown 设置格式。我们支持基本 Markdown。All text fields in a card and its section can be formatted using Markdown. We support basic Markdown.

重要

由于所有字段均被处理为 Markdown,因此必要时请务必将 Markdown 特殊字符(例如 *#)转义。Since all fields are processed as Markdown, be sure to escape Markdown special characters (such as * or #) if needed.

效果Effect MarkdownMarkdown
斜体Italics *Italic*
粗体Bold **Bold**
粗斜体Bold italics ***Bold Italic***
删除线Strike-through ~~Strike-through~~
链接Links [Microsoft](https://www.microsoft.com)
标题(<h1><h6>Headings (<h1> through <h6> # Heading###### Heading# Heading through ###### Heading
点符列表Bulleted lists * List item- List item* List item or - List item

提示

设置文本字段的格式时,请遵循下面这些准则。Follow these guidelines when formatting text fields.

  • 使用 Markdown 设置文本格式。Do use Markdown to format text.
  • 请勿在卡片中使用 HTML 标记。将忽略 HTML 并将其视为纯文本。Don't use HTML markup in your cards. HTML is ignored and treated as plain text.

使用分区Using sections

如果你的卡片表示单个“实体”,则你可以不必使用任何分区。话虽如此,但分区支持“活动”概念,而这往往是表示卡片数据的不错方式。If your card represents a single "entity", you may be able to get away with not using any section. That said, sections support the concept of an "activity" which is often a good way to represent data in a card.

如果你的卡片表示多个“实体”或者类似于特定新闻源的摘要,那么你肯定会想要使用多个分区,一个“实体”对应一个分区。If your card represents multiple "entities" or is, for instance, a digest for a particular news source, you will definitely want to use multiple sections, one per "entity."

提示

计划卡片布局时,请遵循下面这些准则。Follow these guidelines when planning the layout of your card.

  • 使用分区,按逻辑对数据进行分组。Do use sections to logically group data together.
  • 有时,可以使用多个分区表示单个数据逻辑组;这样则可以更加灵活地对卡片中显示的信息进行排序。例如,这样则可以在活动前显示事件列表。Sometimes, multiple sections MAY be used to represent a single logical group of data; this allows for more flexibility on ordering the information presented in the card. For example, it makes it possible to display a list of facts before an activity.
  • 包含的分区请勿超过 10 个。卡片旨在方便阅读;如果卡片中的信息过多,用户则会忽视这些信息。Don't include more than 10 sections. Cards are meant to be easy to read; if there is too much information in a card, it will be lost on the user.
  • 对于摘要式卡片,建议在卡片末尾添加“查看完整摘要”操作。For digest-like cards, consider adding a "View full digest" action at the end of the card.

卡片字段Card fields

字段Field 类型Type 描述Description
@type 字符串String 必需。必须设置为 MessageCardRequired. Must be set to MessageCard.
@context 字符串String 必需。必须设置为 https://schema.org/extensionsRequired. Must be set to https://schema.org/extensions.
correlationId UUIDUUID correlationId 属性简化了出于问题排查目的而查找日志的过程。The correlationId property simplifies the process of locating logs for troubleshooting issues. 建议在发送可操作卡片时,服务应设置并记录此属性中的唯一 UUID。We recommend that when sending an actionable card, your service should set and log a unique UUID in this property.

当用户在卡片上调用操作时,Office 365 会将 POST 请求中的 Card-Correlation-IdAction-Request-Id 头发送到服务。When the user invokes an action on the card, Office 365 sends the Card-Correlation-Id and Action-Request-Id headers in the POST request to your service. Card-Correlation-Id 的值与卡片中的 correlationId 属性值相同。Card-Correlation-Id contains the same value as the correlationId property in the card. Action-Request-Id 是 Office 365 生成的唯一 UUID,有助于查找用户执行的特定操作。Action-Request-Id is a unique UUID generated by Office 365 to help locate specific action performed by a user. 收到操作 POST 请求时,服务应同时记录这两个值。Your service should log both of these values when receiving action POST requests.
expectedActors 字符串数组Array of String 可选。Optional. 其中包含操作终结点收件人的预期电子邮件地址列表。This contains a list of expected email addresses of the recipient for the action endpoint.

用户可以拥有多个电子邮件地址,且操作终结点可能不想要持有者令牌的 sub 声明中显示的特定电子邮件地址。A user can have multiple email addresses and the action endpoint might not be expecting the particular email address presented in the sub claim of the bearer token. 例如,某个用户可能同时有 john.doe@contoso.comjohn@contoso.com 电子邮件地址,但操作终结点希望接收持有者令牌的 sub 声明中的 john@contoso.comFor example, a user could have both the john.doe@contoso.com or john@contoso.com email address, but the action endpoint expects to receive john@contoso.com in the sub claim of the bearer token. 通过将此字段设置为 ["john@contoso.com"]sub 声明将具有预期的电子邮件地址。By setting this field to ["john@contoso.com"], the sub claim will have the expected email address.
originator StringString 通过电子邮件发送时,此为必需字段;通过连接器发送时,则不适用。Required when sent via email, not applicable when sent via connector. 对于可操作电子邮件,必须设置为可操作电子邮件开发者仪表板生成的提供程序 ID。For actionable email, MUST be set to the provider ID generated by the Actionable Email Developer Dashboard.
summary 字符串String 如果卡片不包含 text 属性,则必填;否则可选。Required if the card does not contain a text property, otherwise optional. summary 属性通常显示在 Outlook 的列表视图中,用于快速确定卡片的主题。The summary property is typically displayed in the list view in Outlook, as a way to quickly determine what the card is all about.

务必始终包含摘要。Do always include a summary.
请勿在摘要中包含详细信息。例如,对于 Twitter 帖子,摘要可能仅显示“@someuser 的新推文”,而不提及推文本身的内容。Don't include details in the summary. For example, for a Twitter post, a summary might simply read "New tweet from @someuser" without mentioning the content of the tweet itself.
themeColor 字符串String 指定卡片的自定义品牌颜色。颜色将以不突兀的方式显示。Specifies a custom brand color for the card. The color will be displayed in a non-obtrusive manner.

务必使用 themeColor 作为卡片的品牌颜色Do use themeColor to brand cards to your color.
请勿使用 themeColor 指示状态。Don't use themeColor to indicate status.
hideOriginalBody BooleanBoolean 仅适用于电子邮件中的卡片Only applies to cards in email messages

设置为 true 时,将隐藏邮件的 HTML 正文。当卡片是比 HTML 正文本身更好或更有用的内容表示形式,尤其是在卡片包含操作时,上述设置会非常有用(参阅下文)。When set to true, causes the HTML body of the message to be hidden. This is very useful in scenarios where the card is a better or more useful representation of the content than the HTML body itself, which is especially true when the card contains actions (see below.)

在以下情况下,请考虑隐藏原始的 HTML 正文:Consider hiding the original HTML body:
  • 如果卡片本身包含用户需要的所有信息If the card itself contains all the information a user would need
  • 如果附加正文内容后,卡片内容冗余If the content of the card is redundant with the content of the body
务必始终要包含一个良好的 HTML 正文,即使会将其隐藏。HTML 正文是不支持卡片的电子邮件客户端可以显示的唯一内容。此外,回复或转发电子邮件时不包含卡片,仅包含 HTML 正文。Do always include a nice HTML body, even if it is going to be hidden. The HTML body is the only thing an email client that doesn't support cards will be able to display. Furthermore, cards are not included when replying to or forwarding emails, only the HTML body.
当正文与卡片显示的信息相互补充时,请勿隐藏正文。例如,零用金报销单审批正文可能会详细说明报销单,而卡片仅显示简短摘要和批准/拒绝操作。Don't hide the body when it is complementary to the information presented in the card. For example, the body of an expense report approval might describe the report in great details while the card just presents a quick summary along with approve/decline actions.
title 字符串String title 属性以醒目的方式显示在卡片的最顶部。使用它来简要介绍卡片内容,以便用户可以快速了解其中的内容。The title property is meant to be rendered in a prominent way, at the very top of the card. Use it to introduce the content of the card in such a way users will immediately know what to expect.

示例:Examples:
  • 每日新闻Daily news
  • 创建新 bugNew bug opened
  • 分配的任务 <name of task>Task <name of task> assigned
务必使标题保持简短,请勿使用长句。Do keep title short, don't make it a long sentence.
务必在标题中提及引用的实体名称。Do mention the name of the entity being referenced in the title.
请勿在标题中通过 Markdown 使用超链接。Don't use hyperlinks (via Markdown) in the title.
text 字符串String 如果卡片不包含 summary 属性,则必填;否则可选。Required if the card does not contain a summary property, otherwise optional. text 属性以正常字体显示在卡片标题下方。The text property is meant to be displayed in a normal font below the card's title. 使用它来显示内容,例如引用的实体的说明,或者新闻文章的摘要。Use it to display content, such as the description of the entity being referenced, or an abstract of a news article.

务必使用简单的 Markdown,例如用于强调语句的粗体或斜体及外部资源链接。Do use simple Markdown, such as bold or italics to emphasize words, and links to external resources.
请勿在文本属性中包含任何操作调用。用户应该可以不阅读它,但仍能了解卡片的所有内容。Don't include any call to action in the text property. Users should be able to not read it and still understand what the card is all about.
sections Array of SectionArray of Section 要包括在卡片中的分区集合。A collection of sections to include in the card. 请参阅分区字段See Section fields.
potentialAction Actions 的数组Array of Actions 可以在该卡片上调用的操作集合。请参阅操作A collection of actions that can be invoked on this card. See Actions.

分区字段Section fields

字段Field 类型Type 描述Description
title 字符串String 分区的 title 属性以突出但不像卡片标题一般醒目的字体显示。它用于简要介绍分区并总结其内容,与卡片标题属性用于总结整个卡片的方式相似。The title property of a section is displayed in a font that stands out while not as prominent as the card's title. It is meant to introduce the section and summarize its content, similarly to how the card's title property is meant to summarize the whole card.

务必使标题保持简短,请勿使用长句。Do keep title short, don't make it a long sentence.
务必在标题中提及引用的实体名称。Do mention the name of the entity being referenced in the title.
请勿在标题中通过 Markdown 使用超链接。Don't use hyperlinks (via Markdown) in the title.
startGroup 布尔值Boolean 设置为 true 时,startGroup 属性将标记信息逻辑组的开头。通常,将 startGroup 设置为 true 的分区将直观地与以前的卡片元素分隔开。例如,Outlook 使用一条很细的水平分割线。When set to true, the startGroup property marks the start of a logical group of information. Typically, sections with startGroup set to true will be visually separated from previous card elements. For example, Outlook uses a subtle horizontal separation line.

An example of the separation of sections with startGroup=true

务必使用 startGroup 来分隔表示不同对象的分区;例如,摘要中的多个推文。Do use startGroup to separate sections that represent different objects; for example, multiple tweets in a digest.
activityImage
activityTitle
activitySubtitle
activityText
字符串String 这四个属性构成一个逻辑组,activityTitleactivitySubtitleactivityText 将使用适用于查看此卡片的设备外形规格的布局与 activityImage 一起并排显示。例如,在 Outlook 网页版中,activityTitleactivitySubtitleactivityText 使用两列布局在 activityImage 的右侧显示。These four properties form a logical group. activityTitle, activitySubtitle and activityText will be displayed alongside activityImage, using a layout appropriate for the form factor of the device the card is being viewed on. For instance, in Outlook on the Web, activityTitle, activitySubtitle and activityText are displayed on the right of activityImage, using a two-column layout:

An example activity layout

将活动字段用于类似以下的场景:Use the activity fields for scenarios such as:
  • 某人做了某事Someone did something
    • 使用 activityImage 显示此人的头像。Use activityImage to display the picture of that person.
    • 使用 activityTitle 总结他们的行为。使其简明扼要。Use activityTitle to summarize what they did. Make it short and to the point.
    • 使用 activitySubtitle 显示类似于操作发生的日期和时间或此人的昵称的内容。Use activitySubtitle to show, for instance, the date and time the action was taken, or the person's handle.
      • activitySubtitle 将以更为低调的字体显示activitySubtitle will be rendered in a more subdued font
      • 请勿包含重要信息Don't include essential information
      • 请勿包含操作调用Don't include calls to action
      • 避免使用 Markdown 格式设置Avoid Markdown formatting
    • 使用 activityText 提供活动的详细信息。Use activityText to provide details about the activity.
      • 务必使用简单的 Markdown 来强调语句或外部源链接。Do use simple Markdown to emphasize words or link to external sources
      • 请勿包含操作调用Don't include calls to action
  • 新闻文章摘要A news article abstract
    • 使用 activityImage 显示与文章相关的图片Use activityImage to display the picture associated with the article
    • 使用 activitySubtitle 显示文章的最初发布日期和时间Use activitySubtitle to display the date and time the article was originally posted
    • 使用 activityText 显示实际的摘要。Use activityText to display the actual abstract
heroImage 图像Image 使用 heroImage 使图像成为卡片的核心。例如,包含图片的推文可能想要将此图片放在正前方:Use heroImage to make an image the centerpiece of your card. For example, a tweet that contains an image will want to put that image front and center:

An example of a hero image in a message card

heroImage 还可用于向卡片添加横幅,例如下面的“TINYPulse – Engage”横幅:heroImage can also be used to add a banner to your card, like the "TINYPulse – Engage" banner below:

An example of using a heroImage to create a banner
text 字符串String 此分区的 text 属性与卡片的 text 属性非常相似。它可用于同一目的。The section's text property is very similar to the text property of the card. It can be used for the same purpose.
facts Array of name/value pairsArray of name/value pairs 事件是分区非常重要的组件。它们通常包含对用户而言非常重要的信息。Facts are a very important component of a section. They often contain the information that really matters to the user.

事件以可供快速高效阅读的方式显示。例如,在 Outlook 网页版中,事件以两列布局显示,并且将事件名称以更为醒目的字体显示:Facts are displayed in such a way that they can be read quickly and efficiently. For example, in Outlook on the Web, facts are presented in a two-column layout, with fact names rendered in a slightly more prominent font:

An example of facts being displayed

事件有许多用途。以下是部分应用场景:There are many uses for facts. Some scenarios:
  • 创建了 bugA bug was created
    • Bug ID:1234Bug ID: 1234
    • 建立者:Adele VanceOpened by: Adele Vance
    • 分配到:Alex DarrowAssigned to: Alex Darrow
  • 应用程序使用情况报告Application usage report
    • 应用程序名称:Contoso CRM 应用Application name: Contoso CRM App
    • 时间段:2016 年 8 月 1 日 - 2016 年 9 月 30 日Period: August 1, 2016 - September 30, 2016
    • 用户数量:542Number of users: 542
    • 会话数:2056Number of sessions: 2056
    • 应用程序的平均使用时间:76 秒Average time spend in the application: 76 seconds
  • 支出审核Expense approval
    • 提交人:Pradeep GuptaSubmitted by: Pradeep Gupta
    • 提交日期:2016 年 10 月 21 日Date submitted: October 21, 2016
    • 总金额:$1,426.95Total amount: $1,426.95
在卡片或分区的文本属性中,务必使用事件,而不要在其中嵌入重要信息。Do use facts instead of embedding important information inside the text property of either the card or the section.
务必使事件名称保持简短。Do keep fact names short.
避免使事件值过长。Avoid making fact values too long.
避免对事件名称和值使用 Markdown格式设置以可最大程度发挥其影响力的方式显示事件。Avoid using Markdown formatting for both fact names and values. Let facts be rendered as intended as that is how they will have the most impact.
但是务必仅将 Markdown 用于事件值中的链接。例如,如果事件引用了外部文档,则让该事件的值成为该文档的链接。Do however use Markdown for links in fact values only. For instance, if a fact references an external document, make the value of that fact a link to the document.
请勿添加没有实际用途的事件。例如,在所有卡片中的值始终相同的事件没有意义,并且会浪费空间。Don't add a fact without a real purpose. For instance, a fact that would always have the same value across all cards is not interesting and a waste of space.
images 图像对象的数组Array of Image objects 通过 images 属性,可以在分区中包含照片库。该照片库将始终以便于使用的方式显示,无论查看它的设备的外形规格如何。例如,在 Outlook 网页版中,可以将图像显示为一个缩略图横条,并且如果其大小与屏幕不完全匹配则可通过控件滚动该集合。在移动设备上,可将图像显示为单个缩略图,并且用户可以使用手指滑动集合。The images property allows for the inclusion of a photo gallery inside a section. That photo gallery will always be displayed in a way that is easy to consume regardless of the form factor of the device it is being viewed on. For instance, in Outlook on the Web, images might be displayed as a horizontal strip of thumbnails with controls allowing to scroll through the collection if it doesn't all fit on the screen. On mobile, images might be displayed as a single thumbnail, with the user able to swipe through the collection with their finger.
potentialAction Array of ActionsArray of Actions 可以在该分区上调用的操作集合。请参阅操作A collection of actions that can be invoked on this section. See Actions.

Image 对象Image object

定义分区的 heroImageimages 属性使用的图像。Defines an image as used by the heroImage and images property of a section.

字段Field 类型Type 描述Description
image StringString 图像的 URL。The URL to the image.
title 字符串String 图像的简要说明。通常,当用户将鼠标悬浮在图像上方时,title 会在工具提示中显示。A short description of the image. Typically, title is displayed in a tooltip as the user hovers their mouse over the image.

操作Actions

用户可以通过卡片快速执行操作而无需离开其电子邮件客户端,从这一点来说,卡片非常强大。设计卡片时,请考虑使其具有可操作性,因为这样可以提高用户参与度和效率。Cards are very powerful in the sense that they allow users to take quick actions without leaving their email client. When designing cards, consider making them actionable, as that will increase user engagement and productivity.

操作使用 potentialAction 属性进行指定,卡片本身及各个分区都包含此属性。Actions are specified using the potentialAction property which is available both on the card itself and on each section. 操作有五种类型:There are five types of actions:

potentialAction 集合最多可以包含 4 个操作(无论是哪种类型)。There can be a maximum of 4 actions (whatever their type) in a potentialAction collection.

  • 务必包含对最终用户影响最大的操作,例如重复率最大的操作。Do include actions that will make the biggest impact for the end user, like the most repetitive ones.
  • 如果没有明确理由,请勿添加 4 个操作。在许多情况下,操作越少,体验越好。Don't add 4 actions just because you can. In many cases, fewer actions will lead to a better experience.
  • 请勿以替代外部应用程序为目的而创建卡片。卡片旨在补充此类应用程序,而非替代它们。Don't craft your cards in an effort to replace an external application. Cards are meant to complement such applications, not to replace them.

OpenUri 操作OpenUri action

在单独的浏览器或应用中打开 URI。Opens a URI in a separate browser or app.

虽然可以通过 Markdown 实现链接,但是 OpenUri 操作具有以下优势:你可以通过它为不同操作系统指定不同 URI,从而可以在移动设备上的应用中打开此链接。Although links can be achieved through Markdown, an OpenUri action has the advantage of allowing you to specify different URIs for different operating systems, which makes it possible to open the link in an app on mobile devices.

  • 如果用户在使用移动设备的应用打开链接这一方面有显著优势,则考虑使用 OpenUri 操作代替 Markdown 中的链接。Consider using an OpenUri action rather than a link in Markdown if there is a clear advantage for your users in their ability to open the link in an app on their mobile device.
  • 务必至少包含一个 OpenUri 操作,以在生成实体的外部应用中查看实体。Do include at least an OpenUri action to view the entity in the external app it comes from.
  • 务必OpenUri 操作作为 potentialAction 集合中的最后一个操作。Do make the OpenUri action the last one in the potentialAction collection.

备注

Microsoft Teams 和 Outlook 网页版仅支持对 OpenUri 操作使用 targets 数组中的 HTTP/HTTPS URL。Microsoft Teams and Outlook on the web only support HTTP/HTTPS URLs in the targets array for an OpenUri action.

字段Field 类型Type 描述Description
name StringString name 属性定义屏幕针对操作显示的文本。The name property defines the text that will be displayed on screen for the action.

务必使用动词。例如,使用“设置截止日期”而非“截止日期”,或使用“添加注释”而非“注释”。在某些情况下,名词自身也可以正常工作,这只是因为其也是一个动词:“comment”Do use verbs. For instance, use "Set due date" instead of "Due date" or "Add note" instead of "Note." In some cases, the noun itself just works because it is also a verb: "Comment"
请勿OpenUri 操作命名为暗示可直接从客户端执行此操作的名称。相反,将操作命名为“在<网站/应用名称>中查看”或“在<网站/应用名称>中打开”。Don't name an OpenUri action in such a way that it suggests the action can be taken right from the client. Instead, name the action "View in <name of site/app>" or "Open in <name of site/app>"
targets 数组Array targets 属性是为每个目标操作系统定义一个 URI 的名称/值对集合。The targets property is a collection of name/value pairs that defines one URI per target operating system.

支持的操作系统值为:defaultwindowsiOSandroiddefault 操作系统通常只在 Web 浏览器中打开 URI,无论实际操作系统如何。Supported operating system values are default, windows, iOS and android. The default operating system will in most cases simply open the URI in a web browser, regardless of the actual operating system.

示例目标属性:Example targets property:
"targets": [
{ "os": "default", "uri": "https://yammer.com/.../123" },
{ "os": "iOS", "uri": "yammer://u/123" },
{ "os": "android", "uri": "yammer://u/123" },
{ "os": "windows", "uri": "yammer://u/123" }
]

HttpPOST 操作HttpPOST action

调用外部 Web 服务。Makes a call to an external Web service.

执行 HttpPOST 操作后,将向 target 字段中的 URL 发出 POST 请求,而目标服务需要对调用方进行身份验证。可通过各种方式完成此操作,例如通过目标 URL 中嵌入的有限目的令牌。有关选择最适合特定场景的安全机制的详细信息和帮助,请参阅可操作邮件的安全要求When an HttpPOST action is executed, a POST request is made to the URL in the target field, and the target service needs to authenticate the caller. This can be done in a variety of ways, including via a Limited Purpose Token embedded in the target URL. For more information and help on choosing the security mechanism that works best for your particular scenario, please see Security requirements for actionable messages.

字段Field 类型Type 描述Description
name StringString name 属性定义屏幕针对操作显示的文本。The name property defines the text that will be displayed on screen for the action.

务必使用动词。例如,使用“设置截止日期”而非“截止日期”,或使用“添加注释”而非“注释”。在某些情况下,名词自身也可以正常工作,这只是因为其也是一个动词:“comment”Do use verbs. For instance, use "Set due date" instead of "Due date" or "Add note" instead of "Note." In some cases, the noun itself just works because it is also a verb: "Comment"
target 字符串String 定义实现操作的服务的 URL 终结点。Defines the URL endpoint of the service that implements the action. 注释: 必须可通过 Internet 访问此 URL,无法使用 localhostNote: this URL must be accessible from the internet, you cannot use localhost.
headers Header 的数组Array of Header Header 对象集合,表示向目标 URL 发送 POST 请求时将发出的 HTTP 标头集。请参阅标头A collection of Header objects representing a set of HTTP headers that will be emitted when sending the POST request to the target URL. See Header.
body 字符串String POST 请求的正文。The body of the POST request.
bodyContentType StringString bodyContentType 为可选,并指定 POST 请求正文的 MIME 类型。The bodyContentType is optional and specifies the MIME type of the body in the POST request. 一些服务要求指定内容类型。Some services require that a content type be specified. 有效值为 application/jsonapplication/x-www-form-urlencodedValid values are application/json and application/x-www-form-urlencoded. 如果未指定,则假定已指定 application/jsonIf not specified, application/json is assumed.

Header 对象是表示 HTTP 标头的名称/值对。The Header object is a name/value pair that represents an HTTP header.

字段Field 类型Type 描述Description
name 字符串String 标头名称The header name
value 字符串String 头值The header value

报告操作执行成功与否Reporting an action's execution success or failure

HttpPOST 操作可在其响应中包含CARD-ACTION-STATUS HTTP 标头。该标头包含指示操作执行结果(成功还是失败)的文本。HttpPOST actions can include the CARD-ACTION-STATUS HTTP header in their response. This header is meant to contain text that indicates the outcome of the action's execution, whether it has succeeded or failed.

该标头的值将以一致的方式显示在卡片的保留区中。还可以通过卡片将其保存,以便可以在以后再显示它,这样就可以提醒用户已在给定卡片上执行的操作。The value of the header will be displayed in a consistent way in a reserved area of the card. It is also saved with the card so it can be displayed later on, so users can be reminded of the actions that have already been executed on a given card.

提示

返回 HttpPOST 操作的响应时,请遵循下面这些准则。Follow these guidelines when returning a response to HttpPOST actions.

  • 在响应中返回 CARD-ACTION-STATUS 头。Do return the CARD-ACTION-STATUS header in your responses.
  • 务必尽可能地使标头中的消息提供丰富且有意义的内容。例如,对于零用金报销单上的“审批”操作:Do make the message in that header as informative and meaningful as possible. For instance, for an "approve" action on an expense report:
    • 如果成功,则不要返回“操作已成功”,而返回“已审批支出”In case of success, don't return "The action was successful", instead return "The expense was approved"
    • 如果失败,则不要返回“操作已失败”,而返回“当前无法审批该支出。请稍后再试”In case of failure, don't return "The action failed", instead return "The expense couldn't be approved at this time. Please try again later"
  • 请勿CARD-ACTION-STATUS 标头中提及执行操作的人员名称及执行操作的时间。将自动添加这两条信息并以一致的方式显示。Don't mention either the name of the person taking the action nor the time the action is being taken in your CARD-ACTION-STATUS header. Both these pieces of information will be automatically added for you and displayed in a consistent way.

刷新卡片Refresh cards

刷新卡片是非常强大的机制,通过它,HttpPOST 操作可以在其成功完成后以动态形式对卡片进行完全更新。许多场景可从刷新卡片机制受益:Refresh cards are a very powerful mechanism that allow HttpPOST actions to fully update the card on the fly as the action successfully completes. There are many scenarios that benefit from refresh cards:

  • 审批场景(例如零用金报销单)Approval scenario (e.g. expense report)
    • 批准或拒绝请求后,将刷新卡片以删除批准/拒绝操作并更新其内容,以便其反映请求已被批准或拒绝的事实。Once the request is approved or rejected, the card is refreshed to remove the approve/decline actions and update its content so it reflects the fact that it's been approved or declined
  • 任务状态Task status
    • 对任务执行操作后,例如设置其截止日期,卡片将进行刷新以便在事件中包含更新的截止日期When an action is taken on a task, such as setting its due date, the card refreshes to include the updated due date in its facts
  • 调查Survey
    • 问题得到答复后,卡片将进行刷新,以便:Once the question has been answered, the card is refreshed so:
      • 不再允许用户回答It no longer allows the user to respond
      • 显示更新状态,例如在用户实际回答旁显示“感谢答复此调查”It shows updated status, like "Thanks for responding to this survey" alongside the user's actual response
      • 可能包含新的 OpenUri 操作,以供用户在线咨询此调查。Potentially include a new OpenUri action that allows the user to consult the survey online

若要刷新 HttpPOST 操作后生成的卡片,服务需要执行以下操作:To refresh a card as a result of an HttpPOST action, a service needs to do the following:

  • 在其收到的 HTTP POST 请求响应的正文中加入新卡片的 JSON 负载。Include the JSON payload of the new card in the body of the response to the HTTP POST request it received.
  • CARD-UPDATE-IN-BODY: true HTTP 标头添加到响应中,以使接收客户端知道其应分析响应正文并提取新卡片(如果未包含刷新卡片机制,则此操作可避免不必要的处理过程)。Add the CARD-UPDATE-IN-BODY: true HTTP header to the response, in order to let the receiving client know that it should parse the response body and extract a new card (this is to avoid unnecessary processing when no refresh card is included.)

提示

返回刷新卡片时,请遵循下面这些准则。Follow these guidelines when returning refresh cards.

  • 务必对只能执行一次的操作使用刷新卡片机制。在这些情况下,刷新卡片不会包含无法再次执行的操作。Do use refresh cards with actions that can only be taken a single time. In those cases, the refresh card would not include any action that cannot be taken anymore
  • 务必对将更改执行操作的实体状态的操作使用刷新卡片机制。在这些情况下,刷新卡片应包含实体的更新信息,并且可以更改可供执行的操作集。Do use refresh cards with actions that change the state of the entity they are performed on. In those cases, the refresh card should include updated information about the entity, and MAY change the set of actions that can be performed
  • 请勿使用刷新卡片与用户进行对话。例如,请勿将刷新卡片用于多步骤“向导”Don't use refresh cards to lead a conversation with the user. For instance, don't use refresh cards for a multi-step "wizard"
  • 至少包含一个 OpenUri 操作,以便在生成实体的外部应用程序中查看实体。Do include at least an OpenUri action to view the entity in the external app it comes from.

ActionCard 操作ActionCard action

显示其他 UI,其中包含一个或多个输入OpenUriHttpPOST 类型的关联操作。Presents additional UI that contains one or more Inputs, along with associated actions that can be either OpenUri or HttpPOST types.

如果操作需要用户的其他输入,则务必使用 ActionCard 操作。以下是部分应用场景:Do use an ActionCard action if an action requires additional input from the user. Some scenarios:

  • 答复调查Responding to a survey
  • 向 bug 添加注释Adding a comment to a bug
  • 提供拒绝零用金报销单的理由Providing justification for declining an expense report

默认情况下,ActionCard 操作将显示为卡片 UI 中的按钮或链接。单击后,该按钮将显示其他 UI,其中包含操作卡片中定义的输入和操作。By default, an ActionCard action will be represented as a button or link in the card's UI. When clicked, that button will display an additional piece of UI containing the inputs and actions defined in the action card.

如果 potentialAction 集合中有一个 ActionCard 操作,则 Outlook 将以“预展开”方式显示该操作。例如其输入和操作将立即显示。If there is a single ActionCard action in a potentialAction collection, then Outlook will represent that action "pre-expanded," e.g. its inputs and actions will be immediately visible.

字段Field 类型Type 描述Description
name StringString name 属性定义屏幕针对操作显示的文本。The name property defines the text that will be displayed on screen for the action.

务必使用动词。例如,使用“设置截止日期”而非“截止日期”,或使用“添加注释”而非“注释”。在某些情况下,名词自身也可以正常工作,这只是因为其也是一个动词:“comment”Do use verbs. For instance, use "Set due date" instead of "Due date" or "Add note" instead of "Note." In some cases, the noun itself just works because it is also a verb: "Comment"
inputs Inputs 的数组Array of Inputs inputs 属性定义操作卡片的 UI 中将显示的各种输入。请参阅输入The inputs property defines the various inputs that will be displayed in the action card's UI. See Inputs
actions Array of ActionsArray of Actions actions 属性是 Action 对象数组,可以是 OpenUriHttpPOST 类型。ActionCard 操作的 actions 属性不能包含其他 ActionCard 操作。The actions property is an array of Action objects, that can be either of type OpenUri or HttpPOST. The actions property of an ActionCard action cannot contain another ActionCard action.

示例 ActionCardExample ActionCard

{
  "@type": "ActionCard",
  "name": "Comment",
  "inputs": [
    {
      "@type": "TextInput",
      "id": "comment",
      "isMultiline": true,
      "title": "Input's title property"
    }
  ],
  "actions": [
    {
      "@type": "HttpPOST",
      "name": "Action's name prop.",
      "target": "https://yammer.com/comment?postId=123",
      "body": "comment={{comment.value}}"
    }
  ]
}

输入Inputs

支持三种类型的输入:TextInputDateInputMultichoiceInputThree types of inputs are supported: TextInput, DateInput, and MultichoiceInput.

通用字段Common fields

以下是所有输入类型通用的字段。The following fields are common to all input types.

字段Field 类型Type 描述Description
id 字符串String 输入的唯一标识,以便可以在 HttpPOST 操作的 URL 或正文中引用此输入。请参阅输入值替换Uniquely identifies the input so it is possible to reference it in the URL or body of an HttpPOST action. See Input value substitution.
isRequired BooleanBoolean 指示用户是否需要键入值,以便可以执行将输入值用作参数的操作。Indicates whether users are required to type a value before they are able to take an action that would take the value of the input as a parameter.

如果用户必须提供值,则务必将输入作为必需。Do make an input required if users MUST provide a value.
如果输入值是对其他必需输入值的补充,则考虑将输入作为必需。例如,可以使用多选输入定义询问“您对自己汽车的满意度是多少”的调查问题,并在后面附加“请详细解释你的答案”作为自由文本输入。注意一些用户不喜欢被强制提供此类说明,因此可能不会对此调查作出任何回复。Consider making an input required if its value is complementary to that of another required input. For instance, you could define a survey question that asks "How satisfied are you with your car" with a multi choice input followed by "Please explain your answer" as a free text input. Keep in mind that some users might not like being forced into providing such explanations, and might as a result not respond to the survey at all.
务必确保用户了解哪些输入是必需的。在输入的标题属性中包含一个标签。例如,Comment (optional)Please rate your experience (required)Do make sure users know which inputs are required. Include a label in the input's title property. For example: Comment (optional) or Please rate your experience (required).
title 字符串String 定义输入的标题。Defines a title for the input.
value StringString 定义输入的初始值。对于多选输入,值必须等于输入的选择之一的值属性。Defines the initial value of the input. For multi-choice inputs, value must be equal to the value property of one of the input's choices.
TextInputTextInput

需要用户提供自由文本时,例如调查问题回复,使用此输入类型。Use this input type when you need users to provide free text, such as the response to a survey question.

字段Field 类型Type 说明Description
isMultiline BooleanBoolean 指示文本输入是否接受多行文本。Indicates whether the text input should accept multiple lines of text.
maxLength NumberNumber 指示可以输入的最大字符数。Indicates the maximum number of characters that can be entered.
示例 TextInputExample TextInput
{
  "@type": "TextInput",
  "id": "comment",
  "isMultiline": true,
  "title": "Input's title property"
}
DateInputDateInput

需要用户提供日期或时间,例如任务的截止日期时,使用此输入类型。Use this input type when you need users to provide a date and or a time, such as for a task's due date.

字段Field 类型Type 说明Description
includeTime BooleanBoolean 指示日期输入除日期之外是否还允许选择时间。Indicates whether the date input should allow for the selection of a time in addition to the date.
示例 DateInputExample DateInput
{
  "@type": "DateInput",
  "id": "dueDate",
  "title": "Input's title property"
}
MultichoiceInputMultichoiceInput

需要用户从预定义的选择列表进行选择,例如 bug 状态、是/否/可能等时,使用此输入类型。Use this input type when you need users to select from a list of pre-defined choices, such as a bug status, yes/no/maybe, etc.

字段Field 类型Type 说明Description
choices Array of name/value pairsArray of name/value pairs 定义可为多选输入选择的值。Defines the values that can be selected for the multichoice input.
isMultiSelect 布尔值Boolean 如果设置为 true,则指示用户可以选择多个选项。指定的选项将显示为复选框列表。默认值为 falseIf set to true, indicates that the user can select more than one choice. The specified choices will be displayed as a list of checkboxes. Default value is false.

An example multi-selection input
style String (normal(default or expanded))String (normal(default or expanded)) isMultiSelectfalse 时,将 style 属性设置为 expanded 将指示主机应用程序尝试在屏幕上显示所有选项,通常会让其使用一组单选按钮。When isMultiSelect is false, setting the style property to expanded will instruct the host application to try and display all choices on the screen, typically using a set of radio buttons.

An example expanded input
示例紧凑型 MultichoiceInputExample compact MultichoiceInput
{
  "@type": "MultichoiceInput",
  "id": "list",
  "title": "Pick an option",
  "choices": [
    { "display": "Choice 1", "value": "1" },
    { "display": "Choice 2", "value": "2" },
    { "display": "Choice 3", "value": "3" }
  ]
}
示例多项选择 MultichoiceInputExample multi-select MultichoiceInput
{
  "@type": "MultichoiceInput",
  "id": "list",
  "title": "Pick an option",
  "isMultiSelect": true,
  "choices": [
    { "display": "Choice 1", "value": "1" },
    { "display": "Choice 2", "value": "2" },
    { "display": "Choice 3", "value": "3" }
  ]
}
示例展开的 MultichoiceInputExample expanded MultichoiceInput
{
  "@type": "MultichoiceInput",
  "id": "list",
  "title": "Pick an option",
  "style": "expanded",
  "choices": [
    { "display": "Choice 1", "value": "1" },
    { "display": "Choice 2", "value": "2" },
    { "display": "Choice 3", "value": "3" }
  ]
}

输入值替换Input value substitution

可在 ViewActionHttpPOST 操作的任意 URL 中引用输入值。还可在 HttpPOST 操作的正文中引用它。引用输入值时,会在执行此操作的前一刻将其替换为实际输入值。The value of an input can be referenced in any URL of a ViewAction or HttpPOST action. It can also be referenced in an HttpPOST action's body. When an input value is referenced, it is substituted with the actual value of the input right before the action is executed.

如需引用输入值,请使用以下格式:To reference an input's value, use the following format:

{{<id of input>.value}}

输入值替换示例Input value substitution example
{
  "@type": "ActionCard",
  "name": "Comment",
  "inputs": [
    {
      "@type": "TextInput",
      "id": "comment",
      "isMultiline": true,
      "title": "Input's title property"
    }
  ],
  "actions": [
    {
      "@type": "HttpPOST",
      "name": "Action's name prop.",
      "target": "https://yammer.com/comment?postId=123",
      "body": "comment={{comment.value}}"
    }
  ]
}

InvokeAddInCommand 操作InvokeAddInCommand action

打开 Outlook 加载项任务窗格。Opens an Outlook add-in task pane. 如果未安装加载项,用户会看到提示,只需单击一下即可安装加载项。If the add-in is not installed, the user is prompted to install the add-in with a single click.

执行 InvokeAddInCommand 操作时,Outlook 会先检查是否已为用户安装并启用请求的加载项。When an InvokeAddInCommand action is executed, Outlook first checks if the requested add-in is installed and turned on for the user. 如果没有,将通知用户此操作需要使用加载项,只需单击一下,即可安装并启用加载项。If it is not, the user is notified that the action requires the add-in, and is able to install and enable the add-in with a single click. Outlook 打开请求,为加载项提供此操作指定的任何初始化上下文。Outlook opens the requested , making any initialization context specified by the action available to the add-in.

如需了解更多信息,请参阅通过可操作邮件调用 Outlook 加载项For more information, see Invoke an Outlook add-in from an actionable message.

字段Field 类型Type 描述Description
name StringString name 属性定义屏幕针对操作显示的文本。The name property defines the text that will be displayed on screen for the action.

务必使用动词。例如,使用“设置截止日期”而非“截止日期”,或使用“添加注释”而非“注释”。在某些情况下,名词自身也可以正常工作,这只是因为其也是一个动词:“comment”Do use verbs. For instance, use "Set due date" instead of "Due date" or "Add note" instead of "Note." In some cases, the noun itself just works because it is also a verb: "Comment"
addInId UUIDUUID 指定相应加载项的加载项 ID。Specifies the add-in ID of the required add-in. 加载项清单的 Id 元素中包含加载项 ID。The add-in ID is found in the Id element in the add-in's manifest.
desktopCommandId 字符串String 指定打开所需任务窗格的加载项命令按钮的 ID。Specifies the ID of the add-in command button that opens the required task pane. 加载项清单中定义此按钮的 Control 元素id 属性中包含此命令按钮 ID。The command button ID is found in the id attribute of the Control element that defines the button in the add-in's manifest. 必须在 MessageReadCommandSurface 扩展点中定义指定的 Control 元素,并且必须为 Button 类型。此外,控件的 Action 还必须为 ShowTaskPane 类型。The specified Control element MUST be defined inside a MessageReadCommandSurface extension point, be of type Button, and the control's Action must be of type ShowTaskPane.
initializationContext ObjectObject 可选。Optional. 开发者可以在此字段中指定任意有效的 JSON 对象。Developers may specify any valid JSON object in this field. 此值会序列化为字符串,并在操作执行时提供给加载项。The value is serialized into a string and made available to the add-in when the action is executed. 这允许该操作将初始化数据传递给加载项。This allows the action to pass initialization data to the add-in.

示例 InvokeAddInCommandExample InvokeAddInCommand

{
  "@type": "InvokeAddInCommand",
  "name": "Invoke My Add-in",
  "addInId": "527104a1-f1a5-475a-9199-7a968161c870",
  "desktopCommandId": "show ",
  "initializationContext": {
    "property1": "Hello world",
    "property2": 5,
    "property3": true
  }
}

卡片示例Card Examples

TrelloTrello

在列表中生成卡片:Card is created in a list:

示例 Trello 卡片

以下是该卡片的生成方式:Here is how that card is built:

说明示例 Trello 卡片组成部分的关系图

以下是展开“添加注释”**** 操作后的同一个卡片:Here's the same card with the Add a comment action expanded:

展开操作卡片后的示例 Trello 卡片

以下是“添加注释”**** 操作的生成方式:Here's how the Add a comment action is built:

说明展开操作卡片后的示例 Trello 卡片组成部分的关系图

Trello JSONTrello JSON

{
  "summary": "Card \"Test card\"",
  "themeColor": "0078D7",
  "title": "Card created: \"Name of card\"",
  "sections": [
    {
      "activityTitle": "David Claux",
      "activitySubtitle": "9/13/2016, 3:34pm",
      "activityImage": "https://connectorsdemo.azurewebsites.net/images/MSC12_Oscar_002.jpg",
      "facts": [
        {
          "name": "Board:",
          "value": "Name of board"
        },
        {
          "name": "List:",
          "value": "Name of list"
        },
        {
          "name": "Assigned to:",
          "value": "(none)"
        },
        {
          "name": "Due date:",
          "value": "(none)"
        }
      ],
      "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."
    }
  ],
  "potentialAction": [
    {
      "@type": "ActionCard",
      "name": "Set due date",
      "inputs": [
        {
          "@type": "DateInput",
          "id": "dueDate",
          "title": "Select a date"
        }
      ],
      "actions": [
        {
          "@type": "HttpPOST",
          "name": "OK",
          "target": "https://..."
        }
      ]
    },
    {
      "@type": "ActionCard",
      "name": "Move",
      "inputs": [
        {
          "@type": "MultichoiceInput",
          "id": "move",
          "title": "Pick a list",
          "choices": [
            { "display": "List 1", "value": "l1" },
            { "display": "List 2", "value": "l2" }
          ]
        }
      ],
      "actions": [
        {
          "@type": "HttpPOST",
          "name": "OK",
          "target": "https://..."
        }
      ]
    },
    {
      "@type": "ActionCard",
      "name": "Add a comment",
      "inputs": [
        {
          "@type": "TextInput",
          "id": "comment",
          "isMultiline": true,
          "title": "Enter your comment"
        }
      ],
      "actions": [
        {
          "@type": "HttpPOST",
          "name": "OK",
          "target": "https://..."
        }
      ]
    },
    {
      "@type": "OpenUri",
      "name": "View in Trello",
      "targets": [
        { "os": "default", "uri": "https://..." }
      ]
    }
  ]
}

TwitterTwitter

以下是 Twitter 摘要卡片示例:Here's an example of a Twitter digest card:

示例 Twitter 摘要卡片

以下是该卡片的生成方式:Here's how that card is built:

说明示例 Twitter 摘要卡片组成部分的关系图

Twitter JSONTwitter JSON

{
  "themeColor": "0078D7",
  "sections": [
    {
      "activityTitle": "**Elon Musk**",
      "activitySubtitle": "@elonmusk - 9/12/2016 at 5:33pm",
      "activityImage": "https://pbs.twimg.com/profile_images/782474226020200448/zDo-gAo0.jpg",
      "activityText": "Climate change explained in comic book form by xkcd xkcd.com/1732"
    },
    {
      "activityTitle": "**Mark Knopfler**",
      "activitySubtitle": "@MarkKnopfler - 9/12/2016 at 1:12pm",
      "activityImage": "https://pbs.twimg.com/profile_images/378800000221985528/b2ebfafca6fd7b565fdf3bf4ccdb4dc9.jpeg",
      "activityText": "Mark Knopfler features on B.B King's all-star album of Blues greats, released on this day in 2005..."
    }
  ]
}

可操作电子邮件Actionable email

以下示例为带嵌入的邮件卡片的 HTML 电子邮件正文。Here's an example of an HTML email body with an embedded message card.

<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <script type="application/ld+json">{
    "@context": "https://schema.org/extensions",
    "@type": "MessageCard",
    "originator": "",
    "hideOriginalBody": "true",
    "themeColor": "0072C6",
    "title": "Visit the Outlook Dev Portal",
    "text": "Click **Learn More** to learn more about Actionable Messages!",
    "potentialAction": [
      {
        "@type": "ActionCard",
        "name": "Send Feedback",
        "inputs": [
          {
            "@type": "TextInput",
            "id": "feedback",
            "isMultiline": true,
            "title": "Let us know what you think about Actionable Messages"
          }
        ],
        "actions": [
          {
            "@type": "HttpPOST",
            "name": "Send Feedback",
            "isPrimary": true,
            "target": "http://..."
          }
        ]
      },
      {
        "@type": "OpenUri",
        "name": "Learn More",
        "targets": [
          { "os": "default", "uri": "https://docs.microsoft.com/outlook/actionable-messages" }
        ]
      }
    ]
  }
  </script>
</head>
<body>
Visit the <a href="https://docs.microsoft.com/outlook/actionable-messages">Outlook Dev Portal</a> to learn more about Actionable Messages.
</body>
</html>