Universelles Aktionsmodell

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

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

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.

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

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

Unterstützte Statuscodes

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

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

• Dokumentation zum universellen Aktionsmodell in Teams
• Adaptive Karten @ Microsoft Build 2020
• Adaptive Karten @ Ignite 2020