Entwerfen von Aktion erfordernden Nachrichtenkarten in Outlook mit dem adaptiven Kartenformat

Artikel
04/08/2023

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

Zur Unterstützung von Outlook für iOS und Outlook für Android ist das adaptive Kartenformat erforderlich. Das MessageCard-Format wird weiterhin unterstützt, ist jedoch nicht mehr das Hauptformat.

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`	Zeichenfolge	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`	Zeichenfolge	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`	Zeichenfolge	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`	Zeichenfolge	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`	Zeichenfolge	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`	Zeichenfolge	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`	Zeichenfolge	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`	Zeichenfolge	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 `POST`sein. 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.Http`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.
`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
            }
          ]
        }
      ]
    }
  ]
}

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`	Zeichenfolge	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

Portal für adaptive Karten

Freigeben über

Entwerfen von Aktion erfordernden Nachrichtenkarten in Outlook mit dem adaptiven Kartenformat

Designer für Aktionen erfordernde Nachrichten

Beispiel für eine einfache adaptive Karte

Tipps zum Entwerfen adaptiver Karten

Textformatierung

Entwurf für einen kleinen Bildschirm

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

Verwenden von Containern

Verwenden von Spalten

Eigenschaften und Funktionen für adaptive Karten in Outlook

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

Action.Submit

Input.Time

Action.Http

HttpHeader

Beispiel für Action.Http

Implementieren der Web-API

Ersetzen des Eingabewerts

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

Aktualisierungskarten

Action.InvokeAddInCommand

Action.DisplayMessageForm

Action.DisplayAppointmentForm

Action.ToggleVisibility

TargetElement

Beispiel für Action.ToggleVisibility

ActionSet-Element

Beispiel für ActionSet

Weitere Eigenschaften für alle Elementtypen adaptiver Karten

Weitere Eigenschaften für den AdaptiveCard-Typ

Weitere Eigenschaften für den Column-Typ

Werte für die Spaltenbreite

Beispiel für Column

Weitere Eigenschaften für den Container-Typ

Weitere Eigenschaften für den Image-Typ

Beispiel für Bildeigenschaften

Siehe auch

Feedback

Zusätzliche Ressourcen