Referenz zu Nachrichtenkarten mit Aktionen

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.

Karten-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.

Richtlinien für den Entwurf

Textformatierung

Alle Textfelder in einer Karte und deren Bereiche können mithilfe von Markdown formatiert werden. Wir unterstützen einfaches Markdown.

Wichtig

Da alle Felder als Markdown verarbeitet werden, müssen Sie Sonderzeichen von Markdown bei Bedarf mit Escapezeichen versehen (z. B. * oder #).

Effekt Markdown
Kursiv *Italic*
Fett **Bold**
Fett Kursiv ***Bold Italic***
Durchgestrichen ~~Strikethrough~~
Links [Microsoft](https://www.microsoft.com)
Überschriften (<h1> bis <h6> # Heading bis ###### Heading
Aufzählungen * List item oder - List item

Tipp

Befolgen Sie diese Richtlinien beim Formatieren von Textfeldern.

  • Verwenden Sie Markdown zum Formatieren von Text.
  • Verwenden Sie in Ihren Karten kein HTML-Markup. HTML wird ignoriert und als reiner Text behandelt.

Mithilfe von Abschnitten

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.

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“.

Tipp

Befolgen Sie diese Richtlinien bei der Planung des Layouts Ihrer Karte.

  • Verwenden Sie Abschnitte, um Daten logisch zu gruppieren.
  • 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.
  • 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.
  • Für Digest-ähnliche Karten sollten Sie das Hinzufügen der Aktion „Vollständigen Digest anzeigen“ am Ende der Karte hinzufügen.

Kartenfelder

Feld Typ Beschreibung
@type Zeichenfolge Erforderlich. Muss auf MessageCard festgelegt werden.
@context Zeichenfolge Erforderlich. Muss auf http://schema.org/extensions festgelegt werden.
correlationId UUID Die correlationId-Eigenschaft vereinfacht das Auffinden von Protokollen zur Behandlung von Problemen. Es wird empfohlen, beim Senden einer Aktion erfordernden Karte Ihren Service festzulegen und in dieser Eigenschaft eine eindeutige UUID zu protokollieren.

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. Card-Correlation-Id enthält denselben Wert wie die correlationId-Eigenschaft auf der Karte. Action-Request-Id ist eine eindeutige UUID, die von Office 365 zum Auffinden einer bestimmten von einem Benutzer ausgeführten Aktion generiert wird. Der Dienst sollte beim Empfang von POST-Anforderungen für Aktionen beide Werte protokollieren.
originator String Erforderlich beim Senden über E-Mail, nicht anwendbar beim Senden über 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.
summary Zeichenfolge 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.

Fügen Sie immer eine Zusammenfassung ein.
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.
themeColor Zeichenfolge Gibt eine benutzerdefinierte Markenfarbe für die Karte an. Die Farbe wird unaufdringlich angezeigt.

Verwenden Sie themeColor, um Karten mit Ihrer Farbe zu versehen.
Es wird nicht empfohlen themeColor zu verwenden, um den Status anzugeben.
hideOriginalBody Boolescher Wert Gilt nur für Karten in E-Mail-Nachrichten

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).

In den folgenden Fällen sollten Sie in Betracht ziehen, den ursprünglichen HTML-Textkörper auszublenden:
  • Wenn die Karte selbst alle Informationen enthält, die ein Benutzer benötigt.
  • Wenn der Inhalt der Karte identisch mit dem Inhalt des Textkörpers ist.
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.
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.
title Zeichenfolge 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.

Beispiele:
  • Tägliche Nachrichten
  • Neuer Fehler geöffnet
  • Aufgabe <name of task> zugewiesen
Halten Sie den Titel kurz (kein langer Satz).
Erwähnen Sie den Namen der Entität, auf die im Titel verwiesen wird.
Verwenden Sie keine Hyperlinks (über Markdown) im Titel.
text Zeichenfolge 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.

Verwenden Sie einfaches Markdown, z. B. fett oder kursiv, um Wörter hervorzuheben, sowie Links zu externen Ressourcen.
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.
potentialAction Array von Actions Eine Zusammenstellung von Aktionen, die auf dieser Karte aufgerufen werden können. Siehe Aktionen.

Abschnittsfelder

Feld Typ Beschreibung
title Zeichenfolge 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.

Halten Sie den Titel kurz (kein langer Satz).
Erwähnen Sie den Namen der Entität, auf die im Titel verwiesen wird.
Verwenden Sie keine Hyperlinks (über Markdown) im Titel.
startGroup Boolescher Wert 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.

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.
activityImage
activityTitle
activitySubtitle
activityText
Zeichenfolge 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:

An example activity layout

Verwenden Sie die Aktivitätenfelder für folgende Szenarien:
  • Jemand hat eine Aktion ausgeführt
    • Verwenden Sie activityImage, um das Bild dieser Person anzuzeigen.
    • Verwenden Sie activityTitle, um die Aktion zusammenzufassen. Formulieren Sie dies kurz und prägnant.
    • Verwenden Sie activitySubtitle, um beispielsweise das Datum und die Uhrzeit der Aktion anzuzeigen, oder den Ziehpunkt der Person.
      • activitySubtitle wird in einer nicht so auffälligen Schriftart angezeigt.
      • Schließen Sie keine wichtigen Informationen ein.
      • Schließen Sie keine ** Aktionsaufrufe ein.
      • Vermeiden Sie** Markdown-Formatierungen.
    • Verwenden Sie activityText, um Details zu der Aktivität anzugeben.
      • Verwenden Sie einfaches Markdown, um Wörter oder Links zu externen Quellen hervorzuheben.
      • **Schließen Sie keine ** Aktionsaufrufe ein.
  • Eine Zusammenfassung eines Nachrichtenartikels
    • Verwenden Sie activityImage, um das Bild anzuzeigen, das mit dem Artikel verknüpft ist.
    • Verwenden Sie activitySubtitle, um das Datum und die Uhrzeit der ursprünglichen Veröffentlichung des Artikels anzuzeigen.
    • Verwenden Sie activityText, um die tatsächliche Zusammenfassung anzuzeigen.
heroImage Image 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:

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.

An example of using a heroImage to create a banner
text Zeichenfolge Die text-Eigenschaft des Abschnitts ist der text-Eigenschaft der Karte sehr ähnlich. Sie kann für den gleichen Zweck verwendet werden.
facts Array von Name/Wert-Paaren Fakten sind eine sehr wichtige Komponente eines Abschnitts. Sie enthalten häufig die Informationen, die dem Benutzer wirklich wichtig sind.

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:

An example of facts being displayed

Es gibt viele Verwendungsmöglichkeiten für Fakten. Einige Szenarien:
  • Ein Fehler wurde erstellt
    • Fehler-ID: 1234
    • Geöffnet von: Anna Lange
    • Zugewiesen an: Adrian Wilske
  • Bericht zu Anwendungsverwendung
    • Name der Anwendung: Contoso CRM-App
    • Zeitraum: 1. August 2016 bis 30. September 2016
    • Anzahl von Benutzern: 542
    • Anzahl von Sitzungen: 2056
    • Durchschnittliche Besuchsdauer in der Anwendung: 76 Sekunden
  • Spesengenehmigung
    • Eingereicht von: Pradeep Gupta
    • Übermittelt am: 21. Oktober 2016
    • Gesamtbetrag: 1.426,95 USD
Verwenden Sie Fakten, anstatt wichtige Informationen innerhalb der Texteigenschaft der Karte oder des Abschnitts einzubetten.
Halten Sie die Namen von Fakten kurz.
Vermeiden Sie zu lange Faktenwerte.
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.
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.
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.
images Array von Bildobjekten 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.
potentialAction Array von Actions Eine Zusammenstellung von Aktionen, die in diesem Abschnitt aufgerufen werden können. Siehe Aktionen.

Bildobjekt

Definiert ein Bild, wie von der heroImage- und der images-Eigenschaft eines Abschnitts verwendet.

Feld Typ Beschreibung
image Zeichenfolge Die URL zum Bild.
title Zeichenfolge Eine kurze Beschreibung des Bilds. In der Regel wird title in einer QuickInfo angezeigt, wenn der Benutzer den Mauszeiger über das Bild bewegt.

Aktionen

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.

Aktionen werden mithilfe der potentialAction-Eigenschaft angegeben, die sowohl auf der Karte selbst als auch in jedem Abschnitt verfügbar ist. Es gibt vier Typen von Aktionen:

Es kann maximal 4 Aktionen (unabhängig von ihrem Typ) in einer potentialAction-Sammlung geben.

  • Schließen Sie Aktionen ein, die die größte Wirkung für den Benutzer haben, z. B. die sich am häufigsten wiederholenden.
  • 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.
  • Gestalten Sie Ihre Karten nicht mit der Absicht, eine externe Anwendung zu ersetzen. Karten sollen eine Ergänzung zu solchen Anwendungen sein, kein Ersatz.

OpenUri-Aktion

Öffnet einen URI in einem separaten Browser oder in einer separaten 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.

  • 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.
  • Schließen Sie mindestens eine OpenUri-Aktion mit ein, um die Entität in der externen App anzuzeigen, aus der sie stammt.
  • Platzieren Sie die OpenUri-Aktion in der potentialAction-Sammlung an letzter Stelle.
Feld Typ Beschreibung
name Zeichenfolge Die name-Eigenschaft definiert den Text, der für die Aktion auf dem Bildschirm angezeigt wird.

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“
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>“.
targets Array Die targets-Eigenschaft ist eine Sammlung von Name/Wert-Paaren, die einen URI pro Zielbetriebssystem definiert.

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.

Beispiel für Zieleigenschaft:
"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-Aktion

Nimmt einen Aufruf an einen externen Webdienst vor.

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.

Feld Typ Beschreibung
name Zeichenfolge Die name-Eigenschaft definiert den Text, der für die Aktion auf dem Bildschirm angezeigt wird.

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“
target Zeichenfolge Definiert den URL-Endpunkt des Diensts, der die Aktion implementiert.
headers Array von 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.
body Zeichenfolge Der Textkörper der POST-Anforderung.
bodyContentType Zeichenfolge Die bodyContentType ist optional und gibt den MIME-Typ des Textkörpers in der POST-Anforderung an. Einige Dienste erfordern, dass ein Inhaltstyp angegeben wird. Gültige Werte sind application/json und application/x-www-form-urlencoded. Falls nicht angegeben, wird application/json angenommen.

Das Header-Objekt ist ein Name-Wert-Paar, das einen HTTP-Header darstellt.

Feld Typ Beschreibung
name String Der Headername
value String Der Headerwert

Melden der erfolgreichen oder fehlerhaften Ausführung einer Aktion

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.

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.

Tipp

Befolgen Sie diese Richtlinien beim Zurückgeben einer Antwort auf HttpPOST-Aktionen.

  • Geben Sie den CARD-ACTION-STATUS-Header in Ihren Antworten zurück.
  • Formulieren Sie die Nachricht in diesem Header so informativ und aussagekräftig wie möglich. Beispiel für die Aktion „Genehmigen“ in einer Spesenabrechnung:
    • Wenn diese Aktion erfolgreich ausgeführt wurde, geben Sie nicht „Die Aktion war erfolgreich“ zurück, sondern besser „Die Spesenabrechnung wurde genehmigt“.
    • 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“.
  • 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.

Aktualisierungskarten

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:

  • Genehmigungsszenario (z.B. Spesenabrechnung)
    • 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.
  • Aufgabenstatus
    • 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.
  • Umfrage
    • Nachdem die Frage beantwortet wurde, wird die Karte folgendermaßen aktualisiert:
      • Der Benutzer kann nicht mehr antworten.
      • Neben der tatsächlichen Antwort des Benutzers wird ein aktualisierter Status angezeigt, z. B. „Vielen Dank für Ihre Teilnahme an dieser Umfrage“.
      • Möglicherweise wird eine neue OpenUri-Aktion eingeschlossen, über die der Benutzer die Umfrage online einsehen kann.

Ein Dienst muss folgendes ausführen, um eine Karte als Ergebnis einer HttpPOST-Aktion zu aktualisieren:

  • Er muss die JSON-Nutzlast der neuen Karte in den Textkörper der Antwort an die empfangene HTTP-POST-Anforderung einschließen.
  • 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).

Tipp

Befolgen Sie diese Richtlinien beim Zurückgeben von Aktualisierungskarten.

  • 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.
  • 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.
  • 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.
  • Schließen Sie mindestens eine OpenUri-Aktion mit ein, um die Entität in der externen App anzuzeigen, aus der sie stammt.

ActionCard-Aktion

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.

Verwenden Sie eine ActionCard-Aktion, wenn für eine Aktion zusätzliche Eingaben vom Benutzer erforderlich sind. Einige Szenarien:

  • Teilnehmen an einer Umfrage
  • Hinzufügen eines Kommentars zu einem Fehler
  • Angeben einer Rechtfertigung für die Ablehnung einer Spesenabrechnung

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.

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.

Feld Typ Beschreibung
name Zeichenfolge Die name-Eigenschaft definiert den Text, der für die Aktion auf dem Bildschirm angezeigt wird.

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“
inputs Array von Inputs Die inputs-Eigenschaft definiert die unterschiedlichen Eingaben, die in der Benutzeroberfläche der Aktionskarte angezeigt werden. Siehe Eingaben.
actions Array von 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.

Beispiel

{
  "@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änge

Drei Arten von Eingaben werden unterstützt: TextInput, DateInput und MultichoiceInput.

Allgemeine Felder

Die folgenden Felder gelten für alle Eingabetypen.

Feld Typ Beschreibung
id Zeichenfolge 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.
isRequired Boolean 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.

Fordern Sie eine Eingab, wenn Benutzer einen Wert eingeben müssen.
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.
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).
title Zeichenfolge Definiert einen Titel für die Eingabe.
value Zeichenfolge 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.
TextInput

Verwenden Sie diesen Eingabetyp, wenn Benutzer freien Text eingeben sollen, z. B. als Antwort auf eine Frage einer Umfrage.

Feld Typ Beschreibung
isMultiline Boolescher Wert Gibt an, ob die Texteingabe mehrere Textzeilen akzeptieren soll.
maxLength Zahl Gibt die maximale Anzahl von Zeichen an, die eingegeben werden können.

Beispiel

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

Verwenden Sie diesen Eingabetyp, wenn Benutzer ein Datum und/oder eine Uhrzeit eingeben sollen, z. B. für das Fälligkeitsdatum einer Aufgabe.

Feld Typ Beschreibung
includeTime Boolescher Wert Gibt an, ob bei der Datumseingabe die Auswahl einer Uhrzeit zusätzlich zum Datum möglich sein soll.

Beispiel

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

Verwenden Sie diesen Eingabetyp, wenn Benutzer eine Auswahl aus einer Liste vordefinierter Auswahlmöglichkeiten treffen sollen, z. B. ein Fehlerstatus, ja/nein/vielleicht usw.

Feld Typ Beschreibung
choices Array von Name/Wert-Paaren Definiert die Werte, die für die Eingabe mit Mehrfachauswahl ausgewählt werden können.
isMultiSelect Boolescher Wert 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.

An example multi-selection input
style Zeichenfolge (normal(Standard oder 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.

An example expanded input

Beispiel (komprimiert)

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

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

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

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.

Verwenden Sie das folgende Format, um auf den Wert einer Eingabe zu verweisen:

{{<id of input>.value}}

Beispiel

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

Öffnet einen Aufgabenbereich für ein Outlook-Add-In. Wenn das Add-In nicht installiert ist, wird der Benutzer aufgefordert, das Add-In mit einem einzigen Mausklick zu installieren.

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. 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. Outlook öffnet den angeforderten Aufgabenbereich und macht ggf. den von der Aktion angegebenen Initialisierungskontext für das Add-In verfügbar.

Weitere Informationen finden Sie unter Aufrufen eines Outlook-Add-Ins in einer Aktion erfordernden Nachricht.

Feld Typ Beschreibung
name Zeichenfolge Die name-Eigenschaft definiert den Text, der für die Aktion auf dem Bildschirm angezeigt wird.

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“
addInId UUID Gibt die Add-In-ID des erforderlichen-Add-Ins an. Die Add-In-ID befindet sich im Id-Element im Manifest des Add-Ins.
dekstopCommandId String Gibt die ID der Add-In-Befehlsschaltfläche an, die den erforderlichen Aufgabenbereich öffnet. Die ID der Befehlsschaltfläche befindet sich im id-Attribut des Control-Elements, das die Schaltfläche im Manifest des Add-Ins definiert. 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.
initializationContext Object Optional. Entwickler können jedes gültige JSON-Objekt in diesem Feld angeben. Der Wert wird in eine Zeichenfolge serialisiert und für das Add-In verfügbar gemacht, wenn die Aktion ausgeführt wird. Dadurch kann die Aktion Initialisierungsdaten an das Add-In übergeben.

Beispiel

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

Kartenbeispiele

Trello

Karte wird in einer Liste erstellt:

Eine Beispiel-Trello-Karte

Diese Karte wird folgendermaßen erstellt:

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:

Eine Beispiel-Trello-Karte mit einer erweiterten Aktionskarte

Die Aktion Kommentar hinzufügen wird folgendermaßen erstellt:

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

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

Twitter

Hier sehen Sie ein Beispiel für eine Twitter-Digestkarte:

Ein Beispiel für eine Twitter-Digestkarte

Diese Karte wird folgendermaßen erstellt:

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

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