Definieren von Aktions Befehlen für die Nachrichten ErweiterungDefine messaging extension action commands

Wichtig

Die Codebeispiele in diesem Abschnitt basieren auf 4,6 und höheren Versionen des bot Framework SDK.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Wenn Sie nach einer Dokumentation für frühere Versionen suchen, lesen Sie den Abschnitt Messaging Extensions-V3 SDK im Ordner Resources der Dokumentation.If you're looking for documentation for earlier versions, see the Messaging Extensions - v3 SDK section in the Resources folder of the documentation.

Aktionsbefehle ermöglichen es Ihnen, Ihren Benutzern ein modales Popup (in Teams als Aufgabenmodul bezeichnet) zu präsentieren, um Informationen zu sammeln oder anzuzeigen, dann ihre Interaktion zu verarbeiten und Informationen in Teams zurückzuschicken.Action commands allow you present your users with a modal popup (called a task module in Teams) to collect or display information, then process their interaction and send information back to Teams. Vor dem Erstellen des Befehls müssen Sie Folgendes entscheiden:Before creating your command you'll need to decide:

  1. Woher kann der Befehl Action ausgelöst werden?Where can the action command be triggered from?
  2. Wie wird das Aufgabenmodul erstellt?How will the task module be created?
  3. Wird die letzte Nachricht oder Karte von einem bot an den Kanal gesendet, oder wird die Nachricht oder Karte in den Verfassen-Nachrichtenbereich eingefügt, damit der Benutzer übermitteln kann?Will the final message or card be sent to the channel from a bot, or will the message or card be inserted into the compose message area for the user to submit?

Auswählen eines Aktionsbefehls zum Aufrufen von SpeicherortenChoose action command invoke locations

Das erste, was Sie entscheiden müssen, ist, wo Ihr Aktionsbefehl (oder genauer gesagt, aufgerufen) aus ausgelöst werden kann.The first thing you need to decide is where your action command can be triggered (or more specifically, invoked) from. Durch Angeben des context in Ihrem App-Manifest kann der Befehl von einem oder mehreren der folgenden Speicherorte aufgerufen werden:By specifying the context in your app manifest, your command can be invoked from one or more of the following locations:

  • Die Schaltflächen am unteren Rand des Bereichs zum Verfassen von Nachrichten.The buttons at the bottom of the compose message area.
  • Durch @mentioning Ihrer APP im Befehlsfeld.By @mentioning your app in the command box. Hinweis: Sie können nicht mit einer bot-Nachricht antworten, die direkt in die Unterhaltung eingefügt wird, wenn Ihre Messaging-Erweiterung aus dem Befehlsfeld aufgerufen wird.Note: You cannot respond with a bot message inserted directly into the conversation if your messaging extension is invoked from the command box.
  • Direkt aus einer vorhandenen Nachricht über die... Überlaufmenü in einer Nachricht.Directly from an existing message via the ... overflow menu on a message. Hinweis: die anfängliche Invoke-Funktion für Ihren bot umfasst ein JSON-Objekt, das die Nachricht enthält, aus der es aufgerufen wurde, die Sie verarbeiten können, bevor Sie Sie mit einem Aufgabenmodul präsentieren.Note: The initial invoke to your bot will include a JSON object containing the message from which it was invoked, which you can process before presenting them with a task module.

Auswählen der Vorgehensweise zum Erstellen des AufgabenmodulsChoose how to build your task module

Neben der Auswahl, aus der der Befehl aufgerufen werden kann, müssen Sie auch auswählen, wie das Formular im Aufgabenmodul für die Benutzer aufgefüllt werden soll.In addition to choosing where your command can be invoked from, you must also chose how to populate the form in the task module for your users. Sie haben drei Optionen zum Erstellen des Formulars, das im Aufgabenmodul gerendert wird:You have three options for creating the form that is rendered inside the task module:

  • Statische Liste von Parametern -Dies ist die einfachste Option.Static list of parameters - This is the simplest option. Sie können eine Liste von Parametern (Eingabefelder) in Ihrem App-Manifest definieren, das vom Microsoft Teams-Client gerendert wird.You can define a list of parameters (input fields) in your app manifest the Teams client will render. Mit dieser Option können Sie die Formatierung nicht steuern.You cannot control the formatting with this option.
  • Adaptive Karte – Sie können eine Adaptive Karte verwenden, die eine bessere Kontrolle über die Benutzeroberfläche bietet, Sie jedoch immer noch auf die verfügbaren Steuerelemente und Formatierungsoptionen beschränkt.Adaptive card - You can choose to use an adaptive card, which provides greater control over the UI, but still limits you on the available controls and formatting options.
  • Eingebettete Webansicht : Wenn Sie die vollständige Kontrolle über die Benutzeroberfläche und die Steuerelemente benötigen, können Sie eine benutzerdefinierte Webansicht im Aufgabenmodul einbetten.Embedded web view - If you need complete control over the UI and controls, you can choose to embed a custom web view in the task module.

Wenn Sie Ihr Aufgabenmodul mit einer statischen Liste von Parametern erstellen, wird der erste Aufruf Ihrer Messaging Erweiterung angezeigt, wenn ein Benutzer den Aufgabenmodul übermittelt.If you choose to create your task module with a static list of parameters, the first call to your messaging extension will be when a user submits the task module. Bei Verwendung einer eingebetteten Webansicht oder einer adaptiven Karte muss Ihre Messaging Erweiterung ein anfängliches Invoke-Ereignis des Benutzers verarbeiten, den Aufgabenmodul erstellen und zurück an den Client zurückgeben.When using an embedded web view or an adaptive card, your messaging extension will need to handle an initial invoke event from the user, create the task module, and return it back to the client.

Auswählen, wie die abschließende Nachricht gesendet wirdChoose how the final message will be sent

In den meisten Fällen führt Ihr Aktionsbefehl dazu, dass eine Karte in das Meldungsfeld verfassen eingefügt wird.In most cases, your action command will result in a card inserted into the compose message box. Ihr Benutzer kann dann beschließen, ihn in den Kanal oder Chat zu senden.Your user can then decide to send it into the channel or chat. Die Nachricht kommt in diesem Fall vom Benutzer, und Ihr Bot kann die Karte nicht weiter bearbeiten oder aktualisieren.The message in this case comes from the user, and your bot will not be able to edit or update the card further.

Wenn Ihre Messaging Erweiterung aus dem Feld Verfassen oder direkt aus einer Nachricht ausgelöst wird, kann Ihr Webdienst die abschließende Antwort direkt in den Kanal oder Chat einfügen.If your messaging extension is triggered from the compose box or directly from a message, your web service can insert the final response directly into the channel or chat. In diesem Fall kommt die Adaptive Karte aus dem bot, der Bot kann Sie aktualisieren, und der Bot kann bei Bedarf auch auf den Gesprächsfaden Antworten.In this case, the adaptive card comes from the bot, the bot will be able to update it, and the bot can also reply to the conversation thread if needed. Sie müssen das bot Objekt Ihrem App-Manifest mit derselben ID hinzufügen und die entsprechenden Bereiche definieren.You will need to add the bot object to your app manifest using the same Id and defining the appropriate scopes.

Hinzufügen des Befehls zum App-ManifestAdd the command to your app manifest

Nachdem Sie sich entschieden haben, wie Benutzer mit Ihrem Aktionsbefehl interagieren sollen, ist es an der Zeit, diese dem App-Manifest hinzuzufügen.Now that you've decided how users will interact with your action command, it is time to add it to your app manifest. Zu diesem Zweck fügen Sie ein neues composeExtension Objekt zur obersten Ebene des JSON-App-Manifests hinzu.To do this you'll add a new composeExtension object to the top level of your app manifest JSON. Sie können dies entweder mit Hilfe von App Studio oder manuell tun.You can either do so with the help of App Studio, or manually.

Erstellen eines Befehls mit App StudioCreate a command using App Studio

In den folgenden Schritten wird davon ausgegangen, dass Sie bereits eine Messaging Erweiterung erstellthaben.The following steps assume you've already created a messaging extension.

  1. Öffnen Sie auf dem Microsoft Teams-Client App Studio , und wählen Sie die Registerkarte Manifest-Editor aus.From the Microsoft Teams client, open App Studio and select the Manifest Editor tab.
  2. Wenn Sie Ihr App-Paket bereits in App Studio erstellt haben, wählen Sie es aus der Liste aus.If you've already created your app package in App Studio, chose it from the list. Wenn dies nicht der Fall ist, können Sie ein vorhandenes App-Paket importieren.If not, you can import an existing app package.
  3. Klicken Sie im Abschnitt Command auf die Schaltfläche Hinzufügen .Click the Add button in the Command section.
  4. Wählen Sie Benutzer erlauben, Aktionen in externen Diensten während innerhalb von Teams auszulösen.Choose Allow users to trigger actions in external services while inside of Teams.
  5. Wenn Sie zum Erstellen des Aufgabenmoduls eine statische Gruppe von Parametern verwenden möchten, wählen Sie diese Option aus.If you want to use a static set of parameters to create your task module, select that option. Andernfalls wählen Sie aus, um einen dynamischen Parametersatz aus Ihrem bot abzurufen.Otherwise, choose to Fetch a dynamic set of parameters from your bot.
  6. Fügen Sie eine Befehls-ID und einen Titelhinzu.Add a Command Id and a Title.
  7. Wählen Sie aus, wo der Aktionsbefehl ausgelöst werden soll.Select where you want your action command to be triggered from.
  8. Wenn Sie Parameter für Ihr Aufgabenmodul verwenden, fügen Sie das erste hinzu.If you're using parameters for your task module, add the first one.
  9. Click SaveClick Save
  10. Wenn Sie weitere Parameter hinzufügen möchten, klicken Sie im Abschnitt Parameters auf die Schaltfläche Hinzufügen , um Sie hinzuzufügen.If you need to add more parameters, click the Add button in the Parameters section to add them.

Manuelles Erstellen eines BefehlsManually create a command

Wenn Sie den Aktions basierten Messaging Erweiterungs Befehl Ihrem App-Manifest manuell hinzufügen möchten, müssen Sie dem Array von Objekten die Parameter "folgt" hinzufügen composeExtension.commands .To manually add your action-based messaging extension command to your app manifest, you'll need to add the follow parameters to your composeExtension.commands array of objects.

EigenschaftennameProperty name ZweckPurpose Pflichtfeld?Required? Minimale ManifestversionMinimum manifest version
id Eindeutige ID, die Sie diesem Befehl zuweisen.Unique ID that you assign to this command. Diese ID wird von der Benutzeranforderung eingeschlossen.The user request will include this ID. JaYes 1.01.0
title Befehlsname.Command name. Dieser Wert wird auf der Benutzeroberfläche angezeigt.This value appears in the UI. JaYes 1.01.0
type Muss action sein.Must be action NeinNo 1.41.4
fetchTask true für eine Adaptive Karte oder eingebettete Webansicht für Ihr Aufgabenmodul, false für eine statische Liste von Parametern oder beim Laden der Webansicht durch einen taskInfotrue for an adaptive card or embedded web view for your task module, false for a static list of parameters or when loading the web view by a taskInfo NeinNo 1.41.4
context Optionales Array von Werten, das definiert, woher die Messaging Erweiterung aufgerufen werden kann.Optional array of values that defines where the messaging extension can be invoked from. Mögliche Werte sind message , compose oder commandBox .Possible values are message, compose, or commandBox. Der Standardwert lautet ["compose", "commandBox"].Default is ["compose", "commandBox"]. NeinNo 1,51.5

Wenn Sie eine statische Liste von Parametern verwenden, werden Sie ebenfalls hinzugefügt.If you are using a static list of parameters, you'll add them as well.

EigenschaftennameProperty name ZweckPurpose Pflichtfeld?Required? Minimale ManifestversionMinimum manifest version
parameters Statische Liste von Parametern für den Befehl.Static list of parameters for the command. Nur verwenden, fetchTask Wenn falseOnly use when fetchTask is false NeinNo 1.01.0
parameter.name Der Name des Parameters.The name of the parameter. Dies wird in der Benutzeranforderung an Ihren Dienst gesendet.This is sent to your service in the user request. JaYes 1.01.0
parameter.description Beschreibt den Zweck oder das Beispiel dieses Parameters des Werts, der angegeben werden sollte.Describes this parameter’s purposes or example of the value that should be provided. Dieser Wert wird auf der Benutzeroberfläche angezeigt.This value appears in the UI. JaYes 1.01.0
parameter.title Kurzer benutzerfreundlicher Parameter Titel oder Bezeichnung.Short user-friendly parameter title or label. JaYes 1.01.0
parameter.inputType Legt den Typ der erforderlichen Eingabe fest.Set to the type of input required. Mögliche Werte sind text :,, textarea ,, number date time , toggle .Possible values include text, textarea, number, date, time, toggle. Default ist auf festgelegt textDefault is set to text NeinNo 1.41.4

Wenn Sie eine eingebettete Webansicht verwenden, können Sie optional das Objekt hinzufügen, taskInfo um Ihre Webansicht abzurufen, ohne den bot direkt aufzurufen.If you are using an embedded web view, you can optionally add the taskInfo object to fetch your web view without calling your bot directly. Wenn Sie diese Option verwenden, ähnelt das Verhalten der Verwendung einer statischen Liste von Parametern darin, dass die erste Interaktion mit Ihrem bot auf die Aufgabe-Modul-Aktion "Submit" reagiert.If you choose to use this option, the behavior is similar to using a static list of parameters in that the first interaction with your bot will be responding to the task module submit action. Wenn Sie ein Objekt verwenden taskInfo , müssen Sie auch den fetchTask Parameter auf festlegen false .If you are using a taskInfo object, be sure to also set the fetchTask parameter to false.

EigenschaftennameProperty name ZweckPurpose Pflichtfeld?Required? Minimale ManifestversionMinimum manifest version
taskInfo Angeben des Aufgabenmoduls, das beim Verwenden eines Messaging Erweiterungs Befehls geladen werden sollSpecify the task module to preload when using a messaging extension command NeinNo 1.41.4
taskInfo.title Titel des ersten AufgabenmodulsInitial task module title NeinNo 1.41.4
taskInfo.width Größe des Aufgabenmoduls: entweder eine Zahl in Pixel oder ein Standardlayout wie "Large", "Medium" oder "Small"Task module width - either a number in pixels or default layout such as 'large', 'medium', or 'small' NeinNo 1.41.4
taskInfo.height Größe des Aufgabenmoduls-entweder eine Zahl in Pixel oder ein Standardlayout wie "Large", "Medium" oder "Small"Task module height - either a number in pixels or default layout such as 'large', 'medium', or 'small' NeinNo 1.41.4
taskInfo.url Anfängliche webansichts-URLInitial web view URL NeinNo 1.41.4

Beispiel für ein App-ManifestApp manifest example

Im folgenden sehen Sie ein Beispiel für ein composeExtensions Objekt, das zwei Aktionsbefehle definiert.The below is an example of a composeExtensions object defining two action commands. Es ist kein Beispiel für das vollständige Manifest, für das vollständige App-Manifest-Schema Siehe: App-Manifest-Schema.It is not an example of the complete manifest, for the full app manifest schema see: App manifest schema.

...
"composeExtensions": [
  {
    "botId": "12a3c29f-1fc5-4d97-a142-12bb662b7b23",
    "canUpdateConfiguration": true,
    "commands": [
      {
        "id": "addTodo",
        "description": "Create a To Do item",
        "title": "Create To Do",
        "type": "action",
        "context": ["commandBox", "message", "compose"],
        "fetchTask": false,
        "parameters": [
          {
            "name": "Name",
            "description": "To Do Title",
            "title": "Title",
            "inputType": "text"
          },
          {
            "name": "Description",
            "description": "Description of the task",
            "title": "Description",
            "inputType": "textarea"
          },
          {
            "name": "Date",
            "description": "Due date for the task",
            "title": "Date",
            "inputType": "date"
          }
        ]
      },
      {
        "id": "reassignTodo",
        "description": "Reassign a todo item",
        "title": "Reassign a todo item",
        "type": "action",
        "fetchTask": true,
      }
    ]
  }
]
...

Nächste SchritteNext steps

Wenn Sie eine Adaptive Karte oder eine eingebettete Webansicht ohne taskInfo Objekt verwenden, sollten Sie Folgendes tun:If you are using either an adaptive card or an embedded web view without a taskInfo object, you'll want to:

Wenn Sie Parameter oder eine eingebettete Webansicht mit einem- taskInfo Objekt verwenden, ist der nächste Schritt für Sie:If you are using parameters or an embedded web view with a taskInfo object, the next step for you is to:

Weitere InformationenLearn more

Testen Sie es in einem Schnellstart:Try it out in a quickstart: