Definieren von Suchbefehlen für die Messaging ErweiterungDefine messaging extension search 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.

Mit den Suchbefehlen für die Nachrichten Erweiterung können Benutzer externe Systeme durchsuchen und die Ergebnisse der Suche in eine Nachricht in Form einer Karte einfügen.Messaging extension search commands allow your users to search external systems and insert the results of that search into a message in the form of a card.

Auswählen von Speicherorten für Messaging Erweiterungs AufrufeChoose messaging extension invoke locations

Das erste, was Sie entscheiden müssen, ist, wo Ihr Suchbefehl (oder genauer gesagt, aufgerufen) aus ausgelöst werden kann.The first thing you need to decide is where your search command can be triggered (or more specifically, invoked) from. Ihr Suchbefehl kann über einen oder beide der folgenden Speicherorte aufgerufen werden:Your search command can be invoked from one or both of the following locations:

  • Die Schaltflächen am unteren Rand des Bereichs zum Verfassen von NachrichtenThe buttons at the bottom of the compose message area
  • Durch @mentioning im BefehlsfeldBy @mentioning in the command box

Wenn der Benutzer im Bereich zum Verfassen von Nachrichten aufgerufen wird, hat er die Möglichkeit, die Ergebnisse an die Unterhaltung zu senden.When invoked from the compose message area, your user will have the option of sending the results to the conversation. Wenn der Benutzer über das Befehlsfeld aufgerufen wird, kann er mit der resultierenden Karte interagieren oder ihn zur Verwendung an einer anderen Stelle kopieren.When invoked from the command box, the user can interact with the resulting card, or copy it for use elsewhere.

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

Nachdem Sie sich entschieden haben, wie Benutzer mit Ihrem Suchbefehl interagieren sollen, ist es an der Zeit, Sie dem App-Manifest hinzuzufügen.Now that you've decided how users will interact with your search 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 zulassen, dass Benutzer ihren Dienst nach Informationen Abfragen und diesen in eine Nachricht einfügen.Choose Allow users to query your service for information and insert that into a message.
  5. Fügen Sie eine Befehls-ID und einen Titelhinzu.Add a Command Id and a Title.
  6. Wählen Sie aus, wo der Suchbefehl ausgelöst werden soll.Select where you want your search command to be triggered from. Das Auswählen von Nachricht ändert derzeit nicht das Verhalten des Suchbefehls.Selecting message does not currently alter the behavior of your search command.
  7. Fügen Sie den Suchparameter hinzu.Add your search parameter.
  8. Klicken Sie auf Speichern.Click Save.

Manuelles Erstellen eines BefehlsManually create a command

Um den Suchbefehl für die Messaging-Erweiterung manuell Ihrem App-Manifest hinzuzufügen, müssen Sie dem composeExtension.commands Array von Objekten die Parameter "folgt" hinzufügen.To manually add your messaging extension search 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
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 Muss query sein.Must be query NeinNo 1.41.4
initialRun 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
context Optionales Array von Werten, das den Kontext definiert, in dem die Suchaktion verfügbar ist.Optional array of values that defines the context the search 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

Außerdem müssen Sie die Details des Such Parameters hinzufügen, mit dem der Text, der für den Benutzer sichtbar ist, im Microsoft Teams-Client definiert wird.You'll also need to add the details of the search parameter, which will define the text visible to your user in the Teams client.

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. 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 festgelegttextDefault is set to text NeinNo 1.41.4

Beispiel für ein App-ManifestApp manifest example

Im folgenden sehen Sie ein Beispiel für composeExtensions ein Objekt, das einen Suchbefehl definiert.The below is an example of a composeExtensions object defining a search command. 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": "57a3c29f-1fc5-4d97-a142-35bb662b7b23",
      "canUpdateConfiguration": true,
      "commands": [{
          "id": "searchCmd",
          "description": "Search Bing for information on the web",
          "title": "Search",
          "initialRun": true,
          "parameters": [{
            "name": "searchKeyword",
            "description": "Enter your search keywords",
            "title": "Keywords"
          }]
        }
      ]
    }
  ],
...
}

Weitere SchritteNext steps

Nachdem Sie den Suchbefehl hinzugefügt haben, müssen Sie die Suchanforderung verarbeiten.Now that you've added your search command, you'll need to handle the search request.

Weitere InformationenLearn more

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