Referenz zu Nachrichtenkarten mit AktionenActionable message card reference

Karten sollen einfach zu lesende Informationen im Überblick bereitstellen, die Benutzer sehr schnell entschlüsseln und bei Bedarf umsetzen können. Die wichtigste Richtlinie für das Entwerfen einer ansprechenden Karte lautet daher „Inhalt statt Farbe“, was bedeutet, dass auf Karten deutliche Aussagen verwendet werden und dass die Verwendung anderer Elemente, die ablenken könnten, z. B. Symbole oder benutzerdefinierte Farben, minimiert wird.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.

Karten-PlaygroundCard playground

Sind Sie bereit, um mit Ihrem Kartenentwurf zu experimentieren? Gehen Sie zum Karten-Playground, wo Sie sehen können, wir Ihre Karte aussieht, während Sie die zugehörige JSON-Nutzlast bearbeiten.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.

Richtlinien für den EntwurfDesign guidelines

TextformatierungText formatting

Alle Textfelder in einer Karte und deren Bereiche können mithilfe von Markdown formatiert werden. Wir unterstützen einfaches Markdown.All text fields in a card and its section can be formatted using Markdown. We support basic Markdown.

Wichtig

Da alle Felder als Markdown verarbeitet werden, müssen Sie Sonderzeichen von Markdown bei Bedarf mit Escapezeichen versehen (z. B. * oder #).Since all fields are processed as Markdown, be sure to escape Markdown special characters (such as * or #) if needed.

EffektEffect MarkdownMarkdown
KursivItalics *Italic*
FettBold **Bold**
Fett KursivBold italics ***Bold Italic***
DurchgestrichenStrikethrough ~~Strikethrough~~
LinksLinks [Microsoft](https://www.microsoft.com)
Überschriften (<h1> bis <h6>Headings (<h1> through <h6> # Heading bis ###### Heading# Heading through ###### Heading
AufzählungenBulleted lists * List item oder - List item* List item or - List item

Tipp

Befolgen Sie diese Richtlinien beim Formatieren von Textfeldern.Follow these guidelines when formatting text fields.

  • Verwenden Sie Markdown zum Formatieren von Text.Do use Markdown to format text.
  • Verwenden Sie in Ihren Karten kein HTML-Markup. HTML wird ignoriert und als reiner Text behandelt.Don't use HTML markup in your cards. HTML is ignored and treated as plain text.

Mithilfe von AbschnittenUsing sections

Wenn Ihre Karte ein einzelne „Entität“ darstellt, müssen Sie möglicherweise keinen Abschnitt verwenden. Abschnitte unterstützen das Konzept einer „Aktivität“, was häufig eine gute Möglichkeit zum Darstellen von Daten in einer Karte darstellt.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.

Wenn Ihre Karte mehrere „Entitäten“ darstellt oder beispielsweise ein Digest für eine bestimmte Nachrichtenquelle ist, sollten Sie auf jeden Fall mehrere Abschnitte verwenden, und zwar einen pro „Entität“.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."

Tipp

Befolgen Sie diese Richtlinien bei der Planung des Layouts Ihrer Karte.Follow these guidelines when planning the layout of your card.

  • Verwenden Sie Abschnitte, um Daten logisch zu gruppieren.Do use sections to logically group data together.
  • In einigen Fällen KÖNNEN mehrere Abschnitte verwendet werden, um eine einzige logische Datengruppe darzustellen, dies bietet eine größere Flexibilität beim Sortieren der in der Karte präsentierten Informationen. Vor einer Aktivität kann beispielsweise eine Liste von Fakten angezeigt werden.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.
  • Verwenden Sie nicht mehr als 10 Abschnitte. Karten sollten einfach zu lesen sein. Wenn sich auf einer Karte zu viele Informationen befinden, verliert der Benutzer den Überblick.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.
  • Für Digest-ähnliche Karten sollten Sie das Hinzufügen der Aktion „Vollständigen Digest anzeigen“ am Ende der Karte hinzufügen.For digest-like cards, consider adding a "View full digest" action at the end of the card.

KartenfelderCard fields

FeldField TypType BeschreibungDescription
@type ZeichenfolgeString Erforderlich. Muss auf MessageCard festgelegt werden.Required. Must be set to MessageCard.
@context ZeichenfolgeString Erforderlich. Muss auf http://schema.org/extensions festgelegt werden.Required. Must be set to http://schema.org/extensions.
correlationId UUIDUUID Die correlationId-Eigenschaft vereinfacht das Auffinden von Protokollen zur Behandlung von Problemen.The correlationId property simplifies the process of locating logs for troubleshooting issues. Es wird empfohlen, beim Senden einer Aktion erfordernden Karte Ihren Service festzulegen und in dieser Eigenschaft eine eindeutige UUID zu protokollieren.We recommend that when sending an actionable card, your service should set and log a unique UUID in this property.

Wenn der Benutzer eine Aktion auf der Karte aufruft, sendet Office 365 die Header Card-Correlation-Id und Action-Request-Id in der POST-Anforderung an Ihren Dienst.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 enthält denselben Wert wie die correlationId-Eigenschaft auf der Karte.Card-Correlation-Id contains the same value as the correlationId property in the card. Action-Request-Id ist eine eindeutige UUID, die von Office 365 zum Auffinden einer bestimmten von einem Benutzer ausgeführten Aktion generiert wird.Action-Request-Id is a unique UUID generated by Office 365 to help locate specific action performed by a user. Der Dienst sollte beim Empfang von POST-Anforderungen für Aktionen beide Werte protokollieren.Your service should log both of these values when receiving action POST requests.
expectedActors Array aus ZeichenfolgenArray of String Optional.Optional. Enthält eine Liste erwarteter E-Mail-Adressen des Empfängers für den Aktionsendpunkt.This contains a list of expected email addresses of the recipient for the action endpoint.

Ein Benutzer kann mehrere E-Mail-Adressen haben, und der Aktionsendpunkt erwartet möglicherweise die jeweilige im sub-Anspruch präsentierte E-Mail-Adresse des Bearertokens nicht.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. Ein Benutzer könnte beispielsweise sowohl die E-Mail-Adresse john.doe@contoso.com oder jdoe@contoso.com haben, aber der Aktionsendpunkt erwartet den Empfang von jdoe@contoso.com im sub-Anspruch des Bearertokens.For example, a user could have both the john.doe@contoso.com or jdoe@contoso.com email address, but the action endpoint expects to receive jdoe@contoso.com in the sub claim of the bearer token. Indem Sie dieses Feld auf ["jdoe@contoso.com"] festlegen, verfügt der sub-Anspruch über die erwarteten E-Mail-Adresse.By setting this field to ["jdoe@contoso.com"], the sub claim will have the expected email address.
originator ZeichenfolgeString Erforderlich beim Senden über E-Mail, nicht anwendbar beim Senden über Connector.Required when sent via email, not applicable when sent via connector. MUSS für eine Aktion erfordernde E-Mail-Nachrichten auf die Anbieter-ID festgelegt werden, die vom Entwicklerdashboard für E-Mails mit Aktionen generiert wird.For actionable email, MUST be set to the provider ID generated by the Actionable Email Developer Dashboard.
summary ZeichenfolgeString Die summary-Eigenschaft wird in der Regel in der Listenansicht in Outlook angezeigt. Mit dieser Eigenschaft kann schnell ermittelt werden, worum es bei der Karte geht.The summary property is typically displayed in the list view in Outlook, as a way to quickly determine what the card is all about.

Fügen Sie immer eine Zusammenfassung ein.Do always include a summary.
Schreiben Sie keine Details in die Zusammenfassung. Eine Zusammenfassung für einen Twitter-Beitrag könnte zum Beispiel einfach „Neuer Tweet von @someuser“ sein, ohne dass der Inhalt des Tweets selbst erwähnt wird.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 ZeichenfolgeString Gibt eine benutzerdefinierte Markenfarbe für die Karte an. Die Farbe wird unaufdringlich angezeigt.Specifies a custom brand color for the card. The color will be displayed in a non-obtrusive manner.

Verwenden Sie themeColor, um Karten mit Ihrer Farbe zu versehen.Do use themeColor to brand cards to your color.
Es wird nicht empfohlen themeColor zu verwenden, um den Status anzugeben.Don't use themeColor to indicate status.
hideOriginalBody Boolescher WertBoolean Gilt nur für Karten in E-Mail-NachrichtenOnly applies to cards in email messages

Wenn dieser auf „true“ festgelegt wird, wird der HTML-Textkörper der Nachricht ausgeblendet. Dies ist sehr nützlich in Szenarien, in denen die Karte eine bessere oder nützlichere Darstellung des Inhalts ist als der HTML-Textkörper selbst. Dies ist insbesondere dann der Fall, wenn die Karte Aktionen enthält (siehe unten).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.)

In den folgenden Fällen sollten Sie in Betracht ziehen, den ursprünglichen HTML-Textkörper auszublenden:Consider hiding the original HTML body:
  • Wenn die Karte selbst alle Informationen enthält, die ein Benutzer benötigt.If the card itself contains all the information a user would need
  • Wenn der Inhalt der Karte identisch mit dem Inhalt des Textkörpers ist.If the content of the card is redundant with the content of the body
Schließen Sie immer einen ansprechenden HTML-Textkörper ein, auch wenn dieser ausgeblendet wird. Der HTML-Textkörper ist das Einzige, was ein E-Mail-Client, der keine Karten unterstützt, anzeigen kann. Außerdem werden beim Antworten auf oder beim Weiterleiten von E-Mails keine Karten eingeschlossen, nur der HTML-Textkörper.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.
Blenden Sie den Textkörper nicht aus, wenn er die auf der Karte dargestellten Informationen ergänzt. Der Textkörper der Genehmigung einer Spesenabrechnung könnte beispielsweise den Bericht detailliert beschreiben, wohingegen die Karte nur eine Schnellübersicht zusammen mit den Aktionen zum Genehmigen/Ablehnen bietet.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 ZeichenfolgeString Die title-Eigenschaft sollte an einer gut sichtbaren Stelle positioniert werden, ganz oben auf der Karte. Verwenden Sie diese, um den Inhalt der Karte derart vorzustellen, dass Benutzer sofort wissen, was sie erwartet.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.

Beispiele:Examples:
  • Tägliche NachrichtenDaily news
  • Neuer Fehler geöffnetNew bug opened
  • Aufgabe <name of task> zugewiesenTask <name of task> assigned
Halten Sie den Titel kurz (kein langer Satz).Do keep title short, don't make it a long sentence.
Erwähnen Sie den Namen der Entität, auf die im Titel verwiesen wird.Do mention the name of the entity being referenced in the title.
Verwenden Sie keine Hyperlinks (über Markdown) im Titel.Don't use hyperlinks (via Markdown) in the title.
text ZeichenfolgeString Die text-Eigenschaft sollte in einer normalen Schriftart unter dem Titel der Karte angezeigt werden. Verwenden Sie sie zum Anzeigen von Inhalten, z. B. die Beschreibung der Entität, auf die verwiesen wird, oder eine Zusammenfassung eines Artikels.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.

Verwenden Sie einfaches Markdown, z. B. fett oder kursiv, um Wörter hervorzuheben, sowie Links zu externen Ressourcen.Do use simple Markdown, such as bold or italics to emphasize words, and links to external resources.
Schließen Sie keine Aktionsaufrufe in der Texteigenschaft ein. Es muss möglich sein, dass Benutzer diese nicht lesen und dennoch wissen, worum es bei der Karte geht.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 von SectionArray of Section Eine Sammlung von Abschnitten, die auf der Karte enthalten sein sollen.A collection of sections to include in the card. Siehe AbschnittsfelderSee Section fields.
potentialAction Array von ActionsArray of Actions Eine Zusammenstellung von Aktionen, die auf dieser Karte aufgerufen werden können. Siehe Aktionen.A collection of actions that can be invoked on this card. See Actions.

AbschnittsfelderSection fields

FeldField TypType BeschreibungDescription
title ZeichenfolgeString Die title-Eigenschaft eines Abschnitts wird in einer Schriftart angezeigt, die auffällig ist, jedoch nicht so hervorsticht, wie der Titel der Karte. Damit soll der Abschnitt vorgestellt und sein Inhalt zusammengefasst werden, so wie die Titeleigenschaft der Karte die gesamte Karte zusammenfassen soll.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.

Halten Sie den Titel kurz (kein langer Satz).Do keep title short, don't make it a long sentence.
Erwähnen Sie den Namen der Entität, auf die im Titel verwiesen wird.Do mention the name of the entity being referenced in the title.
Verwenden Sie keine Hyperlinks (über Markdown) im Titel.Don't use hyperlinks (via Markdown) in the title.
startGroup Boolescher WertBoolean Wenn dieser auf true festgelegt ist, markiert die startGroup-Eigenschaft den Beginn einer logischen Gruppe von Informationen. Abschnitte, bei denen startGroup auf true festgelegt ist, werden visuell von vorherigen Kartenelementen getrennt. Outlook verwendet beispielsweise eine feine horizontale Trennungslinie.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

Verwenden Sie startGroup, um Abschnitte zu trennen, die unterschiedliche Objekte darstellen, z. B. mehrere Tweets in einem Digest.Do use startGroupto separate sections that represent different objects; for example, multiple tweets in a digest.
activityImage
activityTitle
activitySubtitle
activityText
ZeichenfolgeString Diese vier Eigenschaften bilden eine logische Gruppe. activityTitle, activitySubtitle und activityText werden neben activityImage angezeigt und verwenden ein Layout, das dem Formfaktor des Geräts entspricht, auf dem die Karte angezeigt wird. In Outlook im Web werden activityTitle, activitySubtitle und activityText unter Verwendung eines zweispaltigen Layouts beispielsweise rechts von activityImage angezeigt: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

Verwenden Sie die Aktivitätenfelder für folgende Szenarien:Use the activity fields for scenarios such as:
  • Jemand hat eine Aktion ausgeführtSomeone did something
    • Verwenden Sie activityImage, um das Bild dieser Person anzuzeigen.Use activityImage to display the picture of that person.
    • Verwenden Sie activityTitle, um die Aktion zusammenzufassen. Formulieren Sie dies kurz und prägnant.Use activityTitle to summarize what they did. Make it short and to the point.
    • Verwenden Sie activitySubtitle, um beispielsweise das Datum und die Uhrzeit der Aktion anzuzeigen, oder den Ziehpunkt der Person.Use activitySubtitle to show, for instance, the date and time the action was taken, or the person's handle.
      • activitySubtitle wird in einer nicht so auffälligen Schriftart angezeigt.activitySubtitle will be rendered in a more subdued font
      • Schließen Sie keine wichtigen Informationen ein.Don't include essential information
      • Schließen Sie keine ** Aktionsaufrufe ein.Don't** include calls to action
      • Vermeiden Sie Markdown-Formatierungen.Avoid Markdown formatting
    • Verwenden Sie activityText, um Details zu der Aktivität anzugeben.Use activityText to provide details about the activity.
      • Verwenden Sie einfaches Markdown, um Wörter oder Links zu externen Quellen hervorzuheben.Do use simple Markdown to emphasize words or link to external sources
      • Schließen Sie keine ** Aktionsaufrufe ein.Don't** include calls to action
  • Eine Zusammenfassung eines NachrichtenartikelsA news article abstract
    • Verwenden Sie activityImage, um das Bild anzuzeigen, das mit dem Artikel verknüpft ist.Use activityImage to display the picture associated with the article
    • Verwenden Sie activitySubtitle, um das Datum und die Uhrzeit der ursprünglichen Veröffentlichung des Artikels anzuzeigen.Use activitySubtitle to display the date and time the article was originally posted
    • Verwenden Sie activityText, um die tatsächliche Zusammenfassung anzuzeigen.Use activityText to display the actual abstract
heroImage ImageImage Verwenden Sie heroImage, um ein Bild als Herzstück der Karte zu verwenden. Bei einem Tweet, der ein Bild enthält, sollte dieses Bild vorne und mittig angezeigt werden: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 kann auch verwendet werden, um Ihrer Karte ein Banner hinzuzufügen, z. B. das Banner „TINYPulse – Engage“ unten.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 ZeichenfolgeString Die text-Eigenschaft des Abschnitts ist der text-Eigenschaft der Karte sehr ähnlich. Sie kann für den gleichen Zweck verwendet werden.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 von Name/Wert-PaarenArray of name/value pairs Fakten sind eine sehr wichtige Komponente eines Abschnitts. Sie enthalten häufig die Informationen, die dem Benutzer wirklich wichtig sind.Facts are a very important component of a section. They often contain the information that really matters to the user.

Fakten werden so angezeigt, dass sie schnell und effizient gelesen werden können. In Outlook im Web werden Fakten beispielsweise in einem zweispaltigen Layout präsentiert, wobei die Faktnamen in einer etwas auffälligeren Schriftart wiedergegeben werden: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

Es gibt viele Verwendungsmöglichkeiten für Fakten. Einige Szenarien:There are many uses for facts. Some scenarios:
  • Ein Fehler wurde erstelltA bug was created
    • Fehler-ID: 1234Bug ID: 1234
    • Geöffnet von: Anna LangeOpened by: Adele Vance
    • Zugewiesen an: Adrian WilskeAssigned to: Alex Darrow
  • Bericht zu AnwendungsverwendungApplication usage report
    • Name der Anwendung: Contoso CRM-AppApplication name: Contoso CRM App
    • Zeitraum: 1. August 2016 bis 30. September 2016Period: August 1, 2016 - September 30, 2016
    • Anzahl von Benutzern: 542Number of users: 542
    • Anzahl von Sitzungen: 2056Number of sessions: 2056
    • Durchschnittliche Besuchsdauer in der Anwendung: 76 SekundenAverage time spend in the application: 76 seconds
  • SpesengenehmigungExpense approval
    • Eingereicht von: Pradeep GuptaSubmitted by: Pradeep Gupta
    • Übermittelt am: 21. Oktober 2016Date submitted: October 21, 2016
    • Gesamtbetrag: 1.426,95 USDTotal amount: $1,426.95
Verwenden Sie Fakten, anstatt wichtige Informationen innerhalb der Texteigenschaft der Karte oder des Abschnitts einzubetten.Do use facts instead of embedding important information inside the text property of either the card or the section.
Halten Sie die Namen von Fakten kurz.Do keep fact names short.
Vermeiden Sie zu lange Faktenwerte.Avoid making fact values too long.
Vermeiden Sie die Verwendung von Markdown-Formatierungen sowohl für Faktnamen als auch -werte. Sorgen Sie dafür, dass Fakten wie beabsichtigt wiedergegeben werden, denn so haben sie die größte Wirkung.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.
Verwenden Sie Markdown jedoch nur für Links in Faktenwerten. Wenn ein Fakt zum Beispiel auf ein externes Dokument verweist, formatieren Sie den Wert dieses Fakts als Link zum Dokument.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.
Fügen Sie keine Fakten ohne echten Zweck hinzu. Fakten, die immer denselben Wert über alle Karten hinweg haben, sind nicht interessant und reine Platzverschwendung.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 von BildobjektenArray of Image objects Die images-Eigenschaft ermöglicht die Einbeziehung einer Fotogalerie innerhalb eines Abschnitts. Diese Fotogalerie wird immer in einer einfach zu nutzenden Weise angezeigt, unabhängig vom Formfaktor des Geräts, auf dem sie angezeigt wird. In Outlook im Web werden Bilder beispielsweise als horizontaler Streifen von Miniaturansichten mit Steuerelementen angezeigt, über die Sie einen Bildlauf durch die Sammlung durchführen können, wenn nicht alles auf den Bildschirm passt. Auf mobilen Geräten können Bilder als einzelne Miniaturansicht angezeigt werden, und der Benutzer hat die Möglichkeit, mit dem Finger durch die Sammlung zu blättern.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 von ActionsArray of Actions Eine Zusammenstellung von Aktionen, die in diesem Abschnitt aufgerufen werden können. Siehe Aktionen.A collection of actions that can be invoked on this section. See Actions.

BildobjektImage object

Definiert ein Bild, wie von der heroImage- und der images-Eigenschaft eines Abschnitts verwendet.Defines an image as used by the heroImage and images property of a section.

FeldField TypType BeschreibungDescription
image ZeichenfolgeString Die URL zum Bild.The URL to the image.
title ZeichenfolgeString Eine kurze Beschreibung des Bilds. In der Regel wird title in einer QuickInfo angezeigt, wenn der Benutzer den Mauszeiger über das Bild bewegt.A short description of the image. Typically, title is displayed in a tooltip as the user hovers their mouse over the image.

AktionenActions

Karten sind sehr leistungsstark dahingehend, dass Benutzer damit Aktionen schnell ausführen können, ohne den E-Mail-Client verlassen zu müssen. Beim Entwerfen von Karten empfiehlt es sich, diese mit Aktionen zu versehen, da dies die Bindung und Produktivität des Benutzers steigert.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.

Aktionen werden mithilfe der potentialAction-Eigenschaft angegeben, die sowohl auf der Karte selbst als auch in jedem Abschnitt verfügbar ist.Actions are specified using the potentialAction property which is available both on the card itself and on each section. Es gibt vier Typen von Aktionen:There are four types of actions:

Es kann maximal 4 Aktionen (unabhängig von ihrem Typ) in einer potentialAction-Sammlung geben.There can be a maximum of 4 actions (whatever their type) in a potentialAction collection.

  • Schließen Sie Aktionen ein, die die größte Wirkung für den Benutzer haben, z. B. die sich am häufigsten wiederholenden.Do include actions that will make the biggest impact for the end user, like the most repetitive ones.
  • Fügen Sie nicht 4 Aktionen hinzu, nur weil dies möglich ist. In vielen Fällen führen weniger Aktionen zu einem besseren Erlebnis.Don't add 4 actions just because you can. In many cases, fewer actions will lead to a better experience.
  • Gestalten Sie Ihre Karten nicht mit der Absicht, eine externe Anwendung zu ersetzen. Karten sollen eine Ergänzung zu solchen Anwendungen sein, kein Ersatz.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-AktionOpenUri action

Öffnet einen URI in einem separaten Browser oder in einer separaten App.Opens a URI in a separate browser or app.

Über Markdown können zwar Links erzielt werden, eine OpenUri-Aktion hat aber den Vorteil, dass Sie unterschiedliche URIs für unterschiedliche Betriebssysteme angeben können, sodass der Link auf mobilen Geräten in einer App geöffnet werden kann.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.

  • Erwägen Sie, eine OpenUri-Aktion anstelle eines Links in Markdown zu verwenden, wenn es für Ihre Benutzer einen klaren Vorteil bedeutet, wenn der Link auf ihrem mobilen Gerät in einer App geöffnet werden kann.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.
  • Schließen Sie mindestens eine OpenUri-Aktion mit ein, um die Entität in der externen App anzuzeigen, aus der sie stammt.Do include at least an OpenUri action to view the entity in the external app it comes from.
  • Platzieren Sie die OpenUri-Aktion in der potentialAction-Sammlung an letzter Stelle.Do make the OpenUri action the last one in the potentialAction collection.
FeldField TypType BeschreibungDescription
name ZeichenfolgeString Die name-Eigenschaft definiert den Text, der für die Aktion auf dem Bildschirm angezeigt wird.The name property defines the text that will be displayed on screen for the action.

Verwenden Sie Verben. Verwenden Sie z. B. „Fälligkeitsdatum festlegen“ anstelle von „Fälligkeitsdatum“ oder „Notiz hinzufügen“ anstelle von „Notiz“: In einigen Fällen funktioniert auch das Substantiv allein: „Kommentar“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"
Benennen Sie eine OpenUri-Aktion nicht derart, dass angedeutet wird, dass die Aktion direkt auf dem Client ausgeführt werden kann. Benennen Sie stattdessen die Aktion „Anzeigen in <Name der Website/App>“ oder „Öffnen in <Name der Website/App>“.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 ArrayArray Die targets-Eigenschaft ist eine Sammlung von Name/Wert-Paaren, die einen URI pro Zielbetriebssystem definiert.The targets property is a collection of name/value pairs that defines one URI per target operating system.

Unterstützte Betriebssystemwerte sind default, windows, iOS und android. Das default-Betriebssystem öffnet in den meisten Fällen einfach den URI in einem Webbrowser, unabhängig vom tatsächlichen Betriebssystem.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.

Beispiel für Zieleigenschaft: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-AktionHttpPOST action

Nimmt einen Aufruf an einen externen Webdienst vor.Makes a call to an external Web service.

Wenn eine HttpPOST-Aktion ausgeführt wird, wird eine POST-Anforderung an die URL im target-Feld gestellt, und der Zieldienst muss den Aufrufer authentifizieren. Dies kann auf vielfältige Weise erfolgen, auch über ein Limited Purpose Token, das in die Ziel-URL eingebettet ist. Weitere Informationen und Hilfe zur Auswahl des Sicherheitsmechanismus, der am besten für Ihr spezielles Szenario funktioniert, finden Sie unter Sicherheitsanforderungen für Nachrichten mit Aktionen.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.

FeldField TypType BeschreibungDescription
name ZeichenfolgeString Die name-Eigenschaft definiert den Text, der für die Aktion auf dem Bildschirm angezeigt wird.The name property defines the text that will be displayed on screen for the action.

Verwenden Sie Verben. Verwenden Sie z. B. „Fälligkeitsdatum festlegen“ anstelle von „Fälligkeitsdatum“ oder „Notiz hinzufügen“ anstelle von „Notiz“: In einigen Fällen funktioniert auch das Substantiv allein: „Kommentar“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 ZeichenfolgeString Definiert den URL-Endpunkt des Diensts, der die Aktion implementiert.Defines the URL endpoint of the service that implements the action.
headers Array von HeaderArray of Header Eine Sammlung von Header-Objekten, die eine Reihe von HTTP-Headern darstellen, die beim Senden der POST-Anforderung an die Ziel-URL ausgegeben werden. Weitere Informationen finden Sie unter Header.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 ZeichenfolgeString Der Textkörper der POST-Anforderung.The body of the POST request.
bodyContentType ZeichenfolgeString Die bodyContentType ist optional und gibt den MIME-Typ des Textkörpers in der POST-Anforderung an.The bodyContentType is optional and specifies the MIME type of the body in the POST request. Einige Dienste erfordern, dass ein Inhaltstyp angegeben wird.Some services require that a content type be specified. Gültige Werte sind application/json und application/x-www-form-urlencoded.Valid values are application/json and application/x-www-form-urlencoded. Falls nicht angegeben, wird application/json angenommen.If not specified, application/json is assumed.

Das Header-Objekt ist ein Name-Wert-Paar, das einen HTTP-Header darstellt.The Header object is a name/value pair that represents an HTTP header.

FeldField TypType BeschreibungDescription
name StringString Der HeadernameThe header name
value StringString Der HeaderwertThe header value

Melden der erfolgreichen oder fehlerhaften Ausführung einer AktionReporting an action's execution success or failure

HttpPOST-Aktionen können den CARD-ACTION-STATUS-HTTP-Header in ihrer Antwort enthalten. Dieser Header ist für Text vorgesehen, der das Ergebnis der Ausführung der Aktion angibt, unabhängig davon, ob diese erfolgreich war oder fehlgeschlagen ist.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.

Der Wert der Kopfzeile wird in konsistenter Weise in einem reservierten Bereich der Karte angezeigt. Er wird auch mit der Karte gespeichert, sodass er später angezeigt werden kann, damit Benutzer an die Aktionen erinnert werden können, die auf einer bestimmten Karte bereits ausgeführt wurden.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.

Tipp

Befolgen Sie diese Richtlinien beim Zurückgeben einer Antwort auf HttpPOST-Aktionen.Follow these guidelines when returning a response to HttpPOST actions.

  • Geben Sie den CARD-ACTION-STATUS-Header in Ihren Antworten zurück.Do return the CARD-ACTION-STATUS header in your responses.
  • Formulieren Sie die Nachricht in diesem Header so informativ und aussagekräftig wie möglich. Beispiel für die Aktion „Genehmigen“ in einer Spesenabrechnung:Do make the message in that header as informative and meaningful as possible. For instance, for an "approve" action on an expense report:
    • Wenn diese Aktion erfolgreich ausgeführt wurde, geben Sie nicht „Die Aktion war erfolgreich“ zurück, sondern besser „Die Spesenabrechnung wurde genehmigt“.In case of success, don't return "The action was successful", instead return "The expense was approved"
    • Wenn die Aktion nicht erfolgreich ausgeführt wurde, geben Sie nicht „Die Aktion ist fehlgeschlagen“ zurück, sondern besser „Die Spesenabrechnung kann derzeit nicht genehmigt werden. Versuchen Sie es später erneut“.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"
  • Erwähnen Sie nicht den Namen der Person, die die Aktion ausführt, und auch nicht die Uhrzeit der Aktion in Ihrem CARD-ACTION-STATUS-Header. Diese beiden Informationsstücke werden automatisch für Sie hinzugefügt und auf konsistente Art und Weise angezeigt.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.

AktualisierungskartenRefresh cards

Aktualisierungskarten bietet eine sehr leistungsstarke Methode, mit der HttpPOST-Aktionen die Karte schnell vollständig aktualisieren können, wenn die Aktion erfolgreich abgeschlossen wird. Es gibt viele Szenarien, die von der Aktualisierungskarten profitieren: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:

  • Genehmigungsszenario (z.B. Spesenabrechnung)Approval scenario (e.g. expense report)
    • Nachdem die Anforderung genehmigt oder abgelehnt wurde, wird die Karte so aktualisiert, dass die Schaltflächen zum Genehmigen/Ablehnen entfernt werden, und der Inhalt wird so aktualisiert, dass klar wird, dass die Anforderung genehmigt oder abgelehnt wurde.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
  • AufgabenstatusTask status
    • Wenn eine für eine Aufgabe eine Aktion ausgeführt wird, z. B. das Festlegen eines Fälligkeitsdatums, wird die Karte so aktualisiert, dass das aktualisierte Fälligkeitsdatum in den Fakten erscheint.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
  • UmfrageSurvey
    • Nachdem die Frage beantwortet wurde, wird die Karte folgendermaßen aktualisiert:Once the question has been answered, the card is refreshed so:
      • Der Benutzer kann nicht mehr antworten.It no longer allows the user to respond
      • Neben der tatsächlichen Antwort des Benutzers wird ein aktualisierter Status angezeigt, z. B. „Vielen Dank für Ihre Teilnahme an dieser Umfrage“.It shows updated status, like "Thanks for responding to this survey" alongside the user's actual response
      • Möglicherweise wird eine neue OpenUri-Aktion eingeschlossen, über die der Benutzer die Umfrage online einsehen kann.Potentially include a new OpenUri action that allows the user to consult the survey online

Ein Dienst muss folgendes ausführen, um eine Karte als Ergebnis einer HttpPOST-Aktion zu aktualisieren:To refresh a card as a result of an HttpPOST action, a service needs to do the following:

  • Er muss die JSON-Nutzlast der neuen Karte in den Textkörper der Antwort an die empfangene HTTP-POST-Anforderung einschließen.Include the JSON payload of the new card in the body of the response to the HTTP POST request it received.
  • Der CARD-UPDATE-IN-BODY: true-HTTP-Header muss der Antwort hinzugefügt werden, damit der empfangende Client weiß, dass er den Antworttext analysieren und eine neue Karte extrahieren soll (um eine unnötige Verarbeitung zu vermeiden, wenn keine Aktualisierungskarte enthalten ist).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.)

Tipp

Befolgen Sie diese Richtlinien beim Zurückgeben von Aktualisierungskarten.Follow these guidelines when returning refresh cards.

  • Verwenden Sie Aktualisierungskarten für Aktionen, die nur ein einziges Mal ausgeführt werden können. In diesen Fällen würde die Aktualisierungskarte keine Aktion enthalten, die nicht mehr ausgeführt werden kann.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
  • Verwenden Sie Aktualisierungskarten für Aktionen, die den Status der Entität ändern, für die sie ausgeführt werden. In diesen Fällen sollte die Aktualisierungskarte die aktualisierten Informationen zu der Entität enthalten und MÖGLICHERWEISE den Satz von Aktionen ändern, die durchgeführt werden können.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
  • Verwenden Sie Aktualisierungskarten nicht, um eine Unterhaltung mit dem Benutzer zu führen. Verwenden Sie z. B. keine Aktualisierungskarten für einen „Assistenten“ mit mehreren Schritten.Don't use refresh cards to lead a conversation with the user. For instance, don't use refresh cards for a multi-step "wizard"
  • Schließen Sie mindestens eine OpenUri-Aktion mit ein, um die Entität in der externen App anzuzeigen, aus der sie stammt.Do include at least an OpenUri action to view the entity in the external app it comes from.

ActionCard-AktionActionCard action

Stellt eine zusätzliche Benutzeroberfläche, die eine oder mehrere Eingaben enthält, zusammen mit verbundenen Aktionen dar, die vom Typ OpenUri oder HttpPOST sein können.Presents additional UI that contains one or more Inputs, along with associated actions that can be either OpenUri or HttpPOST types.

Verwenden Sie eine ActionCard-Aktion, wenn für eine Aktion zusätzliche Eingaben vom Benutzer erforderlich sind. Einige Szenarien:Do use an ActionCard action if an action requires additional input from the user. Some scenarios:

  • Teilnehmen an einer UmfrageResponding to a survey
  • Hinzufügen eines Kommentars zu einem FehlerAdding a comment to a bug
  • Angeben einer Rechtfertigung für die Ablehnung einer SpesenabrechnungProviding justification for declining an expense report

Standardmäßig wird eine ActionCard-Aktion als eine Schaltfläche oder ein Link in der Benutzeroberfläche der Karte dargestellt. Nach Mausklick zeigt die entsprechende Schaltfläche ein zusätzliches Stück Benutzeroberfläche an, das die Eingaben und Aktionen enthält, die in der Aktionskarte definiert sind.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.

Wenn es eine einzige ActionCard-Aktion in einer potentialAction-Sammlung gibt, wird diese Aktion in Outlook „vorab erweitert“ dargestellt, d.h. die Eingaben und Aktionen sind sofort sichtbar.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.

FeldField TypType BeschreibungDescription
name ZeichenfolgeString Die name-Eigenschaft definiert den Text, der für die Aktion auf dem Bildschirm angezeigt wird.The name property defines the text that will be displayed on screen for the action.

Verwenden Sie Verben. Verwenden Sie z. B. „Fälligkeitsdatum festlegen“ anstelle von „Fälligkeitsdatum“ oder „Notiz hinzufügen“ anstelle von „Notiz“: In einigen Fällen funktioniert auch das Substantiv allein: „Kommentar“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 Array von InputsArray of Inputs Die inputs-Eigenschaft definiert die unterschiedlichen Eingaben, die in der Benutzeroberfläche der Aktionskarte angezeigt werden. Siehe Eingaben.The inputs property defines the various inputs that will be displayed in the action card's UI. See Inputs
actions Array von ActionsArray of Actions Die actions-Eigenschaft ist ein Array von Action-Objekten, die vom Typ OpenUri oder HttpPOST sein können. Die actions-Eigenschaft einer ActionCard-Aktion kann keine andere ActionCard-Aktion enthalten.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.

BeispielExample

{
  "@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}}"
    }
  ]
}

EingängeInputs

Drei Arten von Eingaben werden unterstützt: TextInput, DateInput und MultichoiceInput.Three types of inputs are supported: TextInput, DateInput, and MultichoiceInput.

Allgemeine FelderCommon fields

Die folgenden Felder gelten für alle Eingabetypen.The following fields are common to all input types.

FeldField TypType BeschreibungDescription
id ZeichenfolgeString Die Eingabe wird eindeutig identifiziert, sodass in der URL oder im Textkörper einer HttpPOST-Aktion darauf verwiesen werden kann. Weitere Informationen finden Sie unter Ersetzen des Eingabewerts.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 Gibt an, ob Benutzer einen Wert eingeben müssen, bevor sie eine Aktion ausführen können, die den Wert der Eingabe als Parameter verwenden würde.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.

Fordern Sie eine Eingab, wenn Benutzer einen Wert eingeben müssen.Do make an input required if users MUST provide a value.
Ziehen Sie in Betracht, eine Eingabe zu erfordern, wenn ihr Wert komplementär zu der einer anderen Eingabe ist. Sie könnten z. B. eine Frage einer Umfrage mit einer Mehrfachauswahl definieren, die lautet „Wie zufrieden sind Sie mit Ihrem Auto?“. Darauf folgt „Bitte erklären Sie Ihre Antwort“ als freier Text. Bitte beachten Sie, dass es einigen Benutzern möglicherweise nicht gefällt, dass sie gezwungen werden, solche Erklärungen abzugeben. Es kann sein, dass diese daher überhaupt nicht an der Umfrage teilnehmen.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.
Vergewissern Sie sich, dass Benutzer wissen, welche Eingaben erforderlich sind. Fügen Sie eine Beschriftung in der title-Eigenschaft der Eingabe ein. Zum Beispiel Comment (optional) oder 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 ZeichenfolgeString Definiert einen Titel für die Eingabe.Defines a title for the input.
value ZeichenfolgeString Definiert den Anfangswert der Eingabe. Bei Eingaben mit mehreren Auswahlmöglichkeiten muss der Wert gleich der value-Eigenschaft einer der Auswahlmöglichkeiten der Eingabe sein.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

Verwenden Sie diesen Eingabetyp, wenn Benutzer freien Text eingeben sollen, z. B. als Antwort auf eine Frage einer Umfrage.Use this input type when you need users to provide free text, such as the response to a survey question.

FeldField TypType BeschreibungDescription
isMultiline Boolescher WertBoolean Gibt an, ob die Texteingabe mehrere Textzeilen akzeptieren soll.Indicates whether the text input should accept multiple lines of text.
maxLength ZahlNumber Gibt die maximale Anzahl von Zeichen an, die eingegeben werden können.Indicates the maximum number of characters that can be entered.

BeispielExample

{
  "@type": "TextInput",
  "id": "comment",
  "isMultiline": true,
  "title": "Input's title property"
}
DateInputDateInput

Verwenden Sie diesen Eingabetyp, wenn Benutzer ein Datum und/oder eine Uhrzeit eingeben sollen, z. B. für das Fälligkeitsdatum einer Aufgabe.Use this input type when you need users to provide a date and or a time, such as for a task's due date.

FeldField TypType BeschreibungDescription
includeTime Boolescher WertBoolean Gibt an, ob bei der Datumseingabe die Auswahl einer Uhrzeit zusätzlich zum Datum möglich sein soll.Indicates whether the date input should allow for the selection of a time in addition to the date.

BeispielExample

{
  "@type": "DateInput",
  "id": "dueDate",
  "title": "Input's title property"
}
MultichoiceInputMultichoiceInput

Verwenden Sie diesen Eingabetyp, wenn Benutzer eine Auswahl aus einer Liste vordefinierter Auswahlmöglichkeiten treffen sollen, z. B. ein Fehlerstatus, ja/nein/vielleicht usw.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.

FeldField TypType BeschreibungDescription
choices Array von Name/Wert-PaarenArray of name/value pairs Definiert die Werte, die für die Eingabe mit Mehrfachauswahl ausgewählt werden können.Defines the values that can be selected for the multichoice input.
isMultiSelect Boolescher WertBoolean Wenn dieser auf true festgelegt ist, gibt dies an, dass der Benutzer mehrere Optionen auswählen kann. Die angegebenen Auswahlmöglichkeiten werden als eine Liste von Kontrollkästchen angezeigt. Der Standardwert ist false.If 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 Zeichenfolge (normal(Standard oder expanded))String (normal(default or expanded)) Wenn isMultiSelect false ist, wird die Hostanwendung durch Festlegen der style-Eigenschaft auf expanded angewiesen, alle Auswahlmöglichkeiten auszuprobieren und auf dem Bildschirm anzuzeigen, in der Regel mithilfe einer Reihe von Optionsfeldern.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

Beispiel (komprimiert)Example (compact)

{
  "@type": "MultichoiceInput",
  "id": "list",
  "title": "Pick an option",
  "choices": [
    { "display": "Choice 1", "value": "1" },
    { "display": "Choice 2", "value": "2" },
    { "display": "Choice 3", "value": "3" }
  ]
}

Beispiel (Mehrfachauswahl)Example (multi-selection)

{
  "@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" }
  ]
}

Beispiel (erweitert)Example (expanded)

{
  "@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" }
  ]
}

Ersetzen des EingabewertsInput value substitution

Auf den Wert einer Eingabe kann in einer URL einer ViewAction- oder HttpPOST-Aktion verwiesen werden. Es kann auch im Textkörper einer HttpPOST-Aktion darauf verwiesen werden. Wenn auf einen Eingabewert verwiesen wird, wird dieser, kurz bevor die Aktion ausgeführt wird, durch den tatsächlichen Wert der Eingabe ersetzt.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.

Verwenden Sie das folgende Format, um auf den Wert einer Eingabe zu verweisen:To reference an input's value, use the following format:

{{<id of input>.value}}

BeispielExample

{
  "@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 AktionInvokeAddInCommand action

Öffnet einen Aufgabenbereich für ein Outlook-Add-In.Opens an Outlook add-in taskpane. Wenn das Add-In nicht installiert ist, wird der Benutzer aufgefordert, das Add-In mit einem einzigen Mausklick zu installieren.If the add-in is not installed, the user is prompted to install the add-in with a single click.

Wenn eine InvokeAddInCommand-Aktion ausgeführt wird, wird von Outlook zuerst überprüft, ob das angeforderte Add-In installiert und für den Benutzer aktiviert ist.When an InvokeAddInCommand action is executed, Outlook first checks if the requested add-in is installed and turned on for the user. Wenn nicht, wird der Benutzer benachrichtigt, dass die Aktion das Add-In erfordert, und kann das Add-In mit einem einzigen Mausklick installieren und aktivieren.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 öffnet den angeforderten Aufgabenbereich und macht ggf. den von der Aktion angegebenen Initialisierungskontext für das Add-In verfügbar.Outlook opens the requested taskpane, making any initialization context specified by the action available to the add-in.

Weitere Informationen finden Sie unter Aufrufen eines Outlook-Add-Ins in einer Aktion erfordernden Nachricht.For more information, see Invoke an Outlook add-in from an actionable message.

FeldField TypType BeschreibungDescription
name ZeichenfolgeString Die name-Eigenschaft definiert den Text, der für die Aktion auf dem Bildschirm angezeigt wird.The name property defines the text that will be displayed on screen for the action.

Verwenden Sie Verben. Verwenden Sie z. B. „Fälligkeitsdatum festlegen“ anstelle von „Fälligkeitsdatum“ oder „Notiz hinzufügen“ anstelle von „Notiz“: In einigen Fällen funktioniert auch das Substantiv allein: „Kommentar“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 Gibt die Add-In-ID des erforderlichen-Add-Ins an.Specifies the add-in ID of the required add-in. Die Add-In-ID befindet sich im Id-Element im Manifest des Add-Ins.The add-in ID is found in the Id element in the add-in's manifest.
desktopCommandId StringString Gibt die ID der Add-In-Befehlsschaltfläche an, die den erforderlichen Aufgabenbereich öffnet.Specifies the ID of the add-in command button that opens the required taskpane. Die ID der Befehlsschaltfläche befindet sich im id-Attribut des Control-Elements, das die Schaltfläche im Manifest des Add-Ins definiert.The command button ID is found in the id attribute of the Control element that defines the button in the add-in's manifest. Das angegebene Control-Element MUSS innerhalb eines MessageReadCommandSurface-Erweiterungspunkts definiert und vom Typ Button sein, und die Action des Steuerelements muss vom Typ ShowTaskPane sein.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.Optional. Entwickler können jedes gültige JSON-Objekt in diesem Feld angeben.Developers may specify any valid JSON object in this field. Der Wert wird in eine Zeichenfolge serialisiert und für das Add-In verfügbar gemacht, wenn die Aktion ausgeführt wird.The value is serialized into a string and made available to the add-in when the action is executed. Dadurch kann die Aktion Initialisierungsdaten an das Add-In übergeben.This allows the action to pass initialization data to the add-in.

BeispielExample

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

KartenbeispieleCard Examples

TrelloTrello

Karte wird in einer Liste erstellt:Card is created in a list:

Eine Beispiel-Trello-Karte

Diese Karte wird folgendermaßen erstellt:Here is how that card is built:

Diagramm, in dem die Teile einer Beispiel-Trello-Karte erläutert werden

Hier sehen Sie dieselbe Karte, bei der nun die Aktion Kommentar hinzufügen erweitert ist:Here's the same card with the Add a comment action expanded:

Eine Beispiel-Trello-Karte mit einer erweiterten Aktionskarte

Die Aktion Kommentar hinzufügen wird folgendermaßen erstellt:Here's how the Add a comment action is built:

Diagramm, in dem die Teile einer Beispiel-Trello-Karte mit einer erweiterten Aktionskarte erläutert werden

JSONJSON

{
  "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

Hier sehen Sie ein Beispiel für eine Twitter-Digestkarte:Here's an example of a Twitter digest card:

Ein Beispiel für eine Twitter-Digestkarte

Diese Karte wird folgendermaßen erstellt:Here's how that card is built:

Diagramm, in dem die Teile einer beispielhaften Twitter-Digestkarte erläutert werden

JSONJSON

{
  "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..."
    }
  ]
}