Universelles Aktionsmodell

  • Artikel

Kontext

Adaptive Karten sind plattformunabhängige Ausschnitte der Benutzeroberfläche, die ein schlankes JSON-Format nutzen, das von Apps und Diensten gemeinsam genutzt werden kann. Adaptive Karten passen sich nicht nur dem Aussehen und Verhalten an, sondern bieten auch umfangreiche Interaktionsfunktionen. Weitere Informationen zu adaptiven Karten finden Sie unter adaptivecards.io.

Mit der steigenden Beliebtheit adaptiver Karten hatten verschiedene Hosts damit begonnen, unterschiedliche Aktionsmodelle zu unterstützen, was zu einer Fragmentierung geführt hat. Um dieses Problem zu lösen, haben die Teams von Teams, Outlook und adaptive Karten daran gearbeitet, ein neues universelles Bot-Aktionsmodell zu erstellen, das über alle Hosts hinweg kompatibel ist. Diese Bemühungen haben zu Folgendem geführt:

  • Generalisierung von Bots und dem Bot Framework als Möglichkeit zur Implementierung auf adaptiven Karten basierender Szenarien für sowohl Teams (Bots) als auch Outlook (Aktion erfordernde Nachricht)
  • Action.Execute als Ersatz für Action.Submit (zurzeit von Bots verwendet) und Action.Http (zurzeit von Aktion erfordernden Nachrichten verwendet)
  • Beliebte Funktionen, die nur von Aktion erfordernden Nachrichten unterstützt werden, wurden für Bots verfügbar gemacht, nämlich:
    • Die Möglichkeit, eine Karte zu dem Zeitpunkt ihrer Anzeige zu aktualisieren
    • Die Möglichkeit, dass Action.Execute-Aktionen eine aktualisierte Karte zurückgeben, die sofort im Client angezeigt wird

Weitere Informationen zu Aktion erfordernden Nachrichten in Outlook finden Sie in der Dokumentation zu Aktion erfordernden Nachrichten.

Ausführliche Informationen zu verschiedenen Szenarien, die mit universellen Aktionen in Teams möglich sind, finden Sie in der Teams-Kartenreferenz.

Vorher Action.Execute Mit Action.Execute
An image depicting the current inconsistent model in Teams and Outlook An image depicting the consistent model that is enabled with Action.Execute in Teams and Outlook
An image showing how Adaptive Card JSONs look like with current inconsistent model An image showing how Adaptive Card JSONs would look the same with new Action.Execute based model

Quelle: Adaptive Karten @ Microsoft Build 2020

Der Rest dieses Dokuments konzentriert sich auf die Dokumentation des universellen Bot-Aktionsmodells im Kontext von Teams und Outlook. Wenn Sie bereits adaptive Karten in Teams mit Bot verwenden, können Sie denselben Bot mit ein paar Änderungen verwenden, um Action.Execute zu unterstützen. Wenn Sie Aktion erfordernde Nachrichten in Outlook verwenden, müssen Sie einen Bot entwickeln, der Action.Execute unterstützt. Aktuell befindet sich die Unterstützung des universellen Bot-Aktionsmodells in Outlook-Clients in der aktiven Entwicklung.

Schema

WICHTIG

Das universelle Bot-Aktionsmodell Modell wird in der Schemaversion 1.4 für adaptive Karten eingeführt. Um diese neuen Funktionen nutzen zu können, muss die version-Eigenschaft Ihrer adaptiven Karte auf 1.4 oder höher festgelegt werden, wie in den folgenden Beispielen gezeigt. Beachten Sie, dass dadurch Ihre adaptive Karte mit älteren Clients (Outlook oder Teams) nicht mehr kompatibel ist, die das universelle Bot-Aktionsmodell nicht unterstützen.

Wenn Sie die refresh-Eigenschaft und/oder Action.Execute verwenden und eine Kartenversion < 1.4 angeben, geschieht Folgendes:

Client Verhalten
Outlook Ihre Karte funktioniert NICHT. refresh wird nicht berücksichtigt, und Action.Execute wird nicht gerendert. Ihre Karte wird möglicherweise sogar vollständig abgelehnt.
Teams Ihre Karte funktioniert MÖGLICHERWEISE NICHT (refresh wird möglicherweise nicht berücksichtigt, und die Action.Execute-Aktionen werden möglicherweise nicht gerendert), abhängig von der Version des Teams-Clients.

Um maximale Kompatibilität in Teams zu gewährleisten, sollten Sie erwägen, Ihre Action.Execute-Aktionen mit einer Action.Submit-Aktion in der fallback-Eigenschaft zu definieren.

Weitere Informationen finden Sie weiter unten im Abschnitt Abwärtskompatibilität.

Action.Execute

Verwenden Sie beim Erstellen von adaptiven Karten Action.Execute anstelle von Action.Submit und Action.Http. Das Schema für Action.Execute ähnelt dem von Action.Submit in hohem Maße.

Beispiel-JSON

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.4",
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": "Action.Submit"
        }
      ]
    }
  ]
}

Eigenschaften

Eigenschaft Type Erforderlich BESCHREIBUNG
type "Action.Execute" Ja Muss "Action.Execute"lauten.
Verb Zeichenfolge Nein Eine praktische Zeichenfolge, die von Entwicklern verwendet werden kann, um die Aktion zu identifizieren.
data string, object Nein Anfängliche Daten, mit denen Eingabefelder kombiniert werden. Dabei handelt es sich im Wesentlichen um „verborgene“ Eigenschaften.
title string Nein Bezeichnung für eine Schaltfläche oder einen Link, die diese Aktion darstellt.
iconUrl uri Nein Optionales Symbol, das in Verbindung mit dem Titel für die Aktion angezeigt wird. Unterstützt Daten-URI in adaptiven Karten der Version 1.2 und höher.
style ActionStyle Nein Steuert den Stil einer Aktion, was beeinflusst, wie die Aktion angezeigt, gesprochen usw. wird.
fallback <action object>, "drop" Nein Beschreibt, was zu tun ist, wenn „Action.Execute“ vom Client, der die Karte anzeigt, nicht unterstützt wird.
requires Dictionary<string> Nein Eine Reihe von Schlüssel-Wert-Paaren, die Funktionen anzeigen, die das Element erfordert, mit der entsprechenden Mindestversion. Wenn eine Funktion fehlt oder nicht die ausreichende Version hat, wird ein Fallback ausgelöst.

Aktualisierungsmechanismus

Neben Action.Execute wird jetzt ein neuer Aktualisierungsmechanismus unterstützt, der es ermöglicht adaptive Karten zu erstellen, die zum Zeitpunkt ihrer Anzeige automatisch aktualisiert werden. Dadurch wird sichergestellt, dass Benutzer immer aktuelle Daten sehen. Ein typischer Anwendungsfall für die Aktualisierung ist eine Genehmigungsanforderung: nach der Genehmigung ist es am besten, dass Benutzern keine Karte angezeigt wird, in der sie zur Genehmigung aufgefordert werden, wenn dies bereits erfolgt ist, sondern stattdessen Informationen zum Zeitpunkt der Genehmigung der Anforderung und zur genehmigenden Person anzeigt.

Um einer adaptiven Karte die automatische Aktualisierung zu gestatten, definieren Sie ihre refresh-Eigenschaft, die eine action vom Typ Action.Execute sowie ein userIds-Array einbettet.

Eigenschaft Type Erforderlich BESCHREIBUNG
action "Action.Execute" Ja Muss eine Aktionsinstanz vom Typ "Action.Execute" sein.
userIds Array<string> Ja Ein Array von MRIs von Benutzern, für die die automatische Aktualisierung aktiviert sein muss.

WICHTIG: Wenn die Listeneigenschaft userIds nicht im Abschnitt refresh der Karte enthalten ist, wird die Karte bei der Anzeige NICHT automatisch aktualisiert. Stattdessen wird dem Benutzer eine Schaltfläche angezeigt, mit der er die Karte manuell aktualisieren kann. Der Grund dafür ist, dass Chats/Kanäle in Teams eine große Anzahl von Mitgliedern enthalten können. Wenn viele Mitglieder den Kanal gleichzeitig anzeigen, würde eine nicht an Bedingungen gebundene automatische Aktualisierung zu sehr vielen gleichzeitigen Aufrufen des Bots führen, was sich nicht skalieren ließe. Um das potenzielle Skalierungsproblem zu verringern, sollte die Eigenschaft userIds immer eingeschlossen werden, um zu identifizieren, welche Benutzer eine automatische Aktualisierung erhalten sollten, wobei aktuell maximal 60 Benutzer-IDs zulässig sind. Weitere Informationen finden Sie unter userIds in refresh (UserIds in der Aktualisierung).

Beachten Sie, dass die userIds-Eigenschaft in Outlook ignoriert und die refresh-Eigenschaft immer automatisch berücksichtigt wird. In Outlook gibt es kein Skalierungsproblem, da Benutzer die Karte in der Regel zu unterschiedlichen Zeitpunkten anzeigen.

Beispiel-JSON

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "originator":"c9b4352b-a76b-43b9-88ff-80edddaa243b",
  "version": "1.4",
  "refresh": {
    "action": {
      "type": "Action.Execute",
      "title": "Submit",
      "verb": "personalDetailsCardRefresh"
    },
    "userIds": []
  },
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    { 
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": "Action.Submit"
        }
      ]
    }
  ]
}

Wichtiger Hinweis für Entwickler von Outlook-Nachrichten, die Aktionen erfordern

Beim Entwickeln von Szenarien mit Outlook-Nachrichten, die Aktionen erfordern, muss die originator-Eigenschaft der adaptiven Karte angegeben werden. originator ist eine GUID (global eindeutiger Bezeichner), die generiert wird, wenn ein Bot den Outlook-Kanal abonniert. Sie wird von Outlook verwendet, um zu überprüfen, ob die adaptive Karte von einem autorisierten Bot gesendet wurde. Die adaptive Karte wird nicht in Outlook gerendert, wenn originator fehlt. originator wird in Teams ignoriert.

Aufrufaktivität adaptiveCard/action

Wenn eine Action.Execute im Client ausgeführt wird (unabhängig davon, ob es sich um die Aktualisierungsaktion oder eine Aktion handelt, die von einem Benutzer explizit durch Klicken auf eine Schaltfläche ausgeführt wird), wird ein neuer Typ von Aufrufaktivität – adaptiveCard/action – an Ihren Bot gesendet. Eine typische Anforderung der adaptiveCard/action-Aufrufaktivität sieht wie folgt aus:

Anforderungsformat

{ 
  "type": "invoke",
  "name": "adaptiveCard/action",

  // ... other properties omitted for brevity

  "value": { 
    "action": { 
      "type": "Action.Execute", 
      "id": "abc", 
      "verb": "def",
      "data": { ... } 
    },
    "trigger": "automatic | manual" 
  }
}
Feld Beschreibung
value.action Eine Kopie der Aktion, wie sie in der adaptiven Karte definiert ist. Wie bei Action.Submit enthält die data-Eigenschaft der Aktion die Werte der verschiedenen Eingaben auf der Karte, sofern vorhanden.
value.trigger Zeigt an, ob die Aktion explizit (durch den Benutzer, der auf eine Schaltfläche klickt) oder implizit (über automatische Aktualisierung) ausgelöst wurde.

Antwortformat

Wenn der Bot eine eingehende adaptiveCard/action-Aufrufaktivität verarbeitet hat (d. h., wenn der Bot-Code überhaupt an der Verarbeitung der Anforderung beteiligt war), muss der vom Bot zurückgegebene Statuscode der HTTP-Antwort gleich 200 und der Text der HTTP-Antwort wie folgt formatiert sein:

{ 
    "statusCode": <number (200 – 599)>, 
    "type": "<string>", 
    "value": "<object>"
}
Feld Beschreibung
statusCode Der HTTP-Antwortstatuscode 200 bedeutet NICHT notwendigerweise, dass der Bot die Anforderung erfolgreich verarbeiten konnte. Eine Clientanwendung MUSS immer die statucCode-Eigenschaft im Text der Antwort überprüfen, um zu erfahren, wie der Bot die Anforderung verarbeitet hat. statusCode ist eine Zahl zwischen 200 und 599, die HTTP-Statuscodewerte widerspiegelt und als Unterstatus für das Ergebnis des Bots dienen soll, der den Aufruf verarbeitet. Ein fehlender, Null- oder nicht definierter Wert für statusCode impliziert 200 (Erfolg).
type Ein Satz bekannter Zeichenfolgenkonstanten, der die erwartete Form der value-Eigenschaft beschreibt.
value Ein-Objekt, das für den Typ des Antworttexts spezifisch ist.

Unterstützte Statuscodes

In der folgenden Tabelle sind die zulässigen Werte für statusCode, type und value im Antworttext des Bots aufgeführt:

Statuscode Typ Werteschema Hinweise
200 application/vnd.microsoft.card.adaptive Adaptive Card Die Anforderung wurde erfolgreich verarbeitet, und die Antwort enthält eine adaptive Karte, die der Client anstelle der aktuellen anzeigen soll.
200 application/vnd.microsoft.activity.message string Die Anforderung wurde erfolgreich verarbeitet, und die Antwort enthält eine Meldung, die der Client anzeigen soll.
400 application/vnd.microsoft.error Fehlerobjekt (ZU ERLEDIGEN: Link erforderlich) Die eingehende Anforderung war ungültig.
401 application/vnd.microsoft.activity.loginRequest OAuthCard (ZU ERLEDIGEN: Link erforderlich) Der Client muss den Benutzer zur Authentifizierung auffordern.
401 application/vnd.microsoft.error.inccorectAuthCode NULL Der vom Client übergebene Authentifizierungszustand war falsch, und die Authentifizierung ist fehlgeschlagen.
412 application/vnd.microsoft.error.preconditionFailed Fehlerobjekt (ZU ERLEDIGEN: Link erforderlich) Der Authentifizierungsfluss für einmaliges Anmelden (SSO) ist fehlgeschlagen.
500 application/vnd.microsoft.error Fehlerobjekt (ZU ERLEDIGEN: Link erforderlich) Ein unerwarteter Fehler ist aufgetreten.

Zusammenfassung: Verwenden des universellen Bot-Aktionsmodells

  1. Verwenden Sie Action.Execute anstelle von Action.Submit. Um ein vorhandenes Szenario in Teams zu aktualisieren, ersetzen Sie alle Instanzen von Action.Submit durch Action.Execute. Informationen zum Ugrade eines vorhandenen Szenarios in Outlook finden Sie weiter unten im Abschnitt „Abwärtskompatibilität“.
  2. Fügen Sie für Karten, die in Outlook angezeigt werden sollen, das originator-Feld hinzu. Informationen finden Sie im obigen JSON-Beispiel.
  3. Fügen Sie Ihrer adaptiven Karte eine refresh-Klausel hinzu, wenn Sie den automatischen Aktualisierungsmechanismus nutzen möchten, oder wenn Ihr Szenario benutzerspezifische Ansichten erfordert. Achten Sie unbedingt darauf, die userIds-Eigenschaft anzugeben, um zu bestimmen, welche Benutzer (maximal 60) automatische Updates erhalten.
  4. Behandeln von adaptiveCard/action-Aufrufanforderungen in Ihrem Bot
  5. Immer, wenn Ihr Bot eine neue Karte als Ergebnis der Verarbeitung von Action.Executezurückgeben muss, können Sie den Kontext der Aufrufanforderung verwenden, um Karten zu generieren, die speziell für einen bestimmten Benutzer erstellt wurden. Stellen Sie sicher, dass die Antwort dem oben definierten Antwortschema entspricht.

Abwärtskompatibilität

Outlook

Das neue universelle Action.Execute-Aktionsmodell ist eine Abkehr vom Action.Http-Aktionsmodell, das zurzeit von Outlook-Nachrichten, die Aktionen erfordern, verwendet wird, in dem Aktionen in der adaptiven Karte als explizite HTTP-Aufrufe codiert sind. Das Action.Execute-Modell ermöglicht es Entwicklern, Szenarien zu implementieren, die sowohl in Outlook als auch Teams „einfach funktionieren“. Szenarien mit Aktion erfordernden Nachrichten können entweder das Action.Http-Modell oder das neue Action.Execute-Modell verwenden, aber nicht beide. Szenarien, die das universelle Action.Execute-Modell verwenden, müssen als Bots implementiert werden und den Outlook Actionable Messages-Kanal abonnieren.

Wichtige Hinweise

  • Szenarien, die mithilfe des universellen Action.Execute-Modells implementiert werden, sind nicht kompatibel mit älteren Versionen von Outlook.
  • Es wird daran gearbeitet, vorhandenen Szenarien mit adaptiven Karten die nahtlose Migration zum universellenAction.Execute-Modell zu ermöglichen.

Teams

Damit Ihre Karten abwärtskompatibel sind und für Benutzer älterer Versionen von Teams funktionieren, sollten ihre Action.Execute-Aktionen eine fallback-Eigenschaft enthalten, die als Action.Submit definiert ist. Ihr Bot sollte so codiert sein, dass er sowohl Action.Execute als auch Action.Submit verarbeiten kann. Beachten Sie, dass es nicht möglich ist, dass Ihr Bot bei Verarbeitung einer Action.Submit eine neue Karte zurückgibt, sodass das Fallbackverhalten über Action.Submit eine Beeinträchtigung der Endbenutzererfahrung zur Folge haben wird.

Wichtiger Hinweis

Einige ältere Teams-Clients unterstützen die fallback-Eigenschaft nicht, wenn sie nicht in einer ActionSet umschlossen sind. Damit es auf solchen Clients zu keinen Abbrüchen kommt, wird dringend empfohlen, dass Sie alle Ihre Action.Execute mit ActionSet umschließen. Im folgenden Beispiel finden Sie Informationen zum Umschließen von Action.Execute mit ActionSet.

Beachten Sie im folgenden Beispiel, dass die version-Eigenschaft der Karte auf 1.2 festgelegt und die Action.Execute mit einer Action.Submit als fallback definiert ist. Wenn die Action.Execute in einem Teams-Client gerendert wird, der Adaptive Karten 1.4 unterstützt, wird sie erwartungsgemäß gerendert und funktioniert auch dementsprechend. In Teams-Clients, die Adaptive Karten 1.4 nicht unterstützen, wird Action.Submit anstelle von Action.Execute gerendert.

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.2",
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": {
            "type": "Action.Submit",
            "title": "Submit"
          }  
        }
      ]
    }
  ]
}

References