Übersicht über das universelle Aktionsmodell

Artikel
04/29/2024

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.

Adaptive Karten sind plattformunabhängige Ausschnitte der Benutzeroberfläche, die in einem einfachen JSON-Format erstellt wurden und von Apps und Diensten freigegeben werden können. Adaptive Karten passen sich nicht nur an das Aussehen und Verhalten des Hosts an, sondern bieten auch umfangreiche Interaktionsfunktionen.

Da adaptive Karten immer beliebter wurden, begannen verschiedene Hosts, verschiedene Aktionsmodelle zu unterstützen, was zur Fragmentierung führte. Um dieses Problem zu lösen, arbeiteten die Teams-, Outlook- und Adaptive Karten-Teams daran, ein neues universelles Bot-Aktionsmodell zu erstellen, das hostübergreifend kompatibel ist. Diese Bemühungen führten zu Folgendem:

Die Generalisierung von Bots und bot Framework als Möglichkeit zum Implementieren adaptiver Karten-basierter Szenarien für Outlook (Aktionen erfordernde Nachrichten) und Teams (Bots)
Action.Execute als Ersatz für sowohl Action.Http (derzeit von Aktionen erfordernde Nachrichten verwendet) als Action.Submit auch (derzeit von Bots verwendet)

Schema

Wichtig

Das universelle Aktionsmodell wird in adaptiver Karte Schemaversion 1.4 und höher eingeführt. Um diese neuen Funktionen verwenden zu können, muss die version -Eigenschaft Ihrer adaptiven Karte auf 1.4 oder höher festgelegt werden, wie in den folgenden Beispielen gezeigt.

Action.Execute

Verwenden Sie Action.Execute beim Erstellen adaptiver Karten für Outlook anstelle von Action.Http. Hier sehen Sie ein Beispiel für adaptive Karte, die in der JSON-Nutzlast verwendet Action.Execute wird.

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "originator":"c9b4352b-a76b-43b9-88ff-80edddaa243b",
  "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"
        }
      ]
    }
  ]
}

Eigenschaften

Eigenschaft	Typ	Erforderlich	Beschreibung
type	`string`	Ja	Muss `Action.Execute` sein.
Verb	`string`	Nein	Eine praktische Zeichenfolge, die vom Entwickler 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 ausgeblendete Eigenschaften.
title	`string`	Nein	Bezeichnung für Schaltfläche oder Link, die diese Aktion darstellt.
iconUrl	`uri`	Nein	Optionales Symbol, das in der Aktion in Verbindung mit dem Titel angezeigt werden soll. Unterstützt daten-URI in adaptiven Karten, Version 1.2 und höher
style	`ActionStyle`	Nein	Steuert den Stil einer Aktion, der 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.
Erfordert	`Dictionary<string>`	Nein	Eine Reihe von Schlüssel-Wert-Paaren, die Features angeben, die das Element mit der entsprechenden Mindestversion erfordert. Wenn ein Feature fehlt oder eine unzureichende Version aufweist, wird ein Fallback ausgelöst.

Aktualisierungsmechanismus

Neben Action.Executewird jetzt ein neuer Aktualisierungsmechanismus unterstützt, der es ermöglicht, adaptive Karten zu erstellen, die zum Zeitpunkt der Anzeige automatisch aktualisiert werden. Dadurch wird sichergestellt, dass Benutzer immer aktuelle Daten sehen. Damit eine adaptive Karte in Outlook automatisch aktualisiert werden kann, definieren Sie die - refresh Eigenschaft, die eine action vom Typ Action.Executeeinbettet.

Eigenschaft	Typ	Erforderlich	Beschreibung
action	`"Action.Execute"`	Ja	Muss eine Aktion instance vom Typ `"Action.Execute"`sein.
userIds	`Array<string>`	Ja	Ein Array mit Nachrichtenressourcenbezeichner (`MRI`) von Benutzern, für die die automatische Aktualisierung in Teams aktiviert werden muss. Weitere Informationen zu Teams finden Sie unter Benutzer-IDs in der Aktualisierung . Beachten Sie, dass die `userIds` Eigenschaft in Outlook ignoriert wird und die `refresh` Eigenschaft immer automatisch berücksichtigt wird.

JSON-Beispiel

{
  "$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"
        }
      ]
    }
  ]
}

Abwärtskompatibilität

Das neue Action.Execute universelle Aktionsmodell ist eine Abkehr vom Aktionsmodell, das Action.Http in adaptiver Karte Version unter 1.4 verwendet wird, wobei Aktionen in der adaptiven Karte als explizite HTTP-Aufrufe codiert werden. Das Action.Execute-Modell ermöglicht es Entwicklern, Szenarien zu implementieren, die sowohl in Outlook als auch in Teams funktionieren. Nachrichtenszenarien mit Aktionen können entweder das Action.Http Modell oder das neue Action.Execute Modell verwenden, aber nicht beides. Szenarien, die das universelle Action.Execute Modell verwenden, müssen als Bots implementiert werden und den Outlook-Kanal für aktionenfähige Nachrichten abonnieren.

Codebeispiele

Nachdem Sie die Dokumentation durchgegangen haben, können Sie mit einigen Beispielen beginnen.

Freigeben über