Erstellen einer Messaging Erweiterung für Microsoft TeamsCreate a messaging extension for Microsoft Teams

Tipp

Suchen Sie nach einer schnelleren Methode für den Einstieg?Looking for a faster way to get started? Erstellen Sie mithilfe des Microsoft Teams-Toolkits eine Messaging Erweiterung .Create a messaging extension using the Microsoft Teams Toolkit.

Auf einer hohen Ebene müssen Sie die folgenden Schritte ausführen, um eine Messaging Erweiterung zu erstellen.At a high level, you'll need to complete the following steps to create a messaging extension.

  1. Vorbereiten Ihrer EntwicklungsumgebungPrepare your development environment
  2. Erstellen und Bereitstellen des Webdiensts (bei der Entwicklung verwenden Sie einen Tunnel Dienst wie ngrok, um den Webdienst lokal auszuführen)Create and deploy your web service (while developing use a tunneling service like ngrok to run it locally)
  3. Registrieren Ihres Webdiensts bei Bot FrameworkRegister your web service with the Bot Framework
  4. Erstellen Ihres App-PaketesCreate your app package
  5. Hochladen Ihres Pakets in Microsoft TeamsUpload your package to Microsoft Teams

Das Erstellen Ihres Webdiensts, das Erstellen Ihres App-Pakets und das Registrieren des Webdiensts mit dem bot-Framework können in beliebiger Reihenfolge erfolgen.Creating your web service, creating your app package, and registering your web service with the Bot Framework can be done in any order. Da diese drei Teile so miteinander verflochten sind, müssen Sie zurückkehren, um die anderen zu aktualisieren, unabhängig davon, in welcher Reihenfolge Sie Sie durchführen.Because those three pieces are so intertwined, no matter which order you do them in you'll need return to update the others. Ihre Registrierung benötigt den Messaging-Endpunkt aus dem bereitgestellten Webdienst, und Ihr Webdienst benötigt die ID und das Kennwort, die aus der Registrierung erstellt wurden.Your registration needs the messaging endpoint from your deployed web service, and your web service needs the Id and password created from your registration. Ihr App-Manifest benötigt auch diese ID, um Teams mit Ihrem Webdienst zu verbinden.Your app manifest also needs that Id to connect Teams to your web service.

Während Sie Ihre Messaging-Erweiterung erstellen, werden Sie regelmäßig zwischen dem Ändern des App-Manifests und dem Bereitstellen von Code in Ihrem Webdienst fortfahren.As you're building your messaging extension, you'll regularly be moving between changing your app manifest, and deploying code to your web service. Beachten Sie beim Arbeiten mit dem App-Manifest, dass Sie entweder die JSON-Datei manuell bearbeiten oder über APP Studio Änderungen vornehmen können.When working with the app manifest, keep in mind that you can either manually manipulate the JSON file, or make changes through App Studio. In beiden Fällen müssen Sie Ihre APP in Microsoft Teams erneut bereitstellen, wenn Sie eine Änderung am Manifest vornehmen, dies ist jedoch nicht erforderlich, wenn Sie Änderungen an Ihrem Webdienst bereitstellen.Either way, you'll need to re-deploy (upload) your app in Teams when you make a change to the manifest, but there's no need to do so when you deploy changes to your web service.

Vorbereiten der EntwicklungsumgebungPrepare your development environment

Das erste, was Sie tun müssen, ist die Vorbereitung Ihrer Entwicklungsumgebung.The first thing you'll need to do is prepare your development environment. Sie müssen sicherstellen, dass das Hochladen von benutzerdefinierten Apps für die Office 365 Organisation aktiviert ist, in der Sie Ihre APP erstellen möchten.You'll need to make sure custom app uploading is enabled for the Office 365 organization you want to build your app in. Wenn Sie einen dedizierten Entwicklungsmandanten benötigen, können Sie sich für das Office 365 Entwicklerprogrammregistrieren.If you need a dedicated development tenant, you can sign up for the Office 365 developer program. Weitere Informationen finden Sie unter Einrichten der Entwicklungsumgebung.For additional information see Setup your development environment.

Erstellen Ihres WebdienstsCreate your web service

Das Herzstück Ihrer Messaging Erweiterung ist Ihr Webdienst.The heart of your messaging extension is your web service. In der Regel wird eine einzelne Route definiert, /api/messages um alle Anforderungen an zu empfangen.It will define a single route, typically /api/messages, to receive all requests on. Wenn Sie von Grund auf neu gestartet werden, stehen Ihnen einige Optionen zur Auswahl.If you're getting started from scratch, you have a few options to choose from.

  • Verwenden Sie eines unserer Schnellstart -Lernprogramme, das Sie durch die Erstellung Ihres Webdiensts führen wird.Use one of our quickstarts tutorials that will guide you through the creation of your web service.
  • Wählen Sie eines der Beispiele für die Messaging-Erweiterung aus, die im Beispiel-Repository für das bot-Framework zum Starten zur Verfügung stehen.Choose one of the messaging extension samples available in the Bot Framework sample repository to start from.
  • Wenn Sie JavaScript verwenden, verwenden Sie den Autobauer- Generator für Microsoft Teams , um Ihre Teams-APP zu Gerüsten, einschließlich des Webdiensts.If you're using JavaScript, use the Yeoman generator for Microsoft Teams to scaffold your Teams app, including your web service.
  • Erstellen Sie Ihren Webdienst von Grund auf neu.Create your web service from scratch. Sie können das Bot Framework-SDK für Ihre Sprache hinzufügen oder direkt mit den JSON-Nutzlasten arbeiten.You can choose to add the Bot Framework SDK for your language, or you can work directly with the JSON payloads.

Registrieren Ihres Webdiensts bei Bot FrameworkRegister your web service with the Bot Framework

Messaging-Erweiterungen nutzen das Messaging-Schema des bot-Frameworks und das Secure Communication-Protokoll; Wenn Sie noch nicht über einen verfügen, müssen Sie den Webdienst im bot-Framework registrieren.Messaging extensions take advantage of the Bot Framework's messaging schema and secure communication protocol; if you don't already have one you'll need to register your web service on the Bot Framework. Die Microsoft-App-ID (wir bezeichnen dies als ihre bot-ID innerhalb von Teams, um Sie von anderen APP-IDs zu identifizieren, mit denen Sie möglicherweise arbeiten) und dem Messaging-Endpunkt Ihr Register mit dem bot-Framework wird in Ihrer Messaging-Erweiterung verwendet, um Anfragen zu empfangen und darauf zu reagieren.The Microsoft App Id (we'll refer to this as your Bot Id from inside of Teams, to identify it from other App Id's you might be working with) and the messaging endpoint your register with the Bot Framework will be used in your messaging extension to receive and respond to requests. Wenn Sie eine vorhandene Registrierung verwenden, stellen Sie sicher, dass Sie den Microsoft Teams-Kanal aktivierthaben.If you're using an existing registration, make sure you enable the Microsoft Teams channel.

Wenn Sie eine der Schnellstarts ausführen oder von einem der verfügbaren Beispiele starten, werden Sie durch die Registrierung Ihres Webdiensts geführt.If you follow one of the quickstarts or start from one of the available samples you'll be guided through registering your web service. Wenn Sie Ihren Dienst manuell registrieren möchten, haben Sie drei Möglichkeiten.If you want to manually register your service you have three options to do so. Wenn Sie sich für die Registrierung ohne Verwendung eines Azure-Abonnements entscheiden, können Sie den vereinfachten OAuth-Authentifizierungs Fluss, der vom bot-Framework bereitgestellt wird, nicht nutzen.If you choose to register without using an Azure subscription you will not be able to take advantage of the simplified OAuth authentication flow provided by the Bot Framework. Sie können Ihre Registrierung nach der Erstellung nach Azure migrieren.You will be able to migrate your registration to Azure after creation.

  • Wenn Sie über ein Azure-Abonnement verfügen (oder ein neues erstellen möchten), können Sie den Webdienst manuell mithilfe des Azure-Portals registrieren.If you have an Azure subscription (or want to create a new one), you can register your web service manually using the Azure Portal. Erstellen Sie eine "bot Channels Registration"-Ressource.Create a "Bot Channels Registration" resource. Sie können die kostenlose Preisklasse auswählen, da Nachrichten von Microsoft Teams nicht auf ihre zulässigen Gesamt Nachrichten pro Monat zählen.You can choose the free pricing tier, as messages from Microsoft Teams do not count towards your total allowable messages per month.
  • Wenn Sie kein Azure-Abonnement verwenden möchten, können Sie das Legacy-Registrierungs Portalverwenden.If you do not wish to use an Azure subscription, you can use the legacy registration portal.
  • App Studio kann Sie auch bei der Registrierung Ihres Webdiensts (bot) unterstützen.App Studio can also help you register your web service (bot). Über APP Studio registrierte Webdienste sind nicht in Azure registriert.Web services registered through App Studio are not registered in Azure. Mithilfe des Legacy Portals können Sie Ihre Registrierungen anzeigen, verwalten und migrieren.You can use the legacy portal to view, manage, and migrate your registrations.

Erstellen des App-ManifestsCreate your app manifest

Sie können Ihr App-Manifest entweder in App Studio oder manuell erstellen.You can either use App Studio to help you create your app manifest, or create it manually.

Erstellen des App-Manifests mithilfe von App StudioCreate your app manifest using App Studio

Sie können die APP Studio-app innerhalb des Microsoft Teams-Clients verwenden, um das App-Manifest zu erstellen.You can use the App Studio app from within the Microsoft Teams client to help create your app manifest.

  1. Öffnen Sie App Studio im Teams-Client aus dem ...-Überlaufmenü auf der linken Navigationsleiste.In the Teams client, open App Studio from the ... overflow menu on the left navigation rail. Wenn es nicht bereits installiert ist, können Sie dies durchsuchen.If it isn't already installed, you can do so by searching for it.
  2. Klicken Sie auf der Registerkarte Manifest-Editor auf neue APP erstellen (oder wenn Sie eine Messaging Erweiterung zu einer vorhandenen APP hinzufügen, können Sie Ihr App-Paket importieren)On the Manifest editor tab select Create a new app (or if you're adding a messaging extension to an existing app, you can import your app package)
  3. Fügen Sie Ihre App-Details hinzu (in der Manifestschemadefinition finden Sie die vollständigen Beschreibungen der einzelnen Felder).Add your app details (see manifest schema definition for full descriptions of each field).
  4. Klicken Sie auf der Registerkarte Messaging Erweiterungen auf die Schaltfläche Setup .On the Messaging extensions tab click the Setup button.
  5. Sie können entweder einen neuen Webdienst (bot) erstellen, der von Ihrer Messaging-Erweiterung verwendet werden soll, oder wenn Sie sich bereits registriert haben, wählen Sie ihn aus, und fügen Sie ihn hier ein.You can either create a new web service (bot) for your messaging extension to use, or if you've already registered one select/add it here.
  6. Aktualisieren Sie Ihre Bot-Endpunktadresse bei Bedarf so, dass Sie auf Ihren Bot verweist.If necessary, update your bot endpoint address to point to your bot. Dies sollte ungefähr so aussehen: https://someplace.com/api/messages.It should look something like https://someplace.com/api/messages.
  7. Die Schaltfläche Hinzufügen im Befehls Abschnitt führt Sie durch das Hinzufügen von Befehlen zu Ihrer Messaging Erweiterung.The Add button in the Command section will guide you through adding commands to your messaging extension. Im Abschnitt Weitere Informationen finden Sie Links zu weiteren Informationen zum Hinzufügen von Befehlen.See the Learn more section for links to more information on adding commands. Denken Sie daran, dass Sie bis zu 10 Befehle für Ihre Messaging Erweiterung definieren können.Remember you can define up to 10 commands for your messaging extension.
  8. Im Abschnitt Nachrichtenhandler können Sie eine Domäne hinzufügen, die von Ihrem Messaging ausgelöst wird.The Message Handlers section allows you to add a domain that your messaging will trigger on. Weitere Informationen finden Sie unter disrolling Link .See link unfurling for more information.

Auf der Registerkarte Finish => Test and Distribute können Sie Ihr App-Paket herunterladen (das Ihr App-Manifest sowie Ihre APP-Symbole enthält) oder das Paket Installieren .From the Finish => Test and distribute tab you can Download your app package (which includes your app manifest as well as your app icons), or Install the package.

Manuelles Erstellen des App-ManifestsCreate your app manifest manually

Wie bei Bots und Tabs aktualisieren Sie das App-Manifest Ihrer APP so, dass Sie die Eigenschaften der Messaging Erweiterung enthält.As with bots and tabs, you update the app 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 das App-Manifest mit der composeExtensions -Eigenschaft ein.To add a messaging extension, include a new top-level JSON structure in your app manifest with the composeExtensions property. Sie erstellen eine einzelne Messaging Erweiterung für Ihre APP mit bis zu 10 Befehlen.You create a single messaging extension for your app, with up to 10 commands.

Hinweis

Das Manifest bezieht sich auf Messaging Erweiterungen als composeExtensions .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, wie bei Bot Framework registriert.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
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 der BefehleDefine your commands

Ihre Messaging Erweiterung sollte einen oder mehrere Befehle deklarieren, mit denen definiert wird, wo Ihre Benutzer Ihre Messaging Erweiterung auslösen können, und welche Art von Interaktion Sie haben.Your messaging extension should declare one or more commands, which define where your users can trigger your messaging extension, and the type of interaction. Weitere Informationen zu Befehlen für die Messaging Erweiterung finden Sie unter erfahren Sie mehr .See learn more for more information on messaging extension commands.

Beispiel für ein einfaches ManifestSimple manifest example

Das folgende Beispiel ist ein einfaches Messaging Erweiterungsobjekt im App-Manifest mit einem Suchbefehl.The example below is a simple messaging extension object in the app manifest with a search command. Hierbei handelt es sich nicht um die komplette App-Manifestdatei, sondern nur um den Teil der Messagingerweiterungen.This is not the entire app manifest file, just the part specific to messaging extensions. Ein vollständiges Beispiel finden Sie unter App-Manifest-Schema .See app manifest schema for a complete example.

...
"composeExtensions": [
  {
    "botId": "abcd1234-1fc5-4d97-a142-35bb662b7b23",
    "canUpdateConfiguration": true,
    "commands": [
      {
        "id": "searchCmd",
        "description": "Search you ToDo's",
        "title": "Search",
        "initialRun": true,
        "parameters": [
          {
            "name": "searchKeyword",
            "description": "Enter your search keywords",
            "title": "Keywords"
          }
        ]
      }
    ]
  }
]
...

Hinzufügen von Nachrichten Handlern für die AktivierungAdd your invoke message handlers

Wenn Ihre Benutzer Ihre Messaging-Erweiterung auslösen, müssen Sie die anfängliche Invoke-Nachricht verarbeiten, einige Informationen vom Benutzer erfassen, diese Informationen verarbeiten und entsprechend reagieren.When your users trigger your messaging extension you'll need to handle the initial invoke message, collect some information from the user, then process that information and respond appropriately. Zu diesem Zweck müssen Sie zunächst entscheiden, welche Art von Befehlen Sie Ihrer Messaging Erweiterung hinzufügen möchten, und entweder eine Aktionsbefehle hinzu fügen oder einen Suchbefehl hinzufügen.To do that, you'll first need to decide what kind of commands you want to add to your messaging extension and either add an action commands or add a search commands.

Messaging Erweiterungen in Microsoft Teams-BesprechungenMessaging extensions in Teams meetings

Sobald eine Besprechung beginnt, können Teams-Teilnehmer während eines Live-Anrufs direkt mit Ihrer Messaging-Erweiterung interagieren.Once a meeting begins, Teams participants can interact directly with your messaging extension during a live call. Berücksichtigen Sie beim Erstellen Ihrer in-Meeting-Messaging-Erweiterung Folgendes:Consider the following when building your in-meeting messaging extension:

  1. Location.Location. Ihre Messaging Erweiterung kann über den Bereich zum Verfassen von Nachrichten, das Befehlsfeld oder @mentioned im Besprechungs Chat aufgerufen werden.Your messaging extension can be invoked from the compose message area, the command box, or @mentioned in the meeting chat.

  2. Metadaten.Metadata. Wenn Ihre Messaging-Erweiterung aufgerufen wird, kann Sie den Benutzer und den Mandanten aus userId und identifizieren tenantId .When your messaging extension is invoked it can identify the user and tenant from userId and tenantId. Die meetingIdkann als Teil des Objekts channelData gefunden werden.The meetingId can be found as part of the channelData object. Ihre APP kann die userId und meetingId für die GetParticipant API-Anforderung zum Abrufen von Benutzerrollen verwenden.Your app can use the userId and meetingId for the GetParticipant API request to retrieve user roles.

  3. Befehlstyp.Command type. Wenn Ihre Nachrichten Erweiterung Aktionsbasierte Befehleverwendet, sollte Sie den Registerkarten für einmaliges Anmelden bei der Authentifizierung entsprechen.If your message extension uses action-based commands, it should follow tabs single sign-on authentication.

  4. Benutzeroberfläche.User experience. Sie sollten die beabsichtigte Endbenutzererfahrung für Messaging Erweiterungen bestimmen, die während eines Besprechungs Chats aufgerufen wurden.You should determine the intended the end-user experience for messaging extensions invoked during a meeting chat.

Nächste SchritteNext steps

Weitere InformationenLearn more

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

Erfahren Sie mehr über Konzepte für Messaging Erweiterungen:Learn more about messaging extensions concepts: