Definieren von Aktionsbefehlen für Nachrichtenerweiterungen

Artikel
06/14/2023

Wichtig

Die Codebeispiele in diesem Abschnitt basieren auf Version 4.6 und höheren Versionen des Bot Framework SDK. Wenn Sie nach Dokumentation zu früheren Versionen suchen, lesen Sie den Abschnitt Nachrichtenerweiterungen – v3 SDK im Ordner Ressourcen der Dokumentation.

Hinweis

Wenn eine Nachrichtenaktion initiiert wird, werden keine Anlagendetails im Rahmen der turncontext Aufrufaktivität gesendet.

Aktionsbefehle ermöglichen es Ihnen, Ihren Benutzern ein modales Popupfenster zu präsentieren, das als Aufgabenmodul in Teams bezeichnet wird. Das Aufgabenmodul sammelt Informationen oder zeigt diese an, verarbeitet die Interaktion und sendet die Informationen an Teams zurück. In diesem Dokument erfahren Sie, wie Sie Speicherorte zum Aufrufen des Aktionsbefehls auswählen, ein Aufgabenmodul erstellen, die endgültige Nachricht oder Karte senden sowie einen Aktionsbefehl mit App Studio oder manuell erstellen.

Bevor Sie den Aktionsbefehl erstellen, müssen Sie die folgenden Faktoren festlegen:

Von wo kann der Aktionsbefehl ausgelöst werden?
Wie wird das Aufgabenmodul erstellt?
Wird die endgültige Nachricht oder Karte von einem Bot an den Kanal gesendet, oder wird die Nachricht oder Karte in den Bereich zum Verfassen von Nachrichten eingefügt, damit der Benutzer die Nachricht bzw. Karte übermitteln kann?

Im folgenden Video erfahren Sie, wie Sie Aktionsbefehle für nachrichtenerweiterungen definieren:

Auswählen von Speicherorten zum Aufrufen von Aktionsbefehlen

Zuerst müssen Sie den Speicherort festlegen, von dem aus der Aktionsbefehl aufgerufen werden muss. Durch Angabe des context im App-Manifests kann der Befehl von einem oder mehreren der folgenden Speicherorte aufgerufen werden:

Bereich zum Verfassen von Nachrichten: die Schaltflächen am unteren Rand des Bereichs zum Verfassen von Nachrichten.

Befehlskontext = compose
Befehlsfeld: Nach @mentioning Ihrer App im Befehlsfeld.

Befehlskontext = commandBox

Hinweis

Wenn die Nachrichtenerweiterung über das Befehlsfeld aufgerufen wird, können Sie nicht mit einer Botnachricht antworten, die direkt in die Unterhaltung eingefügt wurde.
Nachricht: direkt aus einer vorhandenen Nachricht über das ... Überlaufmenü einer Nachricht.

Befehlskontext = message
Hinweis
- Der anfängliche Aufruf des Bots enthält ein JSON-Objekt, das die Nachricht enthält, aus der er aufgerufen wurde. Sie können die Nachricht verarbeiten, bevor Sie ein Aufgabenmodul präsentieren.
- Wenn der Benutzer aus den Auslassungspunkten ... auswählt, wird ein Überlaufmenü angezeigt. Nachrichtenaktionen für Apps, die Sie für Ihre organization oder Apps von Drittanbietern erstellt haben, werden jedoch standardmäßig nicht angezeigt. Nachdem der Benutzer Weitere Aktionen ausgewählt hat, kann er die Nachrichtenaktionen anzeigen und die erforderliche Option auswählen. Die entsprechende Meldungsaktion wird im Überlaufmenü angezeigt. Im Überlaufmenü werden die drei letzten Nachrichtenaktionen angezeigt. Sie können die anzuzeigende Meldungsaktion nicht anheften.

In der folgenden Abbildung werden die Speicherorte angezeigt, von denen der Aktionsbefehl aufgerufen wird:

Speicherorte zum Aufrufen von Aktionsbefehlen

Um benutzerdefinierte Optionen unter Weitere Optionen (...) oder Weitere Aktionen hinzuzufügen, fügen Sie Ihre Befehle in composeExtensions der -Eigenschaft des App-Manifestschemas hinzu. Weitere Informationen finden Sie unter Hinzufügen des Aktionsbefehls zu Ihrem App-Manifest.

Auswählen, wie Sie Ihr Aufgabenmodul erstellen möchten

Sie müssen nicht nur auswählen, von wo aus der Befehl aufgerufen werden kann, sondern auch, wie das Formular im Aufgabenmodul für Ihre Benutzer aufgefüllt werden soll. Sie haben die folgenden drei Optionen zum Erstellen des Formulars, das innerhalb des Aufgabenmoduls gerendert wird:

Statische Parameterliste: Dies ist die einfachste Methode. Sie können eine Liste von Parametern in Ihrem App-Manifest definieren, die der Teams-Client rendert, aber in diesem Fall nicht die Formatierung steuern.
Adaptive Karte: Sie können eine adaptive Karte verwenden, die eine bessere Kontrolle über die Benutzeroberfläche bietet, Sie aber weiterhin auf die verfügbaren Steuerelemente und Formatierungsoptionen beschränkt.
Eingebettete Webansicht: Sie können eine benutzerdefinierte Webansicht in das Aufgabenmodul einbetten, um eine vollständige Kontrolle über die Benutzeroberfläche und die Steuerelemente zu haben.

Wenn Sie das Aufgabenmodul mit einer statischen Liste von Parametern erstellen möchten und der Benutzer das Aufgabenmodul übermittelt, wird die Nachrichtenerweiterung aufgerufen. Wenn Sie eine eingebettete Webansicht oder eine adaptive Karte verwenden, muss Ihre Nachrichtenerweiterung ein anfängliches Aufrufereignis vom Benutzer behandeln, das Aufgabenmodul erstellen und an den Client zurücksenden.

Auswählen, wie die endgültige Nachricht gesendet wird

In den meisten Fällen führt der Aktionsbefehl dazu, dass eine Karte in das Feld zum Verfassen von Nachrichten eingefügt wird. Der Benutzer kann sie in den Kanal oder Chat senden. In diesem Fall stammt die Nachricht vom Benutzer, und der Bot kann die Karte nicht weiter bearbeiten oder aktualisieren.

Wenn die Nachrichtenerweiterung über das Feld zum Verfassen oder direkt aus einer Nachricht aufgerufen wird, kann Ihr Webdienst die endgültige Antwort direkt in den Kanal oder Chat einfügen. In diesem Fall stammt die adaptive Karte vom Bot, der Bot aktualisiert sie und antwortet bei Bedarf auf den Unterhaltungsthread. Sie müssen das bot -Objekt dem App-Manifest hinzufügen, indem Sie dieselbe ID verwenden und die entsprechenden Bereiche definieren.

Hinzufügen des Aktionsbefehls zum App-Manifest

Um den Aktionsbefehl zum App-Manifest hinzuzufügen, müssen Sie der obersten Ebene des App-Manifest-JSON ein neues Objekt composeExtensions hinzufügen. Dazu können Sie eine der folgenden Methoden verwenden:

Erstellen eines Aktionsbefehls mithilfe des Entwicklerportals
Manuelles Erstellen eines Aktionsbefehls

Erstellen eines Aktionsbefehls mithilfe des Entwicklerportals

Sie können einen Aktionsbefehl über das Entwicklerportal erstellen.

Hinweis

Die Voraussetzung zum Erstellen eines Aktionsbefehls ist, dass Sie bereits eine Nachrichtenerweiterung erstellt haben. Informationen zum Erstellen einer Nachrichtenerweiterung finden Sie unter Erstellen einer Nachrichtenerweiterung.

So erstellen Sie einen Aktionsbefehl:

Öffnen Sie das Entwicklerportal über den Microsoft Teams-Client, und wählen Sie die Registerkarte Apps aus. Wenn Sie Ihr App-Paket bereits im Entwicklerportal erstellt haben, wählen Sie aus der Liste aus. Wenn Sie kein App-Paket erstellt haben, importieren Sie ein vorhandenes Paket.
Wählen Sie nach dem Importieren eines App-Pakets unter App-Featuresdie Option Nachrichtenerweiterungen aus.
Um eine Nachrichtenerweiterung zu erstellen, benötigen Sie einen von Microsoft registrierten Bot. Sie können entweder einen vorhandenen Bot verwenden oder einen neuen Bot erstellen. Wählen Sie die Option Neuen Bot erstellen aus, geben Sie dem neuen Bot einen Namen, und wählen Sie dann Erstellen aus.
Um einen vorhandenen Bot zu verwenden, wählen Sie Vorhandenen Bot auswählen und die vorhandenen Bots aus der Dropdownliste aus, oder wählen Sie Bot-ID eingeben aus, wenn Sie bereits eine Bot-ID erstellt haben.
Wählen Sie den Bereich des Bots und dann Speichern aus.
Wählen Sie im Abschnitt Befehl die Option Befehl hinzufügen aus, um die Befehle einzuschließen, die über das Verhalten der Nachrichtenerweiterung entscheiden.
Wählen Sie Aktion und dann Parametertyp aus.
Geben Sie Befehls-ID, Befehlstitel und Befehlsbeschreibung ein.
Geben Sie alle Parameter ein, und wählen Sie den Typ der Eingabe aus der Dropdownliste aus.
Wählen Sie unter Vorschaulinksdie Option Domäne hinzufügen aus.
Geben Sie eine gültige Domäne ein, und wählen Sie dann Hinzufügen aus.
Wählen Sie Speichern aus.

So fügen Sie zusätzliche Parameter hinzu

Wählen Sie im Befehlsabschnitt die Auslassungspunkte und dann Parameter bearbeiten aus.
Wählen Sie Parameter hinzufügen aus, und geben Sie alle Parameter ein.

Manuelles Erstellen eines Aktionsbefehls

Zum manuellen Hinzufügen des Befehls für die aktionsbasierte Nachrichtenerweiterung zum App-Manifest müssen Sie dem Array von Objekten composeExtensions.commands die folgenden Parameter hinzufügen:

Eigenschaftenname	Zweck	Pflichtfeld?	Minimale Manifestversion
`id`	Diese Eigenschaft ist eine eindeutige ID, die Sie diesem Befehl zuweisen. Die Benutzeranforderung enthält diese ID.	Ja	1.0
`title`	Diese Eigenschaft ist ein Befehlsname. Dieser Wert wird auf der Benutzeroberfläche angezeigt.	Ja	1.0
`type`	Diese Eigenschaft muss eine `action` sein.	Nein	1.4
`fetchTask`	Diese Eigenschaft ist für eine adaptive Karte oder eingebettete Webansicht für Ihr Aufgabenmodul auf `false` und für eine statische Liste von Parametern oder beim Laden der Webansicht durch eine `taskInfo` auf `true` festgelegt.	Nein	1.4
`context`	Diese Eigenschaft ist ein optionales Array von Werten, das definiert, von wo aus die Nachrichtenerweiterung aufgerufen wird. Die möglichen Werte sind `message`, `compose` oder `commandBox`. Der Standardwert ist `["compose", "commandBox"]`.	Nein	1,5

Wenn Sie eine statische Liste von Parametern verwenden, müssen Sie auch die folgenden Parameter hinzufügen:

Eigenschaftenname	Zweck	Erforderlich?	Minimale Manifestversion
`parameters`	Diese Eigenschaft beschreibt die statische Liste von Parametern für den Befehl. Nur verwenden, wenn `fetchTask` gleich `false` ist.	Nein	1.0
`parameter.name`	Diese Eigenschaft beschreibt den Namen des Parameters. Dies wird in der Benutzeranforderung an Ihren Dienst gesendet.	Ja	1.0
`parameter.description`	Diese Eigenschaft beschreibt den Zweck des Parameters oder ein Beispiel für den Wert, der bereitgestellt werden soll. Dieser Wert wird auf der Benutzeroberfläche angezeigt.	Ja	1.0
`parameter.title`	Diese Eigenschaft ist ein kurzer benutzerfreundlicher Parametertitel oder eine Bezeichnung.	Ja	1.0
`parameter.inputType`	Diese Eigenschaft ist auf den Typ der erforderlichen Eingabe festgelegt. Folgende Werte stehen zur Verfügung: `text`, `textarea`, `number`, `date`, `time`, `toggle`. Der Standardwert ist `text`.	Nein	1.4

Wenn Sie eine eingebettete Webansicht verwenden, können Sie optional das taskInfo -Objekt hinzufügen, um Ihre Webansicht abzurufen, ohne ihren Bot direkt aufzurufen. Wenn Sie diese Option auswählen, ist das Verhalten ähnlich wie bei der Verwendung einer statischen Liste von Parametern. Die erste Interaktion mit Ihrem Bot besteht darin, auf die Aufgabenmodul-Sendeaktion zu reagieren. Wenn Sie ein taskInfo -Objekt verwenden, müssen Sie den fetchTask Parameter auf falsefestlegen.

Eigenschaftenname	Zweck	Erforderlich?	Minimale Manifestversion
`taskInfo`	Geben Sie das Aufgabenmodul an, das vorab geladen werden soll, wenn Sie einen Nachrichtenerweiterungsbefehl verwenden.	Nein	1.4
`taskInfo.title`	Titel des anfänglichen Aufgabenmoduls.	Nein	1.4
`taskInfo.width`	Aufgabenmodulbreite: entweder eine Angabe in Pixeln oder ein Standardlayout, z. B. `large`, `medium` oder `small`.	Nein	1.4
`taskInfo.height`	Aufgabenmodulhöhe: entweder eine Angabe in Pixeln oder ein Standardlayout, z. B. `large`, `medium` oder `small`.	Nein	1.4
`taskInfo.url`	Anfängliche Webansichts-URL.	Nein	1.4

Beispiel für ein App-Manifest

Dieser Abschnitt ist kein Beispiel für das vollständige Manifest. Im Folgenden finden Sie ein Beispiel für ein composeExtensions Objekt, das zwei Aktionsbefehle definiert:

...
"composeExtensions": [
  {
    "botId": "c8fa3cf6-b1f0-4ba8-a5bf-a241bc29adf3",
    "commands": [
      {
        "id": "To do",
        "type": "action",
        "title": "Create To do",
        "description": "Create a To do",
        "initialRun": true,
        "fetchTask": false,
        "context": [
          "commandBox",
          "compose"
        ],
        "parameters": [
          {
            "name": "Name",
            "title": "Title",
            "description": "To do Title",
            "inputType": "text"
          },
          {
            "name": "Description",
            "title": "Description",
            "description": "Description of the task",
            "inputType": "textarea"
          },
          {
            "name": "Date",
            "title": "Date",
            "description": "Due date for the task",
            "inputType": "date"
          }
        ]
      }
    ],
    "canUpdateConfiguration": true,
    "messageHandlers": [
      {
        "type": "link",
        "value": {
          "domains": [
            "yourapp.onmicrosoft.com"
          ]
        }
      }
    ]
  }
]
...

Weitere Informationen finden Sie unter App-Manifestschema.

Codebeispiel

Beispielname	Beschreibung	.NET	Node.js	Manifest
Teams-Nachrichtenerweiterungen – Aktion	In diesem Beispiel wird gezeigt, wie Sie Aktionsbefehle definieren, ein Aufgabenmodul erstellen und auf eine Aktion zum Übermitteln von Aufgabenmodulen reagieren.	View	View	View
Vorschau der Aktion "Nachrichtenerweiterung"	In diesem Beispiel wird gezeigt, wie Sie die Aktionsvorschau in Messagingerweiterungen mit Bot Framework v4 verwenden.	View	View	View

Schrittweise Anleitung

Befolgen Sie die schrittweise Anleitung zum Erstellen einer aktionsbasierten Teams-Nachrichtenerweiterung.

Nächster Schritt

Wenn Sie eine adaptive Karte oder eine eingebettete Webansicht ohne Objekt taskInfo verwenden, besteht der nächste Schritt darin:

Aufgabenmodul erstellen und damit reagieren

Wenn Sie die Parameter oder eine eingebettete Webansicht mit einem taskInfo -Objekt verwenden, besteht der nächste Schritt darin:

Auf das Senden des Aufgabenmoduls reagieren