Suche mit Messaging ErweiterungenSearch 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.

Suchbasierte Messaging-Erweiterungen ermöglichen es Ihnen, ihren Dienst abzufragen und diese Informationen in Form einer Karte nach rechts in Ihre Nachricht einzusenden.Search based messaging extensions allow you to query your service and post that information in the form of a card, right into your message

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 Such TypenSearch type message extensions

Legen Sie für die suchbasierte Messaging Erweiterung den type Parameter auf fest query .For search based messaging extension set the type parameter to query. Unten sehen Sie ein Beispiel für ein Manifest mit einem einzigen Suchbefehl.Below is an example of a manifest with a single search command. Einer einzelnen Messaging Erweiterung können bis zu 10 verschiedene Befehle zugeordnet werden.A single messaging extension can have up to 10 different commands associated with it. 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.bing",
  "developer": {
    "name": "John Developer",
    "websiteUrl": "http://bingbotservice.azurewebsites.net/",
    "privacyUrl": "http://bingbotservice.azurewebsites.net/privacy",
    "termsOfUseUrl": "http://bingbotservice.azurewebsites.net/termsofuse"
  },
  "name": {
    "short": "Bing",
    "full": "Bing"
  },
  "description": {
    "short": "Find Bing search results",
    "full": "Find Bing search results and share them with your team members."
  },
  "icons": {
    "outline": "bing-outline.jpg",
    "color": "bing-color.jpg"
  },
  "accentColor": "#ff6a00",
  "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"
          }]
        }
      ]
    }
  ],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": [
    "bingbotservice.azurewebsites.net",
    "*.bingbotservice.azurewebsites.net"
  ]
}

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.

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.

Hinzufügen von EreignishandlernAdd event handlers

Der Großteil ihrer Arbeit umfasst das onQuery Ereignis, das alle Interaktionen im Fenster Messaging Erweiterung verarbeitet.Most of your work involves the onQuery event, which handles all interactions in the messaging extension window.

Wenn Sie canUpdateConfiguration true im Manifest auf festlegen, aktivieren Sie das Menüelement Einstellungen für Ihre Messaging Erweiterung und müssen auch verarbeiten onQuerySettingsUrl und onSettingsUpdate .If you set canUpdateConfiguration to true in the manifest, you enable the Settings menu item for your messaging extension and must also handle onQuerySettingsUrl and onSettingsUpdate.

Behandeln von onquery-EreignissenHandle onQuery events

Eine Messaging Erweiterung empfängt ein onQuery Ereignis, wenn im Fenster Messaging Erweiterung etwas passiert oder an das Fenster gesendet wird.A messaging extension receives an onQuery event when anything happens in the messaging extension window or is sent to the window.

Wenn Ihre Messaging-Erweiterung eine Konfigurationsseite verwendet, sollte Ihr Handler onQuery zunächst auf gespeicherte Konfigurationsinformationen überprüfen; wenn die Messaging Erweiterung nicht konfiguriert ist, geben Sie eine config Antwort mit einem Link zur Konfigurationsseite zurück.If your messaging extension uses a configuration page, your handler for onQuery should first check for any stored configuration information; if the messaging extension isn't configured, return a config response with a link to your configuration page. Beachten Sie, dass die Antwort von der Konfigurationsseite auch von behandelt wird onQuery .Be aware that the response from the configuration page is also handled by onQuery. (Die einzige Ausnahme ist, wenn die Konfigurationsseite vom Handler für aufgerufen wird onQuerySettingsUrl ; Lesen Sie den folgenden Abschnitt.)(The sole exception is when the configuration page is called by the handler for onQuerySettingsUrl; see the following section.)

Wenn Ihre Messaging-Erweiterung Authentifizierung erfordert, überprüfen Sie die Benutzerstatusinformationen; Wenn der Benutzer nicht angemeldet ist, befolgen Sie die Anweisungen im Abschnitt Authentifizierung weiter unten in diesem Thema.If your messaging extension requires authentication, check the user state information; if the user isn't signed in, follow the instructions in the Authentication section later in this topic.

Überprüfen Sie als nächstes, ob initialRun festgelegt ist, und führen Sie in diesem Fall entsprechende Maßnahmen durch, beispielsweise die Bereitstellung von Anweisungen oder eine Liste von Antworten.Next, check whether initialRun is set; if so, take appropriate action, such as providing instructions or a list of responses.

Der Rest Ihres Handlers onQuery fordert den Benutzer zur Eingabe von Informationen auf, zeigt eine Liste mit Vorschau Karten an und gibt die vom Benutzer ausgewählte Karte zurück.The remainder of your handler for onQuery prompts the user for information, displays a list of preview cards, and returns the card selected by the user.

Behandeln von onQuerySettingsUrl-und onSettingsUpdate-EreignissenHandle onQuerySettingsUrl and onSettingsUpdate events

Die onQuerySettingsUrl -und- onSettingsUpdate Ereignisse werden zusammenarbeiten, um das Menüelement Einstellungen zu aktivieren.The onQuerySettingsUrl and onSettingsUpdate events work together to enable the Settings menu item.

Screenshots des Menüelements "Speicherorte von Einstellungen"

Der Handler für onQuerySettingsUrl gibt die URL für die Konfigurationsseite zurück, nachdem die Konfigurationsseite geschlossen wurde, der Handler für onSettingsUpdate akzeptiert und speichert den zurückgegebenen Zustand.Your handler for onQuerySettingsUrl returns the URL for the configuration page; after the configuration page closes, your handler for onSettingsUpdate accepts and saves the returned state. (Dies ist der einzige Fall, in dem onQuery die Antwort wird nicht von der Konfigurationsseite empfangen.)(This is the one case in which onQuery doesn't receive the response from the configuration page.)

Empfangen und beantworten von AbfragenReceive and respond to queries

Jede Anforderung an Ihre Messaging Erweiterung erfolgt über ein Activity Objekt, das an die Rückruf-URL gesendet wird.Every request to your messaging extension is done via an Activity object that is posted to your callback URL. Die Anforderung enthält Informationen zum Benutzer Befehl wie ID und Parameterwerte.The request contains information about the user command, such as ID and parameter values. Die Anforderung liefert auch Metadaten zu dem Kontext, in dem Ihre Erweiterung aufgerufen wurde, einschließlich Benutzer-und Mandanten-ID sowie Chat-ID oder Kanal-und Team-IDs.The request also supplies metadata about the context in which your extension was invoked, including user and tenant ID, along with chat ID or channel and team IDs.

Empfangen von BenutzeranforderungenReceive user requests

Wenn ein Benutzer eine Abfrage ausführt, sendet Microsoft Teams Ihrem Dienst ein Standardmäßiges bot-Framework Activity -Objekt.When a user performs a query, Microsoft Teams sends your service a standard Bot Framework Activity object. Ihr Dienst sollte seine Logik für einen ausführen, der Activity type auf invoke name einen unterstützten Typ festgelegt und festgelegt hat composeExtension , wie in der folgenden Tabelle dargestellt.Your service should perform its logic for an Activity that has type set to invoke and name set to a supported composeExtension type, as shown in the following table.

Zusätzlich zu den standardmäßigen bot-Aktivitätseigenschaften enthält die Nutzlast die folgenden Anforderungs Metadaten:In addition to the standard bot activity properties, the payload contains the following request metadata:

EigenschaftsnameProperty name ZweckPurpose
type Typ der Anforderung; muss sein invoke .Type of request; must be invoke.
name Der Typ des Befehls, der für den Dienst ausgestellt wird.Type of command that is issued to your service. Derzeit werden die folgenden Typen unterstützt:Currently the following types are supported:
composeExtension/query
composeExtension/querySettingUrl
composeExtension/setting
composeExtension/selectItem
composeExtension/queryLink
from.id Die ID des Benutzers, der die Anforderung gesendet hat.ID of the user that sent the request.
from.name Der Name des Benutzers, der die Anforderung gesendet hat.Name of the user that sent the request.
from.aadObjectId Azure Active Directory Objekt-ID des Benutzers, der die Anforderung gesendet hat.Azure Active Directory object id of the user that sent the request.
channelData.tenant.id Azure Active Directory Mandanten-ID.Azure Active Directory tenant ID.
channelData.channel.id Kanal-ID (wenn die Anforderung in einem Kanal erfolgt ist).Channel ID (if the request was made in a channel).
channelData.team.id Team-ID (wenn die Anforderung in einem Kanal erfolgt ist).Team ID (if the request was made in a channel).
clientInfo Optionale Metadaten zur Client Software, die zum Senden der Nachricht eines Benutzers verwendet wurde.Optional metadata about the client software used to send a user's message. Die Entität kann zwei Eigenschaften enthalten:The entity can contain two properties:
Das country Feld enthält den erkannten Speicherort des Benutzers.The country field contains the user's detected location.
Das platform Feld beschreibt die Messaging-Clientplattform.The platform field describes the messaging client platform.
Weitere Informationen finden Sie unter nicht-IRI-Entitätstypen – abgeschlossen werden ungültig.For additional information, please see Non-IRI entity types — clientInfo.

Die Anforderungsparameter selbst werden im Value-Objekt gefunden, das die folgenden Eigenschaften enthält:The request parameters itself are found in the value object, which includes the following properties:

EigenschaftsnameProperty name ZweckPurpose
commandId Der Name des vom Benutzer aufgerufenen Befehls, der einem der im App-Manifest deklarierten Befehle entspricht.The name of the command invoked by the user, matching one of the commands declared in the app manifest.
parameters Array von Parametern.Array of parameters. Jedes Parameter-Objekt enthält den Namen des Parameters sowie den vom Benutzer bereitgestellten Parameterwert.Each parameter object contains the parameter name, along with the parameter value provided by the user.
queryOptions Paginierung Parameter:Pagination parameters:
skip: Skip count für diese Abfrageskip: skip count for this query
count: Anzahl der zurückzugebenden Elementecount: number of elements to return

AnforderungsbeispielRequest example

{
  "name": "composeExtension/query",
  "value": {
    "commandId": "searchCmd",
    "parameters": [
      {
        "name": "searchKeywords",
        "value": "Toronto"
      }
    ],
    "queryOptions": {
      "skip": 0,
      "count": 25
    }
  },
  "type": "invoke",
  "timestamp": "2017-05-01T15:45:51.876Z",
  "localTimestamp": "2017-05-01T08:45:51.876-07:00",
  "id": "f:622749630322482883",
  "channelId": "msteams",
  "serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/",
  "from": {
    "id": "29:1C7dbRrC_5yzN1RGtZIrcWT0xz88KPGP9sxdpVpV8sODlgPHeQE9RqQ02hnpuKzy6zZ-AaZx6swUOMj_Dsdse3TQ4sIaeebbFBF-VgjJy_nY",
    "name": "Larry Jin",
    "aadObjectId": "cd723fa0-0591-416a-9290-e93ecf3a9b92"
  },
  "conversation": {
    "id": "19:skypespaces_8198cfe0dd2647ae91930f0974768a40@thread.skype"
  },
  "recipient": {
    "id": "28:b4922ea1-5315-4fd0-9b21-d941ab06e39f",
    "name": "TheComposeExtensionDev"
  },
  "entities": [
    {
    "type": "clientInfo",
      "country": "US",
      "platform": "Windows"
    }
  ]
}

Alternativ (oder zusätzlich) zum Durchsuchen Ihres externen Diensts können Sie eine URL verwenden, die in das Meldungsfeld verfassen eingefügt wurde, um Ihren Dienst abzufragen und eine Karte zurückzugeben.As an alternative (or in addition) to searching your external service, you can use a URL inserted into the compose message box to query your service and return a card. Im Screenshot unten hat ein Benutzer eine URL für eine Arbeitsaufgabe in Azure DevOps eingefügt, die von der Messaging Erweiterung in eine Karte aufgelöst wurde.In the screenshot below a user has pasted in a URL for a work item in Azure DevOps which the messaging extension has resolved into a card.

Beispiel für eine Link-Entfaltung

Damit Ihre Messaging Erweiterung auf diese Weise mit Links interagieren kann, müssen Sie zuerst das messageHandlers Array wie im folgenden Beispiel zu Ihrem App-Manifest hinzufügen:To enable your messaging extension to interact with links this way you'll first need to add the messageHandlers array to your app manifest as in the example below:

"composeExtensions": [
  {
    "botId": "abc123456-ab12-ab12-ab12-abcdef123456",
    "messageHandlers": [
      {
        "type": "link",
        "value": {
          "domains": [
            "*.trackeddomain.com"
          ]
        }
      }
    ]
  }
]

Nachdem Sie die Domäne zum Überwachen des App-Manifests hinzugefügt haben, müssen Sie Ihren botcode so ändern, dass er auf die unten gezeigte Invoke-Anforderung antwortet .Once you've added the domain to listen on to the app manifest, you'll need to change your bot code to respond to the below invoke request.

{
  "type": "invoke",
  "name": "composeExtension/queryLink",
  "value": {
    "url": "https://theurlsubmittedbyyouruser.trackeddomain.com/id/1234"
  }
}

Wenn Ihre APP mehrere Elemente zurückgibt, wird nur die erste verwendet.If your app returns multiple items only the first will be used.

Reagieren auf BenutzeranforderungenRespond to user requests

Wenn der Benutzer eine Abfrage ausführt, gibt Microsoft Teams eine synchrone http-Anforderung an Ihren Dienst aus.When the user performs a query, Microsoft Teams issues a synchronous HTTP request to your service. An diesem Zeitpunkt hat der Code 5 Sekunden, um eine HTTP-Antwort auf die Anforderung bereitzustellen.At that point, your code has 5 seconds to provide an HTTP response to the request. Während dieser Zeit kann der Dienst zusätzliche Suchvorgänge durchführen oder eine andere Geschäftslogik, die für die Zustellung der Anforderung benötigt wird.During this time, your service can perform additional lookup, or any other business logic needed to serve the request.

Ihr Dienst sollte mit den Ergebnissen Antworten, die mit der Benutzerabfrage übereinstimmen.Your service should respond with the results matching the user query. Die Antwort muss einen HTTP-Statuscode 200 OK und ein gültiges Application/JSON-Objekt mit folgendem Text angeben:The response must indicate an HTTP status code of 200 OK and a valid application/json object with the following body:

EigenschaftsnameProperty name ZweckPurpose
composeExtension Antwortumschlag auf oberster Ebene.Top-level response envelope.
composeExtension.type Typ der Antwort.Type of response. Die folgenden Typen werden unterstützt:The following types are supported:
result: zeigt eine Liste der Suchergebnisse an.result: displays a list of search results
auth: der Benutzer wird aufgefordert, sich zu authentifizieren.auth: asks the user to authenticate
config: der Benutzer wird aufgefordert, die Messaging Erweiterung einzurichten.config: asks the user to set up the messaging extension
message: zeigt eine Nur-Text-Nachricht an.message: displays a plain text message
composeExtension.attachmentLayout Gibt das Layout der Anlagen an.Specifies the layout of the attachments. Wird für Antworten vom Typ verwendet result .Used for responses of type result.
Derzeit werden die folgenden Typen unterstützt:Currently the following types are supported:
list: eine Liste von Kartenobjekten, die Miniaturansichten, Titel und Textfelder enthaltenlist: a list of card objects containing thumbnail, title, and text fields
grid: ein Raster von Miniaturbilderngrid: a grid of thumbnail images
composeExtension.attachments Array gültiger Attachment-Objekte.Array of valid attachment objects. Wird für Antworten vom Typ verwendet result .Used for responses of type result.
Derzeit werden die folgenden Typen unterstützt:Currently the following types are supported:
application/vnd.microsoft.card.thumbnail
application/vnd.microsoft.card.hero
application/vnd.microsoft.teams.card.o365connector
application/vnd.microsoft.card.adaptive
composeExtension.suggestedActions Vorgeschlagene Aktionen.Suggested actions. Wird für Antworten vom Typ auth oder verwendet config .Used for responses of type auth or config.
composeExtension.text Anzuzeigende Meldung.Message to display. Wird für Antworten vom Typ verwendet message .Used for responses of type message.

Antwortkarten Typen und-VorschauenResponse card types and previews

Wir unterstützen die folgenden Anlagentypen:We support the following attachment types:

Eine Übersicht finden Sie unter Cards .See Cards for an overview.

Weitere Informationen zur Verwendung der Miniaturansicht-und Hero-Kartentypen finden Sie unter Add Cards and Card Actions.To learn how to use the thumbnail and hero card types, see Add cards and card actions.

Weitere Informationen zur Office 365-Verbindungskarte finden Sie unter using Office 365 Connector Cards.For additional documentation regarding the Office 365 Connector card, see Using Office 365 Connector cards.

Die Ergebnisliste wird auf der Microsoft Teams-Benutzeroberfläche mit einer Vorschau der einzelnen Elemente angezeigt.The result list is displayed in the Microsoft Teams UI with a preview of each item. Die Vorschau wird auf eine von zwei Arten generiert:The preview is generated in one of two ways:

  • Verwenden der preview -Eigenschaft innerhalb des- attachment Objekts.Using the preview property within the attachment object. Die preview Anlage kann nur eine Hero-oder Thumbnail-Karte sein.The preview attachment can only be a Hero or Thumbnail card.
  • Extrahiert aus den title Eigenschaften Basic, text und und der image Anlage.Extracted from the basic title, text, and image properties of the attachment. Diese werden nur verwendet, wenn die preview Eigenschaft nicht festgelegt ist und diese Eigenschaften verfügbar sind.These are used only if the preview property is not set and these properties are available.

Sie können eine Vorschau einer adaptiven oder Office 365-connectorkarte in der Ergebnisliste anzeigen, indem Sie einfach die zugehörige Preview-Eigenschaft festlegen; Dies ist nicht erforderlich, wenn die Ergebnisse bereits Hero-oder Thumbnail-Karten sind.You can display a preview of an Adaptive or Office 365 Connector card in the result list simply by setting its preview property; this is not necessary if the results are already hero or thumbnail cards. Wenn Sie die Vorschau Anlage verwenden, muss es sich entweder um eine Hero-oder eine Miniatur Ansichtskarte handeln.If you use the preview attachment, it must be either a Hero or Thumbnail card. Wenn keine Preview-Eigenschaft angegeben wird, schlägt die Vorschau der Karte fehl, und es wird nichts angezeigt.If no preview property is specified, the preview of the card will fail and nothing will be displayed.

AnforderungsbeispielResponse example

In diesem Beispiel wird eine Antwort mit zwei Ergebnissen gezeigt, wobei unterschiedliche Kartenformate gemischt werden: Office 365-Konnektor und adaptiv.This example shows a response with two results, mixing different card formats: Office 365 Connector and Adaptive. Während Sie wahrscheinlich mit einem Kartenformat in ihrer Antwort bleiben möchten, wird gezeigt, wie die preview Eigenschaft der einzelnen Elemente in der attachments Auflistung explizit eine Vorschau im Hero-oder Miniatur Ansichtsformat definieren muss, wie oben beschrieben.While you'll likely want to stick with one card format in your response, it shows how the preview property of each element in the attachments collection must explicitly define a preview in hero or thumbnail format as described above.

{
  "composeExtension": {
    "type": "result",
    "attachmentLayout": "list",
    "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"
                }
              ]
            }
          ]
        },
        "preview": {
          "contentType": "application/vnd.microsoft.card.thumbnail",
          "content": {
            "title": "85069: Create a cool app",
            "images": [
              {
                "url": "https://placekitten.com/200/200"
              }
            ]
          }
        }
      },
      {
        "contentType": "application/vnd.microsoft.card.adaptive",
        "content": {
          "type": "AdaptiveCard",
          "body": [
            {
              "type": "Container",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "Microsoft Corp (NASDAQ: MSFT)",
                  "size": "medium",
                  "isSubtle": true
                },
                {
                  "type": "TextBlock",
                  "text": "September 19, 4:00 PM EST",
                  "isSubtle": true
                }
              ]
            },
            {
              "type": "Container",
              "spacing": "none",
              "items": [
                {
                  "type": "ColumnSet",
                  "columns": [
                    {
                      "type": "Column",
                      "width": "stretch",
                      "items": [
                        {
                          "type": "TextBlock",
                          "text": "75.30",
                          "size": "extraLarge"
                        },
                        {
                          "type": "TextBlock",
                          "text": "▼ 0.20 (0.32%)",
                          "size": "small",
                          "color": "attention",
                          "spacing": "none"
                        }
                      ]
                    },
                    {
                      "type": "Column",
                      "width": "auto",
                      "items": [
                        {
                          "type": "FactSet",
                          "facts": [
                            {
                              "title": "Open",
                              "value": "62.24"
                            },
                            {
                              "title": "High",
                              "value": "62.98"
                            },
                            {
                              "title": "Low",
                              "value": "62.20"
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ],
          "version": "1.0"
        },
        "preview": {
          "contentType": "application/vnd.microsoft.card.thumbnail",
          "content": {
            "title": "Microsoft Corp (NASDAQ: MSFT)",
            "text": "75.30 ▼ 0.20 (0.32%)"
          }
        }
      }
    ]
  }
}

StandardabfrageDefault query

Wenn Sie initialRun true im Manifest auf festlegen, gibt Microsoft Teams eine "Standard"-Abfrage aus, wenn der Benutzer die Messaging Erweiterung zum ersten Mal öffnet.If you set initialRun to true in the manifest, Microsoft Teams issues a "default" query when the user first opens the messaging extension. Ihr Dienst kann auf diese Abfrage mit einer Reihe von vorab aufgefüllten Ergebnissen Antworten.Your service can respond to this query with a set of prepopulated results. Dies kann hilfreich sein, um beispielsweise kürzlich angezeigte Elemente, Favoriten oder andere Informationen anzuzeigen, die nicht von der Benutzereingabe abhängig sind.This can be useful for displaying, for instance, recently viewed items, favorites, or any other information that is not dependent on user input.

Die Standardabfrage hat dieselbe Struktur wie jede reguläre Benutzerabfrage, mit Ausnahme eines Parameters, initialRun dessen Zeichenfolgenwert ist true .The default query has the same structure as any regular user query, except with a parameter initialRun whose string value is true.

Anforderungs Beispiel für eine StandardabfrageRequest example for a default query

{
  "type": "invoke",
  "name": "composeExtension/query",
  "value": {
    "commandId": "searchCmd",
    "parameters": [
      {
        "name": "initialRun",
        "value": "true"
      }
    ],
    "queryOptions": {
      "skip": 0,
      "count": 25
    }
  },
  ⋮
}

Identifizieren des BenutzersIdentify the user

Jede Anforderung an ihre Dienste umfasst die verborgene ID des Benutzers, der die Anforderung ausgeführt hat, sowie den Anzeigenamen des Benutzers und die Azure Active Directory Objekt-ID.Every request to your services includes the obfuscated ID of the user that performed the request, as well as the user's display name and Azure Active Directory object ID.

"from": {
  "id": "29:1C7dbRrC_5yzN1RGtZIrcWT0xz88KPGP9sxdpVpV8sODlgPHeQE9RqQ02hnpuKzy6zZ-AaZx6swUOMj_Dsdse3TQ4sIaeebbFBF-VgjJy_nY",
  "name": "Larry Jin",
  "aadObjectId": "cd723fa0-0591-416a-9290-e93ecf3a9b92"
},

Die id aadObjectId Werte und sind garantiert die des authentifizierten Teams-Benutzers.The id and aadObjectId values are guaranteed to be that of the authenticated Teams user. Sie können als Schlüssel zum Nachschlagen von Anmeldeinformationen oder einem beliebigen zwischengespeicherten Zustand in Ihrem Dienst verwendet werden.They can be used as keys to look up credentials or any cached state in your service. Darüber hinaus enthält jede Anforderung die Azure Active Directory Mandanten-ID des Benutzers, die zum Identifizieren der Organisation des Benutzers verwendet werden kann.In addition, each request contains the Azure Active Directory tenant ID of the user, which can be used to identify the user’s organization. Wenn zutreffend, enthält die Anforderung auch die Team-und Kanal-IDs, aus denen die Anforderung stammt.If applicable, the request also contains the team and channel IDs from which the request originated.

AuthentifizierungAuthentication

Wenn Ihr Dienst eine Benutzerauthentifizierung erfordert, müssen Sie sich beim Benutzer anmelden, bevor er die Messaging Erweiterung verwenden kann.If your service requires user authentication, you need to sign in the user before he or she can use the messaging extension. Wenn Sie einen bot oder eine Registerkarte geschrieben haben, die den Benutzer signiert, sollte dieser Abschnitt vertraut sein.If you have written a bot or a tab that signs in the user, this section should be familiar.

Die Sequenz lautet wie folgt:The sequence is as follows:

  1. Der Benutzer gibt eine Abfrage aus, oder die Standardabfrage wird automatisch an den Dienst gesendet.User issues a query, or the default query is automatically sent to your service.
  2. Der Dienst überprüft, ob der Benutzer zuerst authentifiziert wurde, indem er die Benutzer-ID des Teams überprüft.Your service checks whether the user has first authenticated by inspecting the Teams user ID.
  3. Wenn der Benutzer nicht authentifiziert wurde, senden Sie eine auth Antwort mit einer openUrl vorgeschlagenen Aktion einschließlich der Authentifizierungs-URL zurück.If the user has not authenticated, send back an auth response with an openUrl suggested action including the authentication URL.
  4. Der Microsoft Teams-Client startet ein Popupfenster, das Ihre Webseite unter Verwendung der angegebenen Authentifizierungs-URL hostet.The Microsoft Teams client launches a pop-up window hosting your webpage using the given authentication URL.
  5. Nachdem sich der Benutzer angemeldet hat, sollten Sie das Fenster schließen und einen "Authentifizierungscode" an den Microsoft Teams-Client senden.After the user signs in, you should close your window and send an "authentication code" to the Teams client.
  6. Der Microsoft Teams-Client gibt dann die Abfrage erneut an Ihren Dienst aus, der den in Schritt 5 übergebenen Authentifizierungscode enthält.The Teams client then reissues the query to your service, which includes the authentication code passed in step 5.

Ihr Dienst sollte überprüfen, ob der in Schritt 6 empfangene Authentifizierungscode mit dem in Schritt 5 übereinstimmt.Your service should verify that the authentication code received in step 6 matches the one from step 5. Dadurch wird sichergestellt, dass ein böswilliger Benutzer nicht versucht, den Anmelde Ablauf vorzutäuschen oder zu gefährden.This ensures that a malicious user does not try to spoof or compromise the sign-in flow. Dies effektiv "schließt die Schleife", um die sichere Authentifizierungssequenz abzuschließen.This effectively "closes the loop" to finish the secure authentication sequence.

Reagieren mit einer AnmeldeaktionRespond with a sign-in action

Um einen nicht authentifizierten Benutzer zur Anmeldung aufzufordern, Antworten Sie mit einer vorgeschlagenen Aktion vom Typ openUrl , die die Authentifizierungs-URL enthält.To prompt an unauthenticated user to sign in, respond with a suggested action of type openUrl that includes the authentication URL.

Antwortbeispiel für eine AnmeldeaktionResponse example for a sign-in action

{
  "composeExtension":{
    "type":"auth",
    "suggestedActions":{
      "actions":[
        {
          "type": "openUrl",
          "value": "https://example.com/auth",
          "title": "Sign in to this app"
        }
      ]
    }
  }
}

Hinweis

Damit die Anmelde Umgebung in einem Teams-Popup gehostet werden kann, muss der Domänenteil der URL in der Liste der gültigen Domänen in Ihrer APP aufgeführt sein.For the sign-in experience to be hosted in a Teams pop-up, the domain portion of the URL must be in your app’s list of valid domains. (Weitere Informationen finden Sie unter validDomains im Manifest-Schema.)(See validDomains in the manifest schema.)

Starten des Anmelde FlussesStart the sign-in flow

Ihre Anmelde Erfahrung sollte reagieren und in ein Popupfenster passt.Your sign-in experience should be responsive and fit within a popup window. Sie sollte in das Microsoft Teams JavaScript Client SDKintegriert werden, das die Nachrichtenübergabe verwendet.It should integrate with the Microsoft Teams JavaScript client SDK, which uses message passing.

Wie bei anderen eingebetteten Erfahrungen, die in Microsoft Teams durchführen, muss der Code im Fenster zuerst aufgerufen werden microsoftTeams.initialize() .As with other embedded experiences running inside Microsoft Teams, your code inside the window needs to first call microsoftTeams.initialize(). Wenn Ihr Code einen OAuth-Fluss ausführt, können Sie die Benutzer-ID des Teams an das Fenster übergeben, das dann an die OAuth-Anmelde-URL übergeben werden kann.If your code performs an OAuth flow, you can pass the Teams user ID into your window, which then can pass it to the OAuth sign-in URL.

Abschließen des Anmelde FlussesComplete the sign-in flow

Wenn die Anmeldeanforderung abgeschlossen wird und zu Ihrer Seite zurückgeleitet wird, sollten Sie die folgenden Schritte ausführen:When the sign-in request completes and redirects back to your page, it should perform the following steps:

  1. Generieren Sie einen Sicherheitscode.Generate a security code. (Dies kann eine Zufallszahl sein.) Sie müssen diesen Code in Ihrem Dienst Zwischenspeichern, zusammen mit den Anmeldeinformationen, die über den Anmelde Fluss abgerufen werden (beispielsweise OAuth 2,0-Token).(This can be a random number.) You need to cache this code on your service, along with the credentials obtained through the sign-in flow (such as OAuth 2.0 tokens).
  2. Rufen Sie microsoftTeams.authentication.notifySuccess den Sicherheitscode an, und übergeben Sie ihn.Call microsoftTeams.authentication.notifySuccess and pass the security code.

Zu diesem Zeitpunkt wird das Fenster geschlossen, und die Steuerung wird an den Microsoft Teams-Client übergeben.At this point, the window closes and control is passed to the Teams client. Der Client kann jetzt die ursprüngliche Benutzerabfrage erneut ausgeben, zusammen mit dem Sicherheitscode in der state -Eigenschaft.The client now can reissue the original user query, along with the security code in the state property. Ihr Code kann den Sicherheitscode verwenden, um die zuvor gespeicherten Anmeldeinformationen nachzuschlagen, um die Authentifizierungssequenz abzuschließen und dann die Benutzeranforderung abzuschließen.Your code can use the security code to look up the credentials stored earlier to complete the authentication sequence and then complete the user request.

Beispiel für eine erneut aufgegebene AnforderungReissued request example

{
    "name": "composeExtension/query",
    "value": {
        "commandId": "insertWiki",
        "parameters": [{
            "name": "searchKeyword",
            "value": "lakers"
        }],
        "state": "12345",
        "queryOptions": {
            "skip": 0,
            "count": 25
        }
    },
    "type": "invoke",
    "timestamp": "2017-04-26T05:18:25.629Z",
    "localTimestamp": "2017-04-25T22:18:25.629-07:00",
    "entities": [{
        "type": "clientInfo",
        "country": "US",
        "platform": "Web",
        
    }],
    "text": "",
    "attachments": [],
    "address": {
        "id": "f:7638210432489287768",
        "channelId": "msteams",
        "user": {
            "id": "29:1A5TJWHkbOwSyu_L9Ktk9QFI1d_kBOEPeNEeO1INscpKHzHTvWfiau5AX_6y3SuiOby-r73dzHJ17HipUWqGPgw",
            "aadObjectId": "fc8ca1c0-d043-4af6-b09f-141536207403"
        },
        "conversation": {
            "id": "19:7705841b240044b297123ad7f9c99217@thread.skype"
        },
        "bot": {
            "id": "28:c073afa8-7e77-4f92-b3e7-aa589e952a3e",
            "name": "maotestbot2"
        },
        "serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/",
        "useAuth": true
    },
    "source": "msteams"
}

SDK-UnterstützungSDK support

.NET.NET

Wenn Sie Abfragen mit dem bot Builder SDK für .net empfangen und verarbeiten möchten, können Sie den invoke Aktionstyp für die eingehende Aktivität überprüfen und dann die Hilfsmethode im NuGet-Paket " Microsoft. bot. Connector. Teams " verwenden, um zu ermitteln, ob es sich um eine Messaging Erweiterungs Aktivität handelt.To receive and handle queries with the Bot Builder SDK for .NET, you can check for the invoke action type on the incoming activity and then use the helper method in the NuGet package Microsoft.Bot.Connector.Teams to determine whether it’s a messaging extension activity.

Beispielcode in .netExample code in .NET

public async Task<HttpResponseMessage> Post([FromBody]Activity activity)
{
    if (activity.Type == ActivityTypes.Invoke) // Received an invoke
    {
        if (activity.IsComposeExtensionQuery())
        {
            // This is the response object that will get sent back to the messaging extension request.
            ComposeExtensionResponse invokeResponse = null;

            // This helper method gets the query as an object.
            var query = activity.GetComposeExtensionQueryData();

            if (query.CommandId != null && query.Parameters != null && query.Parameters.Count > 0)
            {
                // query.Parameters has the parameters sent by client
                var results = new ComposeExtensionResult()
                {
                    AttachmentLayout = "list",
                    Type = "result",
                    Attachments = new List<ComposeExtensionAttachment>(),
                };
                invokeResponse.ComposeExtension = results;
            }

            // Return the response
            return Request.CreateResponse<ComposeExtensionResponse>(HttpStatusCode.OK, invokeResponse);
        } else
        {
            // Handle other types of Invoke activities here.
        }
    } else {
      // Failure case catch-all.
      var response = Request.CreateResponse(HttpStatusCode.BadRequest);
      response.Content = new StringContent("Invalid request! This API supports only messaging extension requests. Check your query and try again");
      return response;
    }
}

Node.jsNode.js

Beispielcode in Node.jsExample code in Node.js

require('dotenv').config();

import * as restify from 'restify';
import * as builder from 'botbuilder';
import * as teamBuilder from 'botbuilder-teams';

class App {
    run() {
        const server = restify.createServer();
        let teamChatConnector = new teamBuilder.TeamsChatConnector({
            appId: process.env.MICROSOFT_APP_ID,
            appPassword: process.env.MICROSOFT_APP_PASSWORD
        });

        // Command ID must match what's defined in manifest
        teamChatConnector.onQuery('<%= commandId %>',
            (event: builder.IEvent,
            query: teamBuilder.ComposeExtensionQuery,
            callback: (err: Error, result: teamBuilder.IComposeExtensionResponse, statusCode: number) => void) => {
                // Check for initialRun; i.e., when you should return default results
                // if (query.parameters[0].name === 'initialRun') {}

                // Check query.queryOptions.count and query.queryOptions.skip for paging

                // Return auth response
                // let response = teamBuilder.ComposeExtensionResponse.auth().actions([
                //     builder.CardAction.openUrl(null, 'https://authUrl', 'Please sign in')
                // ]).toResponse();

                // Return config response
                // let response = teamBuilder.ComposeExtensionResponse.config().actions([
                //     builder.CardAction.openUrl(null, 'https://configUrl', 'Please sign in')
                // ]).toResponse();

                // Return result response
                let response = teamBuilder.ComposeExtensionResponse.result('list').attachments([
                    new builder.ThumbnailCard()
                        .title('Test thumbnail card')
                        .text('This is a test thumbnail card')
                        .images([new builder.CardImage().url('https://bot-framework.azureedge.net/bot-icons-v1/bot-framework-default-9.png')])
                        .toAttachment()
                ]).toResponse();
                callback(null, response, 200);
            });
        server.post('/api/composeExtension', teamChatConnector.listen());
        server.listen(process.env.PORT, () => console.log(`listening to port:` + process.env.PORT));
    }
}

const app = new App();
app.run();

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