Initiieren von Aktionen mit Messaging ErweiterungenInitiate actions with messaging extensions

Wichtig

Die Artikel in diesem Abschnitt basieren auf dem V3 bot Framework SDK.The articles in this section are based on the v3 Bot Framework SDK. Wenn Sie nach der aktuellen Dokumentation (Version 4,6 oder höher des SDK) suchen, lesen Sie den Abschnitt aufgabenorientierte Interaktionen mit Messaging Erweiterungen .If you're looking for current documentation (version 4.6 or later version of the SDK) see the Task-oriented interactions with Messaging Extensions section.

Aktionsbasierte Messaging Erweiterungen ermöglichen es Ihren Benutzern, Aktionen in externen Diensten innerhalb von Teams auszulösen.Action-based messaging extensions allow your users to trigger actions in external services while inside of Teams.

Beispiel für eine Messaging Erweiterungskarte

In den folgenden Abschnitten wird die Vorgehensweise beschrieben.The following sections describe how to do this.

Hinzufügen einer Messaging Erweiterung zu Ihrer APPAdd a messaging extension to your app

Eine Messaging Erweiterung ist ein in der Cloud gehosteter Dienst, der Benutzeranforderungen überwacht und mit strukturierten Daten wie einer Karteantwortet.A messaging extension is a cloud-hosted service that listens to user requests and responds with structured data, such as a card. Sie integrieren Ihren Dienst in Microsoft Teams über bot- Activity Framework-Objekte.You integrate your service with Microsoft Teams via Bot Framework Activity objects. Unsere .net-und Node. js-Erweiterungen für das bot Builder SDK können Ihnen helfen, Ihrer APP Messaging Erweiterungsfunktionen hinzuzufügen.Our .NET and Node.js extensions for the Bot Builder SDK can help you add messaging extension functionality to your app.

Diagramm des Nachrichtenflusses für Messaging Erweiterungen

Registrieren im bot-FrameworkRegister in the Bot Framework

Wenn Sie dies noch nicht getan haben, müssen Sie zuerst einen bot mit dem Microsoft bot Framework registrieren.If you haven’t done so already, you must first register a bot with the Microsoft Bot Framework. Die Microsoft-App-ID und die Rückruf Endpunkte für Ihren bot, wie dort definiert, werden in Ihrer Messaging-Erweiterung verwendet, um Benutzeranforderungen zu empfangen und darauf zu reagieren.The Microsoft app ID and callback endpoints for your bot, as defined there, will be used in your messaging extension to receive and respond to user requests. Denken Sie daran, den Microsoft Teams-Kanal für Ihren bot zu aktivieren.Remember to enable the Microsoft Teams channel for your bot.

Notieren Sie sich Ihre bot-APP-ID und Ihr App-Kennwort, müssen Sie die APP-ID in Ihrem App-Manifest angeben.Record your bot app ID and app password, you will need to supply the app ID in your app manifest.

Aktualisieren des App-ManifestsUpdate your app manifest

Wie bei Bots und Tabs aktualisieren Sie das Manifest Ihrer APP so, dass die Eigenschaften der Messaging Erweiterung enthalten sind.As with bots and tabs, you update the manifest of your app to include the messaging extension properties. Diese Eigenschaften bestimmen, wie Ihre Messaging Erweiterung angezeigt wird und sich im Microsoft Teams-Client verhält.These properties govern how your messaging extension appears and behaves in the Microsoft Teams client. Messaging Erweiterungen werden beginnend mit v 1.0 des Manifests unterstützt.Messaging extensions are supported beginning with v1.0 of the manifest.

Deklarieren der Messaging ErweiterungDeclare your messaging extension

Um eine Messaging Erweiterung hinzuzufügen, fügen Sie eine neue JSON-Struktur der obersten Ebene in Ihr composeExtensions Manifest mit der-Eigenschaft ein.To add a messaging extension, include a new top-level JSON structure in your manifest with the composeExtensions property. Derzeit ist es nur möglich, eine einzelne Messaging Erweiterung für Ihre APP zu erstellen.Currently, you are limited to creating a single messaging extension for your app.

Hinweis

Das Manifest bezieht sich auf Messaging composeExtensionsErweiterungen als.The manifest refers to messaging extensions as composeExtensions. Dadurch wird die Abwärtskompatibilität gewährleistet.This is to maintain backward compatibility.

Die Erweiterungs Definition ist ein Objekt mit der folgenden Struktur:The extension definition is an object that has the following structure:

EigenschaftennameProperty name ZweckPurpose Pflichtfeld?Required?
botId Die eindeutige Microsoft-App-ID für den bot, die im bot-Framework registriert ist.The unique Microsoft app ID for the bot as registered with the Bot Framework. Dies sollte in der Regel mit der ID für Ihre gesamte Teams-App übereinstimmen.This should typically be the same as the ID for your overall Teams app. JaYes
scopes Array, personal das angibt, ob dieser Erweiterung oder team Bereichen (oder beides) hinzugefügt werden kann.Array declaring whether this extension can be added to personal or team scopes (or both). JaYes
canUpdateConfiguration Aktiviert das Menüelement Einstellungen .Enables Settings menu item. NeinNo
commands Array von Befehlen, die von dieser Messaging Erweiterung unterstützt werden.Array of commands that this messaging extension supports. Sie sind auf 10 Befehle limitiert.You are limited to 10 commands. JaYes

Definieren von BefehlenDefine commands

Ihre Messaging Erweiterung sollte einen Befehl deklarieren, der angezeigt wird, wenn der Benutzer Ihre APP über die Schaltfläche Weitere Optionen () im Feld Verfassen auswählt.Your messaging extension should declare one command, which appears when the user selects your app from the More options () button in the compose box.

Screenshot der Liste der Messaging Erweiterungen in Microsoft Teams

Im App-Manifest ist Ihr Befehls Element ein Objekt mit der folgenden Struktur:In the app manifest, your command item is an object with the following structure:

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
description Hilfetext, der angibt, was dieser Befehl ausführt.Help text indicating what this command does. Dieser Wert wird auf der Benutzeroberfläche angezeigt.This value appears in the UI. JaYes 1.01.0
type Legen Sie den Typ des Befehls fest.Set the type of command. Mögliche Werte sind query und action.Possible values include query and action. Wenn nicht vorhanden, wird der Standardwert auf festgelegt.queryIf not present the default value is set to query NeinNo 1.41.4
initialRun Optionaler Parameter, der query mit Befehlen verwendet wird.Optional parameter, used with query commands. Bei Festlegung auf " true" gibt an, dass dieser Befehl ausgeführt werden soll, sobald der Benutzer diesen Befehl auf der Benutzeroberfläche auswählt.If set to true, indicates this command should be executed as soon as the user chooses this command in the UI. NeinNo 1.01.0
fetchTask Optionaler Parameter, der action mit Befehlen verwendet wird.Optional parameter, used with action commands. Legen Sie den Wert auf true fest, um die Adaptive Karte oder die weburl abzurufen, die im Aufgabenmodulangezeigt werden soll.Set to true to fetch the adaptive card or web url to display within the task module. Dies wird verwendet, wenn die Eingaben für action den Befehl im Gegensatz zu einer statischen Gruppe von Parametern dynamisch sind.This is used when the inputs to the action command is dynamic as opposed to a static set of parameters. Beachten Sie, dass bei Festlegung auf true die Liste der statischen Parameter für den Befehl ignoriert wird.Note that the if set to true the static parameter list for the command is ignored NeinNo 1.41.4
parameters Statische Liste von Parametern für den Befehl.Static list of parameters for the command. JaYes 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 festgelegttextDefault is set to text NeinNo 1.41.4
context Optionales Array von Werten, das den Kontext definiert, in dem die Nachrichtenaktion verfügbar ist.Optional array of values that defines the context the message action is available in. Mögliche Werte sind message, composeoder commandBox.Possible values are message, compose, or commandBox. Der Standardwert lautet ["compose", "commandBox"].Default is ["compose", "commandBox"]. NeinNo 1,51.5

Nachrichten Erweiterungen für AktionstypenAction type message extensions

Um Aktionen aus einer Messaging Erweiterung zu initiieren type , legen Sie den Parameter auf fest action .To initiate actions from a messaging extension set the type parameter to action. Unten sehen Sie ein Beispiel für ein Manifest mit einer Suche und einem Create-Befehl.Below is an example of a manifest with a search and a create command. Eine einzelne Messaging Erweiterung kann bis zu zehn verschiedene Befehle haben.A single messaging extension can have up to 10 different commands. Dies kann sowohl mehrere Suchfunktionen als auch mehrere Aktionsbasierte Befehle umfassen.This can include both multiple search and multiple action-based commands.

Beispiel für ein vollständiges App-ManifestComplete app manifest example

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.7/MicrosoftTeams.schema.json",
  "manifestVersion": "1.5",
  "version": "1.0",
  "id": "57a3c29f-1fc5-4d97-a142-35bb662b7b23",
  "packageName": "com.microsoft.teams.samples.Todo",
  "developer": {
    "name": "John Developer",
    "websiteUrl": "http://todobotservice.azurewebsites.net/",
    "privacyUrl": "http://todobotservice.azurewebsites.net/privacy",
    "termsOfUseUrl": "http://todobotservice.azurewebsites.net/termsofuse"
  },
  "name": {
    "short": "To Do",
    "full": "To Do"
  },
  "description": {
    "short": "Find or create a new task in To Do",
    "full": "Find or create a new task in To Do"
  },
  "icons": {
    "outline": "todo-outline.jpg",
    "color": "todo-color.jpg"
  },
  "accentColor": "#ff6a00",
  "composeExtensions": [
    {
      "botId": "57a3c29f-1fc5-4d97-a142-35bb662b7b23",
      "canUpdateConfiguration": true,
      "commands": [
        {
          "id": "searchCmd",
          "description": "Search you Todo's",
          "title": "Search",
          "initialRun": true,
          "context": ["commandBox", "compose"],
          "parameters": [
            {
              "name": "searchKeyword",
              "description": "Enter your search keywords",
              "title": "Keywords"
            }
          ]
        },
        {
          "id": "addTodo",
          "description": "Create a To Do item",
          "title": "Create To Do",
          "type": "action",
          "context": ["commandBox", "message", "compose"],
          "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,
          "parameters": [
            {
              "name": "Name",
              "title": "Title"
            }
          ]
        }
      ]
    }
  ],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": [
    "todobotservice.azurewebsites.net",
    "*.todobotservice.azurewebsites.net"
  ]
}

Initiieren von Aktionen aus NachrichtenInitiate actions from messages

Zusätzlich zum Initiieren von Aktionen aus dem Bereich zum Verfassen von Nachrichten können Sie auch Ihre Messaging Erweiterung verwenden, um eine Aktion aus einer Nachricht zu initiieren.In addition to initiating actions from the compose message area, you can also use your messaging extension to initiate an action from a message. Auf diese Weise können Sie den Inhalt der Nachricht an Ihren bot zur Verarbeitung senden und auf diese Nachricht optional mit einer Antwort Antworten, die unter Antworten auf Sendenbeschrieben wird.This will allow you to send the contents of the message to your bot for processing, and optionally reply to that message with a response using the method described in Responding to submit. Die Antwort wird als Antwort auf die Nachricht eingefügt, die Ihre Benutzer vor dem Senden bearbeiten können.The response will be inserted as a reply to the message that your users can edit before submitting. Ihre Benutzer können über das Menü Überlauf auf Ihre Messaging Erweiterung zugreifen ... und dann Take action wie in der Abbildung unten auswählen.Your users can access your messaging extension from the overflow ... menu and then selecting Take action as in the image below.

Beispiel für das Initiieren einer Aktion aus einer Nachricht

Damit Ihre Messaging Erweiterung mit einer Nachricht funktioniert, müssen Sie den context Parameter dem Objekt Ihrer Messaging Erweiterung im App-Manifest hinzufügen, commands wie im folgenden Beispiel dargestellt.To enable your messaging extension to work from a message you'll need to add the context parameter to your messaging extension's commands object in your app manifest as in the example below. Gültige Zeichenfolgen für das context Array sind "message" , "commandBox" und "compose" .Valid strings for the context array are "message", "commandBox", and "compose". Der Standardwert ist ["compose", "commandBox"].The default value is ["compose", "commandBox"]. Ausführliche Informationen zum Parameter finden Sie im Abschnitt define Commands context .See the define commands section for complete details on the context parameter.

"composeExtensions": [
  {
    "botId": "57a3c29f-1fc5-4d97-a142-35bb662b7b23",
    "canUpdateConfiguration": true,
    "commands": [
      {
        "id": "reassignTodo",
        "description": "Reassign a todo item",
        "title": "Create To Do",
        "type": "Action",
        "context": ["message"],
        "fetchTask": true
    }]
    ...

Unten sehen Sie ein Beispiel für das Objekt, das value die Nachrichtendetails enthält, die gesendet werden, wenn ein Teil der composeExtension Anforderung an Ihren bot gesendet wird.Below is an example of the value object containing the message details that will be sent as part of the composeExtension request be sent to your bot.

{
  "name": "composeExtension/submitAction",
  "type": "invoke",
...
  "value": {
    "commandId": "setReminder",
    "commandContext": "message",
    "messagePayload": {
      "id": "1111111111",
      "replyToId": null,
      "createdDateTime": "2019-02-25T21:29:36.065Z",
      "lastModifiedDateTime": null,
      "deleted": false,
      "subject": "Message subject",
      "summary": null,
      "importance": "normal",
      "locale": "en-us",
      "body": {
        "contentType": "html",
        "content": "this is the message"
    },
      "from": {
        "device": null,
        "conversation": null,
        "user": {
          "userIdentityType": "aadUser",
          "id": "wxyz12ab8-ab12-cd34-ef56-098abc123876",
          "displayName": "Jamie Smythe"
        },
        "application": null
      },
      "reactions": [
        {
          "reactionType": "like",
          "createdDateTime": "2019-02-25T22:40:40.806Z",
          "user": {
            "device": null,
            "conversation": null,
            "user": {
              "userIdentityType": "aadUser",
              "id": "qrst12346-ab12-cd34-ef56-098abc123876",
              "displayName": "Jim Brown"
            },
            "application": null
          }
        }
      ],
      "mentions": [
        {
          "id": 0,
          "mentionText": "Sarah",
          "mentioned": {
            "device": null,
            "conversation": null,
            "user": {
              "userIdentityType": "aadUser",
              "id": "ab12345678-ab12-cd34-ef56-098abc123876",
              "displayName": "Sarah"
            },
            "application": null
          }
        }
      ]
    }
  ...

Testen über hochladenTest via uploading

Sie können Ihre Messaging Erweiterung testen, indem Sie Ihre APP hochladen.You can test your messaging extension by uploading your app. Weitere Informationen finden Sie unter Hochladen Ihrer APP in einem Team .See Uploading your app in a team for details.

Um Ihre Messaging Erweiterung zu öffnen, navigieren Sie zu einem beliebigen Chat oder Kanal.To open your messaging extension, navigate to any of your chats or channels. Wählen Sie im Feld Verfassen die Schaltfläche Weitere Optionen () aus, und wählen Sie Ihre Messaging Erweiterung aus.Choose the More options () button in the compose box, and choose your messaging extension.

Sammeln von Eingaben von BenutzernCollecting input from users

Es gibt drei Möglichkeiten zum Erfassen von Informationen von einem Endbenutzer in Microsoft Teams.There are three ways to collect information from an end user in Teams.

Liste der statischen ParameterStatic parameter list

In dieser Methode müssen Sie lediglich eine statische Liste von Parametern im Manifest definieren, wie oben im Befehl "Create to do" dargestellt.In this method, all you need to do is define a static list of parameters in the manifest as shown above in the "Create To Do" command. Um diese Methode zu verwenden, ist sichergestellt, fetchTask false dass Sie die Parameter im Manifest definieren und festlegen.To use this method ensure fetchTask is set to false and that you define your parameters in the manifest.

Wenn ein Benutzer einen Befehl mit statischen Parametern auswählt, generiert Microsoft Teams ein Formular in einem Aufgabenmodul, wobei die im Manifest definierten Parameter verwendet werden.When a user chooses a command with static parameters, Teams will generate a form in a Task Module with the parameters defined in the manifest. Beim Drücken von Submit composeExtension/submitAction wird a an den bot gesendet.On hitting Submit a composeExtension/submitAction is sent to the bot. Weitere Informationen zu den erwarteten Antworten finden Sie im Thema Antworten auf Submit .See the topic Responding to submit for more information on the expected set of responses.

Dynamische Eingabe mithilfe einer adaptiven KarteDynamic input using an adaptive card

Bei dieser Methode kann Ihr Dienst eine benutzerdefinierte Adaptive Karte definieren, um die Benutzereingabe zu erfassen.In this method, your service can define a custom adaptive card to collect the end user input. Legen Sie für diesen Ansatz den fetchTask Parameter auf true im Manifest fest.For this approach, set the fetchTask parameter to true in the manifest. Beachten Sie, dass bei Festlegung fetchTask auf true statische Parameter, die für den Befehl definiert sind, ignoriert werden.Note that if you set fetchTask to true any static parameters defined for the command will be ignored.

In dieser Methode erhält Ihr Dienst ein composeExtension/fetchTask Ereignis und muss mit einer adaptiven kartenbasierten Antwort auf AufgabenmodulAntworten.In this method your service will receive a composeExtension/fetchTask event and needs to respond with an adaptive card based task module response. Unten sehen Sie eine Beispielantwort mit einer adaptiven Karte:Below is an sample response with an adaptive card:

{
    "task": {
        "type": "continue",
        "value": {
            "card": {
                "contentType": "application/vnd.microsoft.card.adaptive",
                "content": {
                    "body": [
                        {
                            "type": "TextBlock",
                            "text": "Please enter the following information:"
                        },
                        {
                            "type": "TextBlock",
                            "text": "Name"
                        },
                        {
                            "type": "Input.Text",
                            "spacing": "None",
                            "title": "New Input.Toggle",
                            "placeholder": "Placeholder text"
                        },
                        {
                            "type": "TextBlock",
                            "text": "Date of birth"
                        },
                        {
                            "type": "Input.Date",
                            "spacing": "None",
                            "title": "New Input.Toggle"
                        }
                    ],
                    "type": "AdaptiveCard",
                    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
                    "version": "1.0"
                }
            }
        }
    }
}

Der Bot kann auch mit einer auth/config-Antwort Antworten, wenn der Benutzer die Erweiterung authentifizieren oder konfigurieren muss, bevor er die Benutzereingabe erhält.The bot can also respond with an auth/config response if the user needs to authenticate or configure the extension before getting the user input.

Dynamische Eingabe mithilfe einer WebansichtDynamic input using a web view

In dieser Methode kann Ihr Dienst ein <iframe> basiertes Widget anzeigen, um eine benutzerdefinierte Benutzeroberfläche anzuzeigen und Benutzereingaben zu erfassen.In this method your service can show an <iframe> based widget to show any custom UI and collect user input. Legen Sie für diesen Ansatz den fetchTask Parameter auf true im Manifest fest.For this approach, set the fetchTask parameter to true in the manifest.

Genau wie beim adaptiven Karten Fluss wird Ihr Dienst ein Ereignis senden fetchTask und muss mit einer URL-basierten Aufgabenmodul AntwortAntworten.Just like in the adaptive card flow your service will be send a fetchTask event and needs to respond with a URL based task module response. Unten sehen Sie eine Beispielantwort mit einer adaptiven Karte:Below is an sample response with an Adaptive card:

{
    "task": {
        "value": {
            "url": "http://mywebapp.com/input"
        },
        "type": "continue"
    }
}

Anforderung zum Installieren Ihres Unterhaltungs-botRequest to install your conversational bot

Wenn Ihre APP auch einen Unterhaltungs-bot enthält, müssen Sie möglicherweise sicherstellen, dass Ihr bot in der Unterhaltung installiert ist, bevor Sie den Aufgabenmodul laden.If your app also contains a conversational bot, it may be necessary to ensure that your bot is installed in the conversation before loading your task module. Dies kann in Situationen hilfreich sein, in denen Sie zusätzlichen Kontext für Ihr Aufgabenmodul erhalten müssen.This can be useful in situations where you need to get additional context for you task module. Beispielsweise müssen Sie möglicherweise das Dienstplan Verzeichnis abrufen, um ein Personenauswahl-Steuerelement oder die Liste der Kanäle in einem Team aufzufüllen.For example, you may need to fetch the roster to populate a people picker control, or the list of channels in a team.

Um diesen Fluss zu erleichtern, wenn Ihre Messaging-Erweiterung zuerst die composeExtension/fetchTask Invoke-Überprüfung erhält, um festzustellen, ob Ihr bot im aktuellen Kontext installiert ist (Sie können dies beispielsweisedurch den Aufruf des Get-Dienstplan Aufrufs erreichen).To facilitate this flow, when your messaging extension first receives the composeExtension/fetchTask invoke check to see if your bot is installed in the current context (you could accomplish this by attempting the get roster call, for example). Wenn Ihr bot nicht installiert ist, geben Sie eine Adaptive Karte mit einer Aktion zurück, die den Benutzer anfordert, ihren bot zu installieren, siehe das Beispiel unten.If your bot is not installed, you return an Adaptive Card with an action that requests the user to install your bot See the example below. Beachten Sie, dass dies erfordert, dass der Benutzer über die Berechtigung zum Installieren von apps an diesem Speicherort verfügt. Wenn dies nicht möglich ist, wird eine Meldung angezeigt, in der Sie aufgefordert werden, Ihren Administrator zu kontaktieren.Note that this requires the user to have permission to install apps in that location; if they cannot they will be presented with a message asking them to contact their administrator.

Hier ist ein Beispiel für die Antwort:Here's an example of the response:

{
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "TextBlock",
      "text": "Looks like you haven't used Disco in this team/chat"
    }
  ],
  "actions": [
    {
      "type": "Action.Submit",
      "title": "Continue",
      "data": {
        "msteams": {
          "justInTimeInstall": true
        }
      }
    }
  ],
  "version": "1.0"
}

Sobald der Benutzer die Installation abgeschlossen hat, erhält der bot eine weitere Invoke-Nachricht mit name = composeExtension/submitAction und value.data.msteams.justInTimeInstall = true .Once the user completes the installation, your bot will receive another invoke message with name = composeExtension/submitAction, and value.data.msteams.justInTimeInstall = true.

Hier ist ein Beispiel für den Aufruf:Here's an example of the invoke:

{
  "value": {
    "commandId": "giveKudos",
    "commandContext": "compose",
    "context": {
      "theme": "default"
    },
    "data": {
      "msteams": {
        "justInTimeInstall": true
      }
    }
  },
  "conversation": {
    "id": "19:7705841b240044b297123ad7f9c99217@thread.skype"
  },
  "name": "composeExtension/submitAction",
  "imdisplayname": "Bob Smith"
}

Sie sollten auf diesen Aufruf mit derselben Antwort Antworten, auf die Sie reagiert haben, wenn der bot bereits installiert wurde.You should respond to this invoke with the same task response you would have responded with if the bot was already installed.

Reagieren auf SubmitResponding to submit

Sobald ein Benutzer seine Eingabe abgeschlossen hat, erhält der bot ein composeExtension/submitAction Ereignis mit den festgelegten Befehls-IDs und Parameterwerten.Once a user completes entering their input your bot will receive a composeExtension/submitAction event with the command id and parameter values set.

Dies sind die unterschiedlichen erwarteten Antworten auf a submitAction .These are the different expected responses to a submitAction.

Antwort des AufgabenmodulsTask Module response

Dies wird verwendet, wenn Ihre Erweiterung Dialogfelder miteinander verketten muss, um weitere Informationen zu erhalten.This is used when your extension needs to chain dialogs together to get more information. Die Antwort ist genau die gleiche wie fetchTask zuvor erwähnt.The response is exactly the same as fetchTask mentioned earlier.

Antwort zum Verfassen der Durchwahl Authentifizierung/-KonfigurationCompose extension auth/config response

Dies wird verwendet, wenn Ihre Erweiterung entweder authentifiziert oder konfiguriert werden muss, um den Vorgang fortzusetzen.This is used when your extension needs to either authenticate or configure in order to continue. Weitere Informationen finden Sie im Abschnitt "Authentifizierung" im Abschnitt "Suche".See authentication section in the search section for more details.

Antwort zum Verfassen der Ergebnis ErweiterungCompose extension result response

Dadurch wird eine Karte als Ergebnis eines Befehls in das Feld Verfassen eingefügt.This used to insert a card into the compose box as a result of a the command. Es ist die gleiche Antwort, die im Suchbefehl verwendet wird, aber Sie ist auf eine Karte oder ein Ergebnis im Array limitiert.It's the same response that's used in the search command, but it's limited to one card or one result in the array.

{
  "composeExtension": {
    "type": "result",
    "attachmentLayout": "list",
    "preview": {
          "contentType": "application/vnd.microsoft.card.thumbnail",
          "content": {
            "title": "85069: Create a cool app",
            "images": [
              {
                "url": "https://placekitten.com/200/200"
              }
            ]
          }
        },
    "attachments": [
      {  
        "contentType": "application/vnd.microsoft.teams.card.o365connector",
        "content": {
          "sections": [
            {
              "activityTitle": "[85069]: Create a cool app",
              "activityImage": "https://placekitten.com/200/200"
            },
            {
              "title": "Details",
              "facts": [
                {
                  "name": "Assigned to:",
                  "value": "[Larry Brown](mailto:larryb@example.com)"
                },
                {
                  "name": "State:",
                  "value": "Active"
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Antworten mit einer adaptiven Karten Nachricht, die von einem bot gesendet wurdeRespond with an adaptive card message sent from a bot

Sie können auch auf die Submit-Aktion reagieren, indem Sie eine Nachricht mit einer adaptiven Karte in den Kanal mit einem bot einfügen.You can also respond to the submit action by inserting a message with an Adaptive Card into the channel with a bot. Der Benutzer kann die Nachricht in einer Vorschau anzeigen, bevor er ihn sendet, und möglicherweise auch mit ihm bearbeiten/interagieren.Your user will be able to preview the message before submitting it, and potentially edit/interact with it as well. Dies kann in Szenarien hilfreich sein, in denen Sie Informationen von Ihren Benutzern sammeln müssen, bevor Sie eine Adaptive Karten Antwort erstellen.This can be very useful in scenarios where you need to gather information from your users before creating an adaptive card response. Das folgende Szenario zeigt, wie Sie diesen Fluss zum Konfigurieren einer Umfrage verwenden können, ohne die Konfigurationsschritte in die Kanal Nachricht einzuschließen.The following scenario shows how you can use this flow to configure a poll without including the configuration steps in the channel message.

  1. Der Benutzer klickt auf die Messaging Erweiterung, um den Aufgabenmodul auszulösen.The user clicks the messaging extension to trigger the task module.
  2. Der Benutzer verwendet den Aufgabenmodul zum Konfigurieren der Umfrage.The user uses the task module to configure the poll.
  3. Nach dem Senden des Konfigurationsaufgaben Moduls verwendet die APP die im Aufgabenmodul bereitgestellten Informationen, um eine Adaptive Karte zu basteln und Sie als botMessagePreview Antwort an den Client zu senden.After submitting the configuration task module the app uses the information provided in the task module to craft an adaptive card and sends it as a botMessagePreview response to the client.
  4. Der Benutzer kann dann eine Vorschau der adaptiven Karten Nachricht anzeigen, bevor der bot ihn in den Kanal einfügt.The user can then preview the adaptive card message before the bot will inserts it into the channel. Wenn der bot noch kein Mitglied des Kanals ist, Send wird der bot durch Klicken hinzugefügt.If the bot is not already a member of the channel, clicking Send will add the bot.
  5. Bei der Interaktion mit der adaptiven Karte wird die Nachricht vor dem Senden geändert.Interacting with the adaptive card will change the message before sending it.
  6. Nachdem der Benutzer Send auf den bot geklickt hat, wird die Nachricht an den Kanal gesendet.Once the user clicks Send the bot will post the message to the channel.

Zum Aktivieren dieses Flusses sollte Ihr Aufgabenmodul wie im folgenden Beispiel reagieren, das die Vorschau Nachricht an den Benutzer weiter gibt.To enable this flow your task module should respond as in the example below, which will present the preview message to the user.

Hinweis

Das activityPreview muss eine message Aktivität mit genau 1 adaptiver Karten Anlage enthalten.The activityPreview must contain a message activity with exactly 1 adaptive card attachment.

{
  "composeExtension": {
    "type": "botMessagePreview",
    "activityPreview": {
      "type": "message",
      "attachments":  [
        {
          "contentType": "application/vnd.microsoft.card.adaptive",
          "content": << Card Payload >>
        }
      ]
    }
  }
}

Ihre Nachrichten Erweiterung muss nun auf zwei neue Arten von Interaktionen reagieren value.botMessagePreviewAction = "send" und value.botMessagePreviewAction = "edit" .Your message extension will now need to respond to two new types of interactions, value.botMessagePreviewAction = "send" and value.botMessagePreviewAction = "edit". Nachfolgend finden Sie ein Beispiel für das value Objekt, das Sie verarbeiten müssen:Below is an example of the value object you will need to process:

{
  "name": "composeExtension/submitAction",
  "type": "invoke",
  "conversation": { "id": "19:c366b75791784100b6e8b515fd55b063@thread.skype" },
  "imdisplayname": "Pranav Smith",
  ...
  "value": {
    "botMessagePreviewAction": "send" | "edit",
    "botActivityPreview": [
      {
        "type": "message/card",
        "attachments": [
          {
            "content":
              {
                "type": "AdaptiveCard",
                "body": [{<<card payload>>}]
              },
            "contentType" : "application/vnd.microsoft.card.adaptive"
          }
        ],
        "context": { "theme": "default" }
      }
    ],
  }
}

Bei der Antwort auf die edit Anforderung sollten Sie mit einer task Antwort mit den Werten Antworten, die mit den Informationen aufgefüllt sind, die der Benutzer bereits übermittelt hat.When responding to the edit request you should respond with a task response with the values populated with the information the user has already submitted. Wenn Sie auf die send Anforderung reagieren, sollten Sie eine Nachricht an den Kanal senden, der die fertige Adaptive Karte enthält.When responding to the send request you should send a message to the channel containing the finalized adaptive card.

teamChatConnector.onComposeExtensionSubmitAction((
    event: builder.IEvent,
    request: teamBuilder.IComposeExtensionActionCommandRequest,
    callback: (err: Error, result: any, statusCode: number) => void) => {
        let invokeValue = (<any> event).value;

        if (invokeValue.botMessagePreviewAction ) {
            let attachment = invokeValue.botActivityPreview[0].attachments[0];

            if (invokeValue.botMessagePreviewAction === 'send') {
                let msg = new builder.Message()
                    .address(event.address)
                    .addAttachment(attachment);
                teamChatConnector.send([msg.toMessage()],
                    (error) => {
                        if(error){
                            //TODO: Handle error and callback
                        }
                        else {
                            callback(null, null, 200);
                        }
                    }
                );
            }

            else if (invokeValue.botMessagePreviewAction === 'edit') {
              // Create the card and populate with user-inputted information
              let card = { ... }

              let taskResponse = {
                task: {
                  type: "continue",
                  value: {
                    title: "Card Preview",
                    card: {
                      contentType: 'application/vnd.microsoft.card.adaptive',
                      content: card
                    }
                  }
                }
              }
              callback(null, taskResponse, 200);
            }

        else {
            let attachment = {
                  //create adaptive card
                };
            let activity = new builder.Message().addAttachment(attachment).toMessage();
            let response = teamBuilder.ComposeExtensionResponse.messagePreview()
                .preview(activity)
                .toResponse();
            callback(null, response, 200);
        }
    });

Siehe auch bot Framework-Beispiele.See also Bot Framework samples.