Erstellen von Nachrichtenerweiterungen

Nachrichtenerweiterungen ermöglichen Benutzern die Interaktion mit Ihrem Webdienst über Schaltflächen und Formulare im Microsoft Teams-Client. Benutzer können in einem externen System über den Nachrichtenbereich „Verfassen“, das Befehlsfeld oder direkt aus einer Nachricht heraus suchen oder Aktionen starten. Die Ergebnisse dieser Interaktionen können als reich formatierte Karte an den Teams-Client zurückgegeben werden.

Wichtig

Nachrichtenerweiterungen sind in Umgebungen von Government Community Cloud (GCC), GCC-High und Department of Defense (DOD) nicht verfügbar.

Der Artikel bietet eine Übersicht über Nachrichtenerweiterungen, Anwendungsfälle, Funktionen, Aktions- und Suchbefehle sowie die Entflechtung von Links.

Die folgende Abbildung zeigt die Speicherorte, an denen Nachrichtenerweiterungen aufgerufen werden können:

Hinweis

• @mentioning Nachrichtenerweiterungen im Feld "Verfassen" werden nicht unterstützt.
• Nachrichtenerweiterungsoptionen werden für Gruppenchats mit externen Benutzern nicht unterstützt.

Desktop

Mobil

Szenarien, in denen Nachrichtenerweiterungen verwendet werden

Szenario	Beispiel
Sie benötigen ein externes System, um eine Aktion auszuführen und das Ergebnis an Ihre Unterhaltung zurückzugeben.	Reservieren Sie eine Ressource und lassen Sie den Kanal das reservierte Zeitfenster kennen.
Sie müssen in einem externen System nach etwas suchen und die Ergebnisse für die Unterhaltung freigeben.	Suchen Sie in Azure DevOps nach einem Arbeitselement, und geben Sie es für die Gruppe als adaptive Karte frei.
Sie möchten eine komplexe Aufgabe mit mehreren Schritten oder großen Mengen von Informationen in einem externen System ausführen und die Ergebnisse für eine Unterhaltung freigeben.	Erstellen Sie einen Fehler in Ihrem Nachverfolgungssystem basierend auf einer Teams-Nachricht, weisen Sie diesen Fehler zu, und senden Sie eine Karte mit den Details des Fehlers an den Konversationsthread.

Grundlegendes zur Funktionsweise von Nachrichtenerweiterungen

Eine Nachrichtenerweiterung besteht aus einem von Ihnen gehosteten Webdienst und einem App-Manifest, das den Speicherort definiert, an dem Ihr Webdienst innerhalb des Teams-Clients aufgerufen wird. Der Webdienst verwendet das Messagingschema und das protokoll für die sichere Kommunikation von Bot Framework, sodass Sie Ihren Webdienst als Bot im Bot Framework registrieren müssen.

Hinweis

Es ist zwar möglich, den Webdienst manuell zu erstellen, es wird jedoch empfohlen, das Bot Framework SDK für die Verwendung des Protokolls zu verwenden.

Im App-Manifest (zuvor als Teams-App-Manifest bezeichnet) wird eine einzelne Nachrichtenerweiterung mit bis zu 10 verschiedenen Befehlen definiert. Jeder Befehl definiert einen Typ, z. B. Aktion oder Suche und die Speicherorte auf dem Client, von denen die Nachrichtenerweiterung aufgerufen wird. Zu den Aufrufspeicherorten gehören der Nachrichtenbereich zum Verfassen, die Befehlsleiste und die Nachricht. Beim Aufruf empfängt der Webdienst eine HTTPS-Nachricht mit einer JSON-Nutzlast mit allen relevanten Informationen. Antworten Sie mit einer JSON-Nutzlast, um den Teams-Client über die nächste zu aktivierende Interaktion zu informieren.

Befehlstypen der Nachrichtenerweiterung

Es gibt zwei Typen von Befehlen für Nachrichtenerweiterungen: Aktionsbefehl und Suchbefehl. Der Befehlstyp „Nachrichtenerweiterung“ definiert die Benutzeroberflächenelemente und Interaktionsflüsse, die für Ihren Webdienst verfügbar sind. Bestimmte Interaktionen, z. B. Authentifizierung und Konfiguration, sind für beide Befehlstypen verfügbar.

Aktionsbefehle

Aktionsbefehle werden verwendet, um den Benutzern ein modales Popup zum Sammeln oder Anzeigen von Informationen zu präsentieren. Wenn der Benutzer das Formular übermittelt, antwortet Ihr Webdienst, indem er eine Nachricht direkt in die Unterhaltung oder in den Nachrichtenerstellungsbereich einfügt. Später kann der Benutzer die Nachricht übermitteln. Für komplexere Workflows können Sie mehrere Formulare miteinander verknüpfen.

Aktionsbefehle werden über den Nachrichtenbereich zum Verfassen, das Befehlsfeld oder eine Nachricht ausgelöst. Wenn der Befehl aus einer Nachricht aufgerufen wird, enthält die anfängliche JSON-Nutzlast, die an Ihren Bot gesendet wird, die gesamte Nachricht, aus der er aufgerufen wurde. Die folgende Abbildung zeigt das Aktionsbefehlsdialogfeld der Nachrichtenerweiterung (in TeamsJS v1.x als Aufgabenmodul bezeichnet):

Suchbefehle

Mit Suchbefehlen können Benutzer in einem externen System nach Informationen suchen. Um Suchbefehle zu verwenden, geben Sie eine Abfrage manuell in das Suchfeld ein, oder fügen Sie einen Link zu einer überwachten Domäne in den Nachrichtenbereich zum Verfassen ein, und betten Sie dann die Suchergebnisse in eine Nachricht ein. In einem einfachen Suchbefehlsfluss enthält die anfängliche Aufrufnachricht die vom Benutzer übermittelte Suchzeichenfolge. Sie antworten mit einer Liste von Karten und Kartenvorschauen. Der Teams-Client rendert eine Liste der Kartenvorschauen für den Benutzer. Wenn der Benutzer eine Karte aus der Liste auswählt, wird sie in voller Größe in den Nachrichtenbereich „Verfassen“ eingefügt.

Die Karten werden über den Nachrichtenbereich zum Verfassen oder das Befehlsfeld ausgelöst, aber nicht über eine Nachricht. Sie können nicht von einer Nachricht ausgelöst werden. Die folgende Abbildung zeigt das Dialogfeld für den Suchbefehl der Nachrichtenerweiterung:

Hinweis

Weitere Informationen zu Karten finden Sie unter Was sind Karten.

Verbreiten von Links

Hinweis

Das Entpacken von Links wird nur für botbasierte Nachrichtenerweiterungen unterstützt.

Wenn eine URL in den Nachrichtenbereich zum Verfassen eingefügt wird, wird ein Webdienst aufgerufen. Diese Funktionalität wird als Verbreiten von Links bezeichnet. Sie können eine Aufrufnachricht abonnieren, wenn URLs, die eine bestimmte Domäne enthalten, in den Nachrichtenbereich zum Verfassen eingefügt werden. Ihr Webdienst kann die URL in einem detaillierten Karte entpacken und mehr Informationen als die Standard-Websitevorschau Karte. Sie können Schaltflächen hinzufügen, damit benutzer sofort Maßnahmen ergreifen können, ohne den Teams-Client zu verlassen. Die folgenden Abbildungen zeigen die Funktion zum Entpacken von Links, wenn ein Link in eine Nachrichtenerweiterung eingefügt wird:

Erstellen von Nachrichtenerweiterungen

Wenn Sie noch keine haben, gibt es zwei Möglichkeiten, eine Nachrichtenerweiterung zu erstellen:

• Erstellen von Nachrichtenerweiterungen mithilfe der API (API-basiert): Sie können ganz einfach eine Nachrichtenerweiterung aus einer vorhandenen API erstellen. Für diese Methode ist ein OAD-Dokument (OpenAPI Description) erforderlich.

• Erstellen von Nachrichtenerweiterungen mithilfe von Bot Framework (Bot-basiert): Wenn Sie eine 1-zu-1-Konversation wünschen, können Sie eine neue Nachrichtenerweiterung aus einem Bot erstellen.

Die folgende Tabelle hilft Ihnen bei der Auswahl eines Nachrichtenerweiterungstyps für den Einstieg:

API-basierte Nachrichtenerweiterung

• Einfacher und schneller zu erstellen und zu verwalten.
• Die Nachrichtenerweiterung verwendet eine API.
• Für die Botlogik ist kein zusätzlicher Code oder keine zusätzliche Ressource erforderlich.
• Ideal für Szenarien, in denen die Nachrichtenerweiterung nur mit einem Webdienst kommunizieren muss und keine komplexe Logik oder Zustandsverwaltung benötigt.
• Der Datenverkehr wird privatisiert, da er nicht von der Azure-Botinfrastruktur abhängt.
• Unterstützt Suchbefehle.

Botbasierte Nachrichtenerweiterung

• Flexibler.
• Die Nachrichtenerweiterung verwendet ein Bot Framework.
• Kann die vollständigen Funktionen eines Bots nutzen.
• Ideal für Szenarien, in denen die Nachrichtenerweiterung mit mehreren Diensten kommunizieren, komplexe Logik oder Benutzerinteraktionen verwalten oder den Zustand sitzungsübergreifend beibehalten muss.
• Unterstützt Aktionsbefehle, Suchbefehle und Das Entpacken von Links.

Wählen Sie eine Option aus, um mit dem Erstellen einer Nachrichtenerweiterung zu beginnen:

      

      

Codebeispiel

Beispielname	Beschreibung	.NET	Node.js	Python	Manifest
Nachrichtenerweiterung mit aktionsbasierten Befehlen	In diesem Beispiel wird gezeigt, wie Sie Aktionsbefehle definieren, einen Dialog erstellen und auf die Aktion "Dialog übermitteln" reagieren.	View	View	View	View
Nachrichtenerweiterung mit suchbasierten Befehlen	In diesem Beispiel wird gezeigt, wie Sie eine suchbasierte Nachrichtenerweiterung erstellen. Es durchsucht NuGet-Pakete und zeigt die Ergebnisse in der suchbasierten Messagingerweiterung an.	View	View	View	View
Vorschau der Aktion "Nachrichtenerweiterung"	In diesem Beispiel wird gezeigt, wie Sie die Aktionsvorschau in Messagingerweiterungen mit Bot Framework v4 verwenden.	View	View	–	Anzeigen
Nachrichtenerweiterungsaktion für die Aufgabenplanung	In diesem Beispiel wird gezeigt, wie Sie eine Aufgabe über den Aktionsbefehl für die Nachrichtenerweiterung planen und eine Erinnerung Karte zu einem geplanten Datum und einer geplanten Uhrzeit erhalten.	View	View	–	View
Northwind-Bestandsnachrichtenerweiterung	In diesem Beispiel wird veranschaulicht, wie Eine Teams-Nachrichtenerweiterung als Agent in Microsoft 365 Copilot verwendet wird.	–	View	–	–