Entwerfen von Aktion erfordernden Nachrichtenkarten in Outlook mit dem adaptiven Kartenformat

  • Artikel

Wichtig

Das Onboarding von neuen Anbietern für aktionenfähige Nachrichten im Global-Bereich wird aufgrund von Dienstupgrades vorübergehend bis zum 30. Juni 2024 angehalten. Vorhandene globale Anbieter und das Onboarding von Organisations- und Testbereichsanbietern sind nicht betroffen. Weitere Informationen finden Sie unter Häufig gestellte Fragen zu Aktionen erfordernden Nachrichten.

Aktion erfordernde Nachrichtenkarten in Outlook werden mit dem Format für adaptive Karten entworfen. Das Format für adaptive Karten ist ein einfaches, jedoch leistungsfähiges Layoutformat, das sehr viel Flexibilität bietet und die Erstellung visuell ansprechender Karten ermöglicht. In diesem Thema erläutern wir die für Outlook spezifischen Funktionen des Formats für adaptive Karten.

Wichtig

Das adaptive Kartenformat ist nur für eine Aktion erfordernde Nachrichten verfügbar, die per E-Mail gesendet werden, und ist für die Unterstützung von Outlook für iOS und Outlook für Android erforderlich. Das MessageCard-Format wird weiterhin unterstützt, ist jedoch nicht mehr das Hauptformat. Office-Connectors und Microsoft Teams unterstützen derzeit das Format für adaptive Karten nicht. Wenn Sie einen Office 365-Connector oder Microsoft Teams implementieren, sehen Sie sich die Referenz für das MessageCard-Format an.

Informationen dazu, welche Versionen von Outlook das adaptive Kartenformat unterstützen, finden Sie unter Outlook-Versionsanforderungen für Aktionen erfordernde Nachrichten.

Designer für Aktionen erfordernde Nachrichten

Das Designer für aktionenfähige Nachrichten bietet eine Drag-and-Drop-Erfahrung zum schnellen Erstellen und Optimieren adaptiver Karten. Dort finden Sie Beispiele für adaptive Karten, mit denen Sie ihre eigenen Karten erstellen können und mit denen Sie diese Karten an Ihr eigenes Microsoft 365-E-Mail-Konto senden können, um zu sehen, wie sie in Outlook aussehen.

Beispiel für eine einfache adaptive Karte

Beispiel für eine adaptive Karte.

Die oben dargestellte Karte zeigt einige der wichtigsten und leistungsstärksten Funktionen des Formats für adaptive Karten:

  • Möglichkeit zum Stapeln von Elementen unterschiedlichen Typs in beliebiger Reihenfolge
  • Möglichkeit zum Steuern des Abstands zwischen diesen Elementen
  • Möglichkeit zum Erstellen eines Elementlayouts in mehreren Spalten
  • Möglichkeit zum horizontalen und vertikalen Ausrichten von Elementen

Nachfolgend wird erläutert, wie diese Karte erstellt wird:

{
  "$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.0",
  "type": "AdaptiveCard",
  "speak": "<s>Your flight is confirmed for you and 3 other passengers from San Francisco to Amsterdam on Friday, October 10 8:30 AM</s>",
  "body": [
    {
      "type": "ColumnSet",
      "columns": [
        {
          "width": "stretch",
          "verticalContentAlignment": "center",
          "items": [
            {
              "type": "TextBlock",
              "size": "medium",
              "text": "**FLIGHT ITINERARY - CONTOSO AIR**"
            },
            {
              "type": "TextBlock",
              "spacing": "none",
              "text": "Passenger: David Claux",
              "isSubtle": true
            }
          ]
        },
        {
          "width": "auto",
          "items": [
            {
              "type": "Image",
              "width": "48px",
              "url": "http://lh3.googleusercontent.com/ik5VKcUE5U7qGSpU3XWwAwe_zeOnHU5x_79o-VXf-C_EGrFPHp4-NcKRCtblrJM5iO61=w300"
            }
          ]
        }
      ]
    },
    {
      "type": "TextBlock",
      "text": "2 Stops",
      "weight": "bolder",
      "spacing": "medium"
    },
    {
      "type": "TextBlock",
      "text": "Fri, October 10 8:30 AM",
      "weight": "bolder",
      "spacing": "none"
    },
    {
      "type": "ColumnSet",
      "separator": true,
      "columns": [
        {
          "type": "Column",
          "width": 1,
          "items": [
            {
              "type": "TextBlock",
              "text": "San Francisco",
              "isSubtle": true
            },
            {
              "type": "TextBlock",
              "size": "extraLarge",
              "color": "accent",
              "text": "SFO",
              "spacing": "none"
            }
          ]
        },
        {
          "type": "Column",
          "width": "auto",
          "items": [
            {
              "type": "TextBlock",
              "text": "&nbsp;"
            },
            {
              "type": "Image",
              "url": "https://messagecardplayground.azurewebsites.net/assets/airplane.png",
              "size": "small",
              "spacing": "none"
            }
          ]
        },
        {
          "type": "Column",
          "width": 1,
          "items": [
            {
              "type": "TextBlock",
              "horizontalAlignment": "right",
              "text": "Amsterdam",
              "isSubtle": true
            },
            {
              "type": "TextBlock",
              "horizontalAlignment": "right",
              "size": "extraLarge",
              "color": "accent",
              "text": "AMS",
              "spacing": "none"
            }
          ]
        }
      ]
    },
    {
      "type": "TextBlock",
      "text": "Non-Stop",
      "weight": "bolder",
      "spacing": "medium"
    },
    {
      "type": "TextBlock",
      "text": "Fri, October 18 9:50 PM",
      "weight": "bolder",
      "spacing": "none"
    },
    {
      "type": "ColumnSet",
      "separator": true,
      "columns": [
        {
          "type": "Column",
          "width": 1,
          "items": [
            {
              "type": "TextBlock",
              "text": "Amsterdam",
              "isSubtle": true
            },
            {
              "type": "TextBlock",
              "size": "extraLarge",
              "color": "accent",
              "text": "AMS",
              "spacing": "none"
            }
          ]
        },
        {
          "type": "Column",
          "width": "auto",
          "items": [
            {
              "type": "TextBlock",
              "text": "&nbsp;"
            },
            {
              "type": "Image",
              "url": "https://messagecardplayground.azurewebsites.net/assets/airplane.png",
              "size": "small",
              "spacing": "none"
            }
          ]
        },
        {
          "type": "Column",
          "width": 1,
          "items": [
            {
              "type": "TextBlock",
              "horizontalAlignment": "right",
              "text": "San Francisco",
              "isSubtle": true
            },
            {
              "type": "TextBlock",
              "horizontalAlignment": "right",
              "size": "extraLarge",
              "color": "accent",
              "text": "SFO",
              "spacing": "none"
            }
          ]
        }
      ]
    }
  ]
}

Tipps zum Entwerfen adaptiver Karten

Eine adaptive Karte kann sehr einfach oder auch sehr komplex sein, je nachdem, welches Layout Sie erzielen möchten. Es ist immer ratsam, den Entwurf der adaptiven Karte zu planen, bevor Sie die eigentliche Payload dafür schreiben. Verwenden Sie dafür zum Beispiel ein Zeichentool oder einfach nur Stift und Papier. Auf diese Weise ist es einfacher, die visuellen Elementen in die entsprechenden Konstrukte für die adaptive Karte umzusetzen. Nachfolgend finden Sie einige Tipps, die Ihnen beim Einstieg helfen.

Textformatierung

Alle TextBlock-Elemente einer Karte können mit Markdown formatiert werden. Outlook unterstützt grundlegendes Markdown.

Wichtig

Da alle TextBlock-Elemente als Markdown verarbeitet werden, stellen Sie sicher, dass Sie Markdown-Sonderzeichen (wie z. B. * oder #) bei Bedarf auskommentieren.

Effekt Markdown-Syntax
Kursiv *This text is in italics*
Fett **This text is bold**
Fett + Kursiv ***This text is bold and in italics***
Durchgestrichen ~~This text is struck through~~
Link [Microsoft](http://www.microsoft.com)
Überschriften (Ebene 1 bis 6) # Heading bis ###### Heading
Aufzählung * List item oder - List item

Tipp

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

Entwurf für einen kleinen Bildschirm

Genau wie beim Entwerfen des HTML-Textkörpers einer E-Mail-Nachricht müssen Sie auch bei einer adaptiven Karte davon ausgehen, dass sie möglicherweise auf einem großen, breiten als auch auf einem kleinen Bildschirm (z. B. einem auf einem Desktop-Computer und auf einem Smartphone.) angezeigt werden kann.

Tipp

  • Es wird empfohlen, die adaptive Karte so zu entwerfen, dass sie auch auf einem kleinen Bildschirm optimal dargestellt wird. In der Regel wird ein Karte, das für einen schmalen Bildschirm entwickelt wurde, gut auf einen breiten Bildschirm skaliert. Das Gegenteil ist jedoch nicht der Fall.
  • Es wird nicht empfohlen, beim Entwerfen der adaptiven Karte davon auszugehen, dass sie nur von Outlook-Benutzern auf einem Desktop-Computer gesehen wird.

Beim Gestalten von Bildern auch Bildschirme mit hohen DPI-Werten berücksichtigen

Es ist noch nicht so lange her, dass die meisten Bildschirme eine eher niedrige Auflösung (z. B. 1024 x 768 Pixel) und 96 DPI (Punkte pro Zoll) hatten. Dies bedeutete, dass 96 Pixel pro Zoll auf dem Bildschirm passten. In den letzten Jahren sind Bildschirme hinsichtlich Auflösung und DPI jedoch kontinuierlich „gewachsen“, insbesondere auf Mobilgeräten. Daher ist es heute nicht ungewöhnlich, dass ein Bildschirm über 192 DPI oder mehr verfügt.

Beim Entwerfen einer adaptiven Karte müssen Sie sicherstellen, dass die Bilder auf jedem Bildschirm optimal dargestellt werden, unabhängig vom DPI-Wert.

Tipp

  • Es wird empfohlen, die Bilder unter der Prämisse zu entwerfen, dass sie auf einem Bildschirm mit einem hohen DPI-Wert angezeigt werden. Ein Bild, das für einen Bildschirm mit niedrigem DPI-Wert (96) ausgelegt ist, wird vergrößert, wenn es auf einem Bildschirm mit höherem DPI-Wert angezeigt wird. Ein Bild, das für einen Bildschirm mit einem hohen DPI-Wert ausgelegt ist, wird auf einem Bildschirm mit einem niedrigen DPI-Wert verkleinert, was in der Regel zu guten Ergebnissen führt. Anders gesagt: Es empfiehlt sich, ein Bild für 100 x 100 Pixel zu entwerfen und es mit 50 x 50 Pixeln anzuzeigen, als ein Bild für 50 x 50 Pixel zu entwerfen und es mit 100 x 100 Pixeln anzuzeigen.
  • Es wird empfohlen, die Eigenschaften width und height des Image-Elements zu verwenden, wenn Sie die tatsächliche Größe der Bilder auf der Karte genau steuern müssen.
  • Es wird nicht empfohlen, Bilder mit einer festen Hintergrundfarbe wie z. B: Weiß zu entwerfen, es sei denn, Sie möchten, dass diese Hintergrundfarbe dem Benutzer angezeigt wird. In Outlook werden Ihre adaptiven Karten nicht notwendigerweise auf einem weißen Hintergrund angezeigt, und Sie müssen darauf achten, dass Ihre Bilder über jeder Hintergrundfarbe optimal angezeigt werden. Aus diesem Grund wird empfohlen, dass der Hintergrund der Bilder transparent ist.
  • Es wird nicht empfohlen, Bilder mit integrierten Abständen zu erstellen. Solche Abstände wirken sich in der Regel negativ auf das Gesamtlayout aus, indem sie zu unerwünschten Abständen an den Seiten des Bilds führen.

Verwenden von Containern

Verwenden Sie das Container-Element nur, wenn es notwendig ist. Mit dem Container-Element könne Sie mehrere Elemente zusammen gruppieren.

Tipp

  • Es wird empfohlen, einen Container zu verwenden, um eine Gruppe von Elementen hervorzuheben. Indem Sie die style-Eigenschaft von Container auf emphasis festlegen, können Sie diesen Container und das darin enthaltene Element hervorheben.
  • Es wird empfohlen, einen Container zu verwenden, um eine Aktion mit einer Gruppe von Elementen zu verknüpfen. Indem Sie die selectAction-Eigenschaft von Container festlegen, werden der Container und sein Inhalt zu einem Einzelklickbereich, der die angegebene Aktion auslöst.
  • Es wird empfohlen, einen Container zu verwenden, um festzulegen, dass ein Teil der Karte reduziert werden kann. Indem Sie Action.ToggleVisibility für einen Container verwenden, können Sie auf einfache Weise für eine Gruppe von Elementen festlegen, dass sie reduziert werden können.
  • Es wird nicht empfohlen, Container zu einem beliebigen anderen Zweck zu verwenden.

Verwenden von Spalten

Verwenden Sie ColumnSet nur, wenn Sie mehrere Elemente auf einer einzelnen horizontalen Linie ausrichten müssen.

Tipp

  • Es wird empfohlen, ColumnSet im Allgemeinen für tabellenähnliche Layouts zu verwenden.
  • Es wird empfohlen, ColumnSet zu verwenden, wenn Sie z. B. ein Bild ganz links auf der Karte und Text in derselben Zeile ganz rechts auf der Karte anzeigen möchten.
  • Es wird empfohlen, eine geeignete Größe für Spalten zu verwenden:
    • Verwenden Sie "width": "auto" für eine Column, um die Breite so weit anzupassen, dass der Inhalt hineinpasst.
    • Verwenden Sie "width": "stretch" für eine Column, um die verbleibende Breite in ColumnSet zu nutzen. Wenn mehrere Columns die Option "width": "stretch" aufweisen, teilen sie die verbleibende Breite gleichmäßig auf.
    • Verwenden Sie "width": <number> für eine Column, um einen Teil der verfügbaren Breite im ColumnSet zu nutzen. Wenn drei Spalten vorhanden sind, für die die width-Eigenschaft auf 1, 4 oder 5 festgelegt ist, nutzen die Spalten jeweils 10 %, 40 % und 50 % der verfügbaren Breite.
    • Verwenden Sie "width": "<number>px", um eine bestimmte Pixelbreite zu verwenden. Dies ist besonders nützlich (und notwendig), wenn Sie Tabellenlayouts erstellen.
  • Es wird nicht empfohlen, ColumnSet zu verwenden, wenn Sie Elemente einfach vertikal Stapeln müssen.

Eigenschaften und Funktionen für adaptive Karten in Outlook

Outlook stellt eine Reihe von zusätzlichen Eigenschaften und Funktionen für adaptive Karten bereit, die im Kontext von Aktion erfordernden Nachrichten verwendet werden können.

Wichtig

Die für Outlook spezifischen Eigenschaften für adaptive Karten können nur im Kontext von Aktion erfordernden Nachrichten verwendet werden. Sie funktioniert nicht in anderen Anwendung, die adaptive Karten verwenden, und sind daher nicht auf der offiziellen Website für adaptive Karten dokumentiert.

Funktonen für adaptive Karten, die für Aktion erfordernde Nachrichten in Outlook nicht unterstützt werden

Action.Submit

Der Aktionstyp Action.Submit wird NICHT für Aktion erfordernde Nachrichten in Outlook unterstützt. Wenn Sie Action.Submit in die Karte einbeziehen, wird dies nicht angezeigt.

Input.Time

Der Elementtyp Input.Time wird NICHT für Aktion erfordernde Nachrichten in Outlook unterstützt. Wenn Sie ein Input.Time-Element in die Karte einbeziehen, wird es nicht angezeigt. Wenn es erforderlich ist, dass Benutzer eine Uhrzeit eingeben, müssen Sie stattdessen Input.Text verwenden und den Wert serverseitig überprüfen.

Action.Http

Aktion erfordernde Nachrichten in Outlook verwenden über den Typ Action.Http ein HTTP-basiertes Aktionsmodell. Action.Http ermöglicht, eine GET- oder POST-Anforderung an eine bestimmte Ziel-URL zu richten, wenn ein Benutzer eine Aktion auf der Karte durchführt.

Eigenschaftenname Typ Erforderlich Beschreibung
type String Ja Muss auf Action.Http festgelegt werden.
title String Nein Der Titel der Aktion, wie er auf dem Bildschirm z. B. auf einem Steuerelement angezeigt wird.
method String Ja Gültige Werte sind GET und POST. Wenn method auf POST festgelegt ist, muss die Eigenschaft body angegeben werden.
url String Ja Die URL des Zielendpunkts der Anforderung. Die url-Eigenschaft unterstützt die Ersetzung von Eingabewerten. Hinweis: Auf diese URL muss über das Internet zugegriffen werden, localhost kann nicht verwendet werden.
headers Array von HttpHeader-Objekten Nein Eine optionale Liste von Überschriften, die an den Zielendpunkt gesendet werden sollen.
body String Nur, wenn method auf POST festgelegt ist. Der Textkörper der POST-Anforderung. Die body-Eigenschaft unterstützt die Ersetzung von Eingabewerten.

HttpHeader

Eigenschaftenname Typ Erforderlich Beschreibung
name String Ja Der Name des HTTP-Headers. Beispiel: Content-Type.
value String Ja Der Wert des HTTP-Headers. Beispiel: application/json. Die value-Eigenschaft unterstützt die Ersetzung von Eingabewerten.

Beispiel für Action.Http

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "Hello world!"
    }
  ],
  "actions": [
    {
      "type": "Action.Http",
      "title": "Click me!",
      "method": "POST",
      "url": "https://contoso.com/api/...",
      "body": "<body of the POST request>",
      "headers": [
        { "name": "Content-Type", "value": "application/json" }
      ]
    }
  ]
}

Die Beispielkarte für Action.Http.

Implementieren der Web-API

Die URL, die in der url-Eigenschaft angegeben ist, muss den folgenden Anforderungen entsprechen.

  • Der Endpunkt muss POST-Anforderungen annehmen.
  • Der Endpunkt sollte den Inhalt der body-Eigenschaft übernehmen.
  • Der Endpunkt sollte den im Authorization-Header gesendeten JWT verwenden, um zu überprüfen, ob Anforderungen von Microsoft stammen.

Ersetzen des Eingabewerts

Adaptive Karten enthalten möglicherweise Eingaben. Unter Umständen ist es notwendig, die Werte dieser Eingaben über eine Action.Http-Aktion an den Zielendpunkt zu übergeben. Dies wird durch die Ersetzung von Eingabewerten erreicht. Betrachten Sie das folgende Beispiel:

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "What's your name?"
    },
    {
      "type": "Input.Text",
      "id": "nameInput",
      "placeholder": "Type your name"
    }
  ],
  "actions": [
    {
      "type": "Action.Http",
      "title": "Say hello",
      "method": "GET",
      "url": "https://contoso.com/sayhello?name={{nameInput.value}}"
    }
  ]
}

Beispielkarte für die Ersetzung von Eingabewerten.

Die oben aufgeführte Karte definiert eine Texteingabe und legt die id-Eigenschaft auf nameInput fest. Sie definiert auch eine Action.Http-Aktion, die einen GET-Aufruf an einen Endpunkt in der Domäne „contoso.com“ durchführt. Durch die Einbeziehung von ?name={{nameInput.value}} in die Ziel-URL wird der Wert der Eingabe mit der ID nameInput zu dem Zeitpunkt, an dem der Benutzer die Aktion ausführt, dynamisch ersetzt. Wenn der Benutzer zum Beispiel den Namen „David“ in die Texteingabe eingegeben hat, lautet die Ziel-URL nach der Ersetzung https://contoso.com/sayhello?name=David

Die Ersetzung von Eingabewerten funktioniert auch in der body-Eigenschaft einer Action.Http-Aktion. Beispiel:

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "What's your name?"
    },
    {
      "type": "Input.Text",
      "id": "nameInput",
      "placeholder": "Type your name"
    }
  ],
  "actions": [
    {
      "type": "Action.Http",
      "title": "Say hello",
      "method": "POST",
      "url": "https://contoso.com/sayhello",
      "body": "{{nameInput.value}}"
    }
  ]
}

Melden der erfolgreichen oder fehlerhaften Ausführung einer von Action.Http

Der Dienst sollte einen HTTP 200-Statuscode zurückgeben, wenn er eine Action.Http-Aktion erfolgreich ausführt. Wenn die Ausführung der Aktion fehlschlägt, sollte der Dienst einen HTTP 4xx-Statuscode zurückgeben. Dieser sollte auch den CARD-ACTION-STATUS-HTTP-Header in der Antwort enthalten, um eine benutzerdefinierte Fehlermeldung anzugeben. Der Wert dieses Headers wird dem Endbenutzer angezeigt, wenn Action.Http nicht ausgeführt werden kann.

Tipp

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

  • Es wird empfohlen, den CARD-ACTION-STATUS-Header in der Fehlerantwort zurückzugeben.
  • Formulieren Sie die Nachricht in diesem Header so informativ und aussagekräftig wie möglich.
  • 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.

Aktualisierungskarten

Aktualisierungskarten sind ein sehr leistungsstarker Mechanismus, mit Action.Http dem Aktionen die Karte während des erfolgreichen Abschlusses der Aktion vollständig aktualisieren können. Es gibt viele Szenarien, die von 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 Action.OpenUrl-Aktion eingeschlossen, über die der Benutzer die Umfrage online einsehen kann.

Ein Dienst muss folgendes ausführen, um eine Karte als Ergebnis einer Action.Http-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 Action.OpenUrl-Aktion mit ein, um die Entität in der externen App anzuzeigen, aus der sie stammt.

Action.InvokeAddInCommand

Die Aktion Action.InvokeAddInCommand ö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 Action.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 Nachricht mit Aktionen.

Eigenschaftenname Typ Erforderlich Beschreibung
type String Ja Muss auf Action.InvokeAddInCommand festgelegt werden.
title String Nein Der Titel der Aktion, wie er auf dem Bildschirm z. B. auf einem Steuerelement angezeigt wird.
addInId String Ja Gibt die Add-In-ID des erforderlichen-Add-Ins an. Die Add-In-ID befindet sich im Id-Element im Manifest des Add-Ins.
desktopCommandId String Ja 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 Objekt Ja 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.

Action.DisplayMessageForm

Die Aktion Action.DisplayMessageForm öffnet das Leseformular einer Nachricht anhand der ID dieser Nachricht. Nachrichten-IDs können über die Outlook-REST-APIs abgerufen werden.

Eigenschaftenname Typ Erforderlich Beschreibung
type String Ja Muss auf Action.DisplayMessageForm festgelegt werden.
title String Nein Der Titel der Aktion, wie er auf dem Bildschirm z. B. auf einem Steuerelement angezeigt wird.
itemId String Ja Gibt die ID der zu öffnenden Nachricht an.

Action.DisplayAppointmentForm

Die Aktion Action.DisplayAppointmentForm öffnet des Leseformular eines Kalenderelementes anhand der ID des Kalenderelements. Kalender-IDs können über die Outlook-REST-APIs abgerufen werden.

Eigenschaftenname Typ Erforderlich Beschreibung
type String Ja Muss auf Action.DisplayAppointmentForm festgelegt werden.
title String Nein Der Titel der Aktion, wie er auf dem Bildschirm z. B. auf einem Steuerelement angezeigt wird.
itemId String Ja Gibt die ID des zu öffnenden Kalenderelements an.

Action.ToggleVisibility

Die Aktion Action.ToggleVisibility ermöglicht, bestimmte Elemente einer Karte ein- oder auszublenden, wenn ein Benutzer auf eine Schaltfläche oder ein anderes Element mit Aktionen klickt. Zusammen mit der Eigenschaft isVisible ermöglicht Action.ToggleVisibility erweiterte Interaktivität auf einer einzelnen Karte.

Eigenschaftenname Typ Erforderlich Beschreibung
type String Ja Muss auf Action.ToggleVisibility festgelegt werden.
title String Nein Der Titel der Aktion, wie er auf dem Bildschirm z. B. auf einem Steuerelement angezeigt wird.
targetElements Array von Zeichenfolge oder TargetElement Ja Die Liste der Elemente, deren Sichtbarkeit umgeschaltet werden soll. Wenn die Elemente im targetElements-Array als Zeichenfolgen angegeben werden, müssen sie die ID eines Elements auf der Karte darstellen. Wenn die Aktion ausgeführt wird, werden diese Elemente angezeigt, wenn sie noch nicht sichtbar waren, oder anderenfalls ausgeblendet. Wenn Elemente des Arrays als TargetElement-Objekte angegeben sind, wird die Sichtbarkeit der einzelnen Zielelemente durch die isVisible-Eigenschaft des TargetElement-Objekts definiert.

TargetElement

Eigenschaftenname Typ Erforderlich Beschreibung
elementId String Ja Die ID des Zielelements.
isVisible Boolean Ja Gibt an, ob das Zielelement sichtbar sein soll, sobald die Aktion abgeschlossen ist.

Beispiel für Action.ToggleVisibility

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "**Action.ToggleVisibility example**: click the button to show or hide a welcome message"
    },
    {
      "type": "TextBlock",
      "id": "helloWorld",
      "isVisible": false,
      "text": "**Hello World!**",
      "size": "extraLarge"
    }
  ],
  "actions": [
    {
      "type": "Action.ToggleVisibility",
      "title": "Click me!",
      "targetElements": [ "helloWorld" ]
    }
  ]
}

Die Beispielkarte wird ähnlich dem Folgenden gerendert, bevor auf die Schaltfläche geklickt wird:

Screenshot der Beispielkarte für Action.ToggleVisibility im reduzierten Zustand.

Die Beispielkarte wird ähnlich dem Folgenden gerendert, nachdem auf die Schaltfläche geklickt wurde:

Screenshot der Beispielkarte für Action.ToggleVisibility im erweiterten Zustand.

ActionSet-Element

Aktionen erfordernde Nachrichten in Outlook fügen Unterstützung für das ActionSet-Element hinzu, sodass Sie an einer beliebigen Stelle auf einer Karte Aktionsschaltflächen hinzufügen können.

Eigenschaftenname Typ Erforderlich Beschreibung
type String Ja Muss auf ActionSet festgelegt werden.
id String Nein Die eindeutige ID des Elements.
spacing String Nein Steuert die Größe des Abstands zwischen diesem Element und dem vorherigen Element.
separator Boolean Nein Steuert, ob eine Trennlinie zwischen diesem Element und dem vorherigen Element angezeigt werden soll. Die Trennlinie wird in der Mitte des Platzes angezeigt, der durch die Eigenschaft spacing definiert wird.
horizontalAlignment String Nein Steuert die horizontale Ausrichtung dieses Elements innerhalb des Containers.
actions Array von Action-Objekten Nein Die Aktionen, die im Satz angezeigt werden sollen.

Außer der Tatsache, dass ActionSet an beliebiger Stelle auf der Karte platziert werden kann, verhält sich dies genau wie die Aktionseigenschaft einer AdaptiveCard.

Beispiel für ActionSet

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
      {
        "type": "ActionSet",
        "actions": [
          {
            "type": "Action.ToggleVisibility",
            "title": "Click me!",
            "targetElements": [ "helloWorld" ]
          }
        ]
      },
      {
        "type": "TextBlock",
        "text": "**Action.ToggleVisibility example**: click the button above to show or hide a welcome message"
      },
      {
        "type": "TextBlock",
        "id": "helloWorld",
        "isVisible": false,
        "text": "**Hello World!**",
        "size": "extraLarge"
      }
  ]
}

Screenshot der Beispielkarte für ActionSet.

Weitere Eigenschaften für alle Elementtypen adaptiver Karten

Eigenschaftenname Typ Erforderlich Beschreibung
isVisible Boolean Nein. Standardwert ist true. Der ursprüngliche Sichtbarkeitszustand des Elements. Wenn isVisible auf false festgelegt ist, ist das Element zunächst auf der Karte nicht sichtbar. Es kann angezeigt werden, indem eine Action.ToggleVisibility-Aktion verwendet wird, wie oben beschrieben.

Eine Erläuterung zur Verwendung von isVisible finden Sie im vorhergehenden Beispiel.

Weitere Eigenschaften für den AdaptiveCard-Typ

Die folgenden weiteren Eigenschaften können für ein AdaptiveCard-Objekt im Kontext von Aktion erfordernden Nachrichten in Outlook festgelegt werden:

Eigenschaftenname Typ Erforderlich Beschreibung
autoInvokeAction Action.Http Nein Die autoInvokeAction-Eigenschaft gibt eine URL an, die eine aktualisierte Nutzlast einer adaptive Karte bereitstellt, um die vorhandene Nutzlast in der Nachricht zu ersetzen. Die method der Action.Http-Aktion MUSS POSTsein. Auf diese Weise kann Ihr Dienst aktuelle Informationen in der Nachricht mit Aktionen bereitstellen. Weitere Informationen finden Sie unter Aktualisieren einer Nachricht mit Aktionen, wenn der Benutzer sie öffnet.
correlationId Zeichenfolge Nein 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 Action.HttpAktion 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.
expectedActors Array aus Zeichenfolgen Nein expectedActors enthält eine Liste der erwarteten E-Mail-Adressen der Benutzer, die auf der Karte Action.Http-Aktionen ausführen können. Ein Benutzer kann mehrere E-Mail-Adressen haben, und der Zielendpunkt Action.Http erwartet möglicherweise nicht die bestimmte E-Mail-Adresse, die im sub-Anspruch des Bearertokens aufgeführt wird. Ein Benutzer könnte beispielsweise sowohl die E-Mail-Adresse john.doe@contoso.com als auch john@contoso.com haben, wobei der Action.Http-Zielendpunkt erwartet, john@contoso.com im untergeordneten Anspruch des Bearertokens zu erhalten. Indem Sie die Einstellung expectedActors auf ["john@contoso.com"] festlegen, hat der sub-Anspruch die erwartete E-Mail-Adresse.
hideOriginalBody Boolesch Nein. Standardwert ist false. 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. Überlegen Sie, ob es von Vorteil ist, den ursprünglichen HTML-Text auszublenden, wenn die Karte selbst alle Informationen enthält, die ein Benutzer benötigt, oder wenn der Inhalt der Karte redundant ist, da er dem Inhalt des Texts entspricht. Schließen Sie immer einen ansprechenden HTML-Textkörper mit Bedeutung 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.
originator Zeichenfolge Ja 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.

Weitere Eigenschaften für den Column-Typ

Die folgenden weiteren Eigenschaften können für ein Column-Objekt im Kontext von Aktion erfordernden Nachrichten in Outlook festgelegt werden:

Eigenschaftenname Typ Erforderlich Beschreibung
width Nummer oder Zeichenfolge Keine (Standard ist auto) Diese Eigenschaft ermöglicht eine genaue Steuerung der Breite einer Column innerhalb des ColumnSet. Weitere Informationen finden Sie unter Werte für Spaltenbreite.
verticalContentAlignment Zeichenfolge. Gültige Werte sind top, center und bottom. Nein. Standard ist top. Die Eigenschaft verticalContentAlignment ermöglicht die senkrechte Positionierung des Inhalts der Spalte (z. B. aller Elemente). Die ist besonders nützlich bei tabellenähnlichen Layouts.
backgroundImage String Nein Die Eigenschaft backgroundImage steht für die URL zu einem Bild, das als Hintergrund der Column verwendet werden soll. Das Hintergrundbild umfasst die gesamte Fläche der Column und wird so skaliert, dass das ursprüngliche Seitenverhältnis beibehalten wird.

Werte für die Spaltenbreite

Wenn width als Zahl ausgedrückt wird, stellt dies die relative Gewichtung der Column innerhalb des ColumnSet dar. Damit eine gewichtete Column auch wirklich nützlich ist, muss mindestens eine weitere gewichtete Column im Satz vorhanden sein. Wenn zum Beispiel für Spalte A width auf 1 und für Spalte B h width auf 2 festgelegt ist, dann verwendet Spalte A ein Drittel des verfügbaren Platzes im Satz, und Spalte B verwendet die verbleibenden zwei Drittel.

Wenn width als Zeichenfolge ausgedrückt wird, können die folgenden Werte verwendet werden:

  • auto: Die Column verwendet so viel des verfügbaren Platzes, wie für den Inhalt erforderlich ist.
  • stretch: Die Column verwendet den verbleibenden Platz im Satz. Wenn die Eigenschaft width für mehrere Spalten auf stretch festgelegt ist, wird der verbleibende Platz von allen Spalten gleichmäßig genutzt.
  • <number>px (z. B. 50px): Die Spalte wird über die angegebene Anzahl von Pixeln verteilt.
  • <number>*, (z. B. 1*): Dies entspricht der Angabe width als Zahl.

Beispiel für Column

{
  "$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "ColumnSet",
      "columns": [
        {
          "width": "50px",
          "items": [
            {
              "type": "Image",
              "url": "https://adaptivecards.io/content/cats/1.png",
              "size": "stretch"
            }
          ]
        },
        {
          "width": "stretch",
          "verticalContentAlignment": "center",
          "items": [
            {
              "type": "TextBlock",
              "text": "This card has two ColumnSets on top of each other. In each, the left column is explicitly sized to be 50 pixels wide.",
              "wrap": true
            }
          ]
        }
      ]
    },
    {
      "type": "ColumnSet",
      "columns": [
        {
          "width": "50px"
        },
        {
          "width": "stretch",
          "verticalContentAlignment": "center",
          "items": [
            {
              "type": "TextBlock",
              "text": "In this second ColumnSet, columns align perfectly even though there is nothing in the left column.",
              "wrap": true
            }
          ]
        }
      ]
    }
  ]
}

Screenshot der Beispielkarte für width.

Weitere Eigenschaften für den Container-Typ

Die folgenden weiteren Eigenschaften können für ein Container-Objekt im Kontext von Aktion erfordernden Nachrichten in Outlook festgelegt werden:

Eigenschaftenname Typ Erforderlich Beschreibung
verticalContentAlignment Zeichenfolge. Gültige Werte sind top, center und bottom. Nein. Standard ist top. Die Eigenschaft verticalContentAlignment ermöglicht die senkrechte Positionierung des Inhalts der Spalte (z. B. aller Elemente). Die ist besonders nützlich bei tabellenähnlichen Layouts.
backgroundImage String Nein Die Eigenschaft backgroundImage steht für die URL zu einem Bild, das als Hintergrund der Container verwendet werden soll. Das Hintergrundbild umfasst die gesamte Fläche des Container und wird so skaliert, dass das ursprüngliche Seitenverhältnis beibehalten wird.

Diese Eigenschaften verhalten sich genau wie ihre Entsprechung für den Column-Typ. Beziehen Sie sich auf das oben genannte Beispiel.

Weitere Eigenschaften für den Image-Typ

Die folgenden weiteren Eigenschaften können für ein Image-Objekt im Kontext von Aktion erfordernden Nachrichten in Outlook festgelegt werden:

Eigenschaftenname Typ Erforderlich Beschreibung
width String Nein Diese Eigenschaft ermöglicht eine genaue Steuerung der Breite eines Bildes in Pixeln. Das zulässige Format ist <number>px, wobei <number> eine ganze Zahl ist. Wenn width angegeben ist, wird die size-Eigenschaft ignoriert. Wenn width angegeben ist, height jedoch nicht, wird die Höhe des Bilds automatisch berechnet, damit das Seitenverhältnis berücksichtigt wird.
height String Nein Diese Eigenschaft ermöglicht die genaue Steuerung der Höhe eines Bilds in Pixeln. Das zulässige Format ist <number>px, wobei <number> eine ganze Zahl ist. Wenn height angegeben ist, wird die size-Eigenschaft ignoriert. Wenn height angegeben ist, width jedoch nicht, wird die Breite des Bilds automatisch berechnet, damit das Seitenverhältnis berücksichtigt wird.
backgroundColor String Nein Die backgroundColor-Eigenschaft gibt die Farbe an, über der das Bild gerendert werden soll. backgroundColor ist besonders in den Fällen nützlich, in denen ein einzelnes Bild auf einer Vielzahl von Hintergrundfarben verwendet werden soll, denn hierdurch entfällt die Notwendigkeit, mehrere Versionen eines einzelnen Bilds erstellen zu müssen. Das Format der Eigenschaft backgroundColor ist #RRGGBB, wobei RR, GG und BB die Hexadezimalwerte für die Rot-, Grün- und Blau-Komponenten der Farbe sind.

Beispiel für Bildeigenschaften

{
  "$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "Below, the same image is presented on top of two different background colors."
    },
    {
      "type": "Image",
      "width": "64px",
      "url": "https://messagecardplayground.azurewebsites.net/assets/circleontransparentbackground.png",
      "backgroundColor": "#FF0000"
    },
    {
      "type": "Image",
      "style": "person",
      "width": "64px",
      "url": "https://messagecardplayground.azurewebsites.net/assets/circleontransparentbackground.png",
      "backgroundColor": "#0000FF"
    }
  ]
}

Screenshot der Beispielkarte für Bildeigenschaften.

Siehe auch