Erstellen Office 365 Connectors für Microsoft TeamsCreating Office 365 Connectors for Microsoft Teams

Mit Microsoft Teams-Apps können Sie Ihren vorhandenen Office 365-Connector hinzufügen oder einen neuen erstellen, der in Microsoft Teams enthalten sein soll.With Microsoft Teams apps, you can add your existing Office 365 Connector or build a new one to include in Microsoft Teams. Weitere Informationen finden Sie unter Erstellen eines eigenen Connectors .See Build your own Connector for more information.

Hinzufügen eines Connectors zu Ihrer Teams-AppAdding a Connector to your Teams App

Sie können Ihren registrierten Connector als Teil Ihres Teams-App-Pakets verteilen.You can distribute your registered Connector as part of your Teams app package. Ob als eigenständige Lösung oder eine von mehreren Funktionen , die ihre Erfahrung in Microsoft Teams ermöglicht, Sie können den Connector als Teil ihrer AppSource-Übermittlung Verpacken und veröffentlichen , oder Sie können ihn direkt für das Hochladen in Microsoft Teams bereitstellen.Whether as a standalone solution, or one of several capabilities that your experience enables in Teams, you can package and publish your Connector as part of your AppSource submission, or you can provide it to users directly for uploading within Teams.

Um den Connector zu verteilen, müssen Sie sich über das Entwickler Dashboard für Connectorsregistrieren.To distribute your Connector, you need to register by using the Connectors Developer Dashboard. Wenn ein Connector registriert ist, wird standardmäßig angenommen, dass der Connector in allen Office 365 Produkten, die diese unterstützen, einschließlich Outlook und Microsoft Teams, funktioniert.By default, once a Connector is registered, it's assumed that your Connector will work in all Office 365 products that support them, including Outlook and Teams. Wenn dies nicht der Fall ist und Sie einen Connector erstellen müssen, der nur in Microsoft Teams funktioniert, kontaktieren Sie uns direkt bei Microsoft Teams-App-Übermittlungen.If that is not the case and you need to create a Connector that only works in Microsoft Teams, contact us directly at Microsoft Teams App Submissions.

Wichtig

Nachdem Sie im Entwickler Dashboard für Konnektoren Speichern ausgewählt haben, ist Ihr Connector registriert.After you choose Save in the Connectors Developer Dashboard, your Connector is registered. Wenn Sie den Connector in AppSource veröffentlichen möchten, befolgen Sie die Anweisungen unter Veröffentlichen Ihrer Microsoft Teams-app in AppSource.If you want to publish your Connector in AppSource, follow the instructions in Publish your Microsoft Teams app to AppSource. Wenn Sie Ihre APP nicht in AppSource veröffentlichen möchten und Sie nur direkt an Ihre Organisation verteilen möchten, können Sie dies tun, indem Sie Sie in Ihrer Organisation veröffentlichen.If you do not wish to publish your app in AppSource, and rather simply distribute it directly to your organization only, you can do so by publishing to your organization. Wenn Sie nur in Ihrer Organisation veröffentlichen möchten, ist im Connector-Dashboard keine weitere Aktion erforderlich.If you only want to publish to your organization, no further action is necessary on the Connector dashboard.

Integrieren der KonfigurationsumgebungIntegrating the configuration experience

Ihre Benutzer werden die gesamte Connector-Konfigurationsumgebung durchführen, ohne den Microsoft Teams-Client verlassen zu müssen.Your users will complete the entire Connector configuration experience without having to leave the Teams client. Um diese Erfahrung zu erzielen, werden die Konfigurationsseiten von Microsoft Teams direkt in einen iframe eingebettet.To achieve this experience, Teams will embed your configuration page directly within an iframe. Die Reihenfolge der Vorgänge lautet wie folgt:The sequence of operations is as follows:

  1. Der Benutzer klickt auf den Connector, um den Konfigurationsprozess zu starten.The user clicks on your connector to begin the configuration process.
  2. Microsoft Teams lädt ihre Konfigurations Erfahrung in Einklang.Teams will load your configuration experience in line.
  3. Der Benutzer interagiert mit ihrer Weboberfläche, um die Konfiguration abzuschließen.The user interacts with your web experience to complete the configuration.
  4. Der Benutzer drückt "Speichern", wodurch ein Rückruf in Ihrem Code ausgelöst wird.The user presses "Save", which triggers a callback in your code.
  5. Ihr Code verarbeitet das Save-Ereignis, indem die webhook-Einstellungen abgerufen werden (unten dokumentiert).Your code will process the save event by retrieving the webhook settings (documented below). Der Code sollte dann den webhook speichern, um Ereignisse später zu veröffentlichen.Your code should then store the webhook to post events later.

Sie können Ihre vorhandene Webkonfigurations Erfahrung wieder verwenden oder eine separate Version erstellen, die speziell in Microsoft Teams gehostet wird.You can reuse your existing web configuration experience or create a separate version to be hosted specifically in Teams. Ihr Code sollte:Your code should:

  1. Schließen Sie das Microsoft Teams-JavaScript-SDK ein.Include the Microsoft Teams JavaScript SDK. Dadurch erhält der Codezugriff auf APIs, um allgemeine Vorgänge wie Abrufen des aktuellen Benutzers/Kanals/Team Kontexts und Initiieren von Authentifizierungs Flüssen auszuführen.This gives your code access to APIs to perform common operations like getting the current user/channel/team context and initiating authentication flows. Initialisieren Sie das SDK durch Aufrufen von microsoftTeams.initialize().Initialize the SDK by calling microsoftTeams.initialize().
  2. Rufen microsoftTeams.settings.setValidityState(true) Sie an, wenn Sie die Schaltfläche speichern aktivieren möchten.Call microsoftTeams.settings.setValidityState(true) when you want to enable the Save button. Sie sollten dies als Antwort auf eine gültige Benutzereingabe wie eine Auswahl oder ein Feld Update tun.You should do this as a response to valid user input, such as a selection or field update.
  3. Registrieren eines microsoftTeams.settings.registerOnSaveHandler() Ereignishandlers, der aufgerufen wird, wenn der Benutzer auf Speichern klickt.Register a microsoftTeams.settings.registerOnSaveHandler() event handler, which gets called when the user clicks Save.
  4. Aufrufen microsoftTeams.settings.setSettings() , um die Connectoreinstellungen zu speichern.Call microsoftTeams.settings.setSettings() to save the connector settings. Was hier gespeichert wird, ist auch, was im Konfigurationsdialogfeld angezeigt wird, wenn der Benutzer versucht, eine vorhandene Konfiguration für den Connector zu aktualisieren.What's saved here is also what will be shown in the configuration dialog if the user tries to update an existing configuration for your connector.
  5. Aufruf microsoftTeams.settings.getSettings() zum Abrufen von webhook-Eigenschaften, einschließlich der URL selbst.Call microsoftTeams.settings.getSettings() to fetch webhook properties, including the URL itself. Sie sollten dies zusätzlich zu während des Save-Ereignisses aufrufen, sollten Sie dies auch aufrufen, wenn die Seite beim ersten Mal im Fall einer Neukonfiguration geladen wird.You should call this In addition to during the save event, you should also call this when your page is first loaded in the case of a re-configuration.
  6. Optional Registrieren eines microsoftTeams.settings.registerOnRemoveHandler() Ereignishandlers, der aufgerufen wird, wenn der Benutzer den Connector entfernt.(Optional) Register a microsoftTeams.settings.registerOnRemoveHandler() event handler, which gets called when the user removes your connector. Dieses Ereignis gibt Ihrem Dienst die Möglichkeit, Bereinigungsaktionen auszuführen.This event gives your service an opportunity to perform any cleanup actions.

GetSettings()AntworteigenschaftenGetSettings() response properties

Hinweis

Die Parameter, die durch den getSettings Aufruf hier zurückgegeben werden, unterscheiden sich, wenn Sie diese Methode auf einer Registerkarte aufrufen und von den hierdokumentierten abweichen.The parameters returned by the getSettings call here are different than if you were to invoke this method from a tab, and differ from those documented here.

ParameterParameter DetailsDetails
entityId Die Entitäts-ID, die vom Code beim Aufruf festgelegt wird setSettings() .The entity ID, as set by your code when calling setSettings().
configName Der Konfigurationsname, wie vom Code beim Aufruf festgelegt setSettings() .The configuration name, as set by your code when calling setSettings().
contentUrl Die URL der Konfigurationsseite, die vom Code beim Aufruf festgelegt wirdsetSettings()The URL of the configuration page, as set by your code when calling setSettings()
webhookUrl Die webhook-URL, die für diesen Connector erstellt wurde.The webhook URL created for this connector. Speichern Sie die webhook-URL, und verwenden Sie Sie, um strukturiertes JSON zu veröffentlichen, um Karten an den Kanal zu senden.Persist the webhook URL and use it to POST structured JSON to send cards to the channel. webhookUrl wird nur zurückgegeben, wenn Anwendung erfolgreich zurückgegeben wird.The webhookUrl is returned only when application returns successfully.
appType Die zurückgegebenen Werte werden können mail, groups bzw. teams entsprechend Office 365-Mail, Office 365-Gruppen oder Microsoft Teams sein.The values returned can be mail, groups or teams corresponding to the Office 365 Mail, Office 365 Groups or Microsoft Teams respectively.
userObjectId Dies ist die eindeutige ID, die dem Office 365 Benutzer entspricht, der das Setup des Connectors initiiert hat.This is the unique id corresponding to the Office 365 user who initiated setup of the connector. Sie sollte gesichert werden.It should be secured. Dieser Wert kann verwendet werden, um den Benutzer in Office 365 zuzuweisen, der die Konfiguration für den Benutzer in Ihrem Dienst eingerichtet hat.This value can be used to associate the user in Office 365 who set up the configuration to the user in your service.

Wenn Sie den Benutzer als Teil des Ladens Ihrer Seite in Schritt 2 oben authentifizieren müssen, lesen Sie diesen Link , um Details darüber zu erhalten, wie Sie die Anmeldung beim Einbetten Ihrer Seite integrieren können.If you need to authenticate the user as part of loading your page in step 2 above, refer to this link for details on how you can integrate login when your page is embedded.

Hinweis

Aufgrund von clientseitigen Kompatibilitätsgründen muss Ihr Code microsoftTeams.authentication.registerAuthenticationHandlers() vor dem Aufruf mit den URL-und Success/Failure-Rückrufmethoden aufgerufen werden authenticate() .Due to cross-client compatibility reasons, your code will need to call microsoftTeams.authentication.registerAuthenticationHandlers() with the URL and success/failure callback methods before calling authenticate().

Behandeln von BearbeitungenHandling edits

Der Code sollte wiederkehrenden Benutzern ermöglichen, eine vorhandene Connector-Konfiguration zu bearbeiten.Your code should handle users returning to edit an existing connector configuration. Rufen Sie dazu microsoftTeams.settings.setSettings() während der anfänglichen Konfiguration mit den folgenden Parametern auf:To do this, call microsoftTeams.settings.setSettings() during the initial configuration with the following parameters:

  • entityIdist die benutzerdefinierte ID, die von Ihrem Dienst verstanden wird, und stellt dar, was der Benutzer konfiguriert hat.entityId is the custom ID that is understood by your service and represents what the user has configured.
  • configNameist ein Anzeigename, den Ihr Konfigurationscode abrufen kann.configName is a friendly name that your configuration code can retrieve
  • contentUrlist eine benutzerdefinierte URL, die geladen wird, wenn ein Benutzer eine vorhandene Connector-Konfiguration bearbeitet.contentUrl is a custom URL that gets loaded when a user edits an existing connector configuration. Sie können diese URL verwenden, um den Code bei der Bearbeitung des Bearbeitungs Falls zu vereinfachen.You can use this URL to make it easier for your code to handle the edit case.

Normalerweise wird dieser Aufruf als Teil des Save-Ereignishandlers ausgeführt.Typically, this call is made as part of your save event handler. Dann, wenn die contentUrl oben geladen wird, sollte Ihr Code aufrufen getSettings() , um alle Einstellungen oder Formulare in ihrer Konfigurationsbenutzeroberfläche aufzufüllen.Then, when the contentUrl above is loaded, your code should call getSettings() to prepopulate any settings or forms in your configuration UI.

Behandeln von EntfernungenHandling removals

Sie können optional einen Ereignishandler ausführen, wenn der Benutzer eine vorhandene Connector-Konfiguration entfernt.You can optionally execute an event handler when the user removes an existing connector configuration. Sie registrieren diesen Handler durch Aufrufen von microsoftTeams.settings.registerOnRemoveHandler() .You register this handler by calling microsoftTeams.settings.registerOnRemoveHandler(). Dieser Handler kann verwendet werden, um Bereinigungsvorgänge wie das Entfernen von Einträgen aus einer Datenbank durchzuführen.This handler can be used to perform cleanup operations such as removing entries from a database.

Einschließen des Konnektors in Ihr ManifestIncluding the Connector in your Manifest

Sie können das automatisch generierte Teams-App-Manifest aus dem Portal herunterladen.You can download the auto-generated Teams app manifest from the portal. Bevor Sie es verwenden können, um Ihre APP zu testen oder zu veröffentlichen, müssen Sie jedoch folgende Schritte ausführen:Before you can use it to test or publish your app, though, you must do the following:

  • Schließen Sie zwei Symbole ein, indem Sie den Anweisungen in Symbole folgen.Include two icons, following the instructions in Icons.
  • Ändern Sie den icons-Teil des Manifests so, dass er auf die Dateinamen der Symbole anstelle von URLs verweist.Modify the icons portion of the manifest to refer to the file names of the icons instead of URLs.

Die folgende manifest.JSON-Datei enthält die grundlegenden Elemente, die zum Testen und Übermitteln Ihrer APP erforderlich sind.The following manifest.json file contains the basic elements needed to test and submit your app.

Hinweis

Ersetzen Sie im folgenden Beispiel id und connectorId mit der GUID des Connectors.Replace id and connectorId in the following example with the GUID of your Connector.

Beispiel-manifest.JSON mit ConnectorExample manifest.json with Connector

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.7/MicrosoftTeams.schema.json",
  "manifestVersion": "1.5",
  "id": "e9343a03-0a5e-4c1f-95a8-263a565505a5",
  "version": "1.0",
  "packageName": "com.sampleapp",
  "developer": {
    "name": "Publisher",
    "websiteUrl": "https://www.microsoft.com",
    "privacyUrl": "https://www.microsoft.com",
    "termsOfUseUrl": "https://www.microsoft.com"
  },
  "description": {
    "full": "This is a sample manifest for an app with a connector with an inline configuration experience.",
    "short": "This is a sample manifest for an app with a connector."
  },
  "icons": {
    "outline": "sampleapp-outline.png",
    "color": "sampleapp-color.png"
  },
  "connectors": [
    {
      "connectorId": "e9343a03-0a5e-4c1f-95a8-263a565505a5",
      "configurationUrl": "https://teamstodoappconnectorwithinlineconfig.azurewebsites.net/Connector/Setup",
      "scopes": [
        "team"
      ]
    }
  ],
  "name": {
    "short": "Sample App",
    "full": "Sample App Long Name"
  },
  "accentColor": "#FFFFFF"
}

Testen des ConnectorsTesting your Connector

Um den Connector zu testen, laden Sie ihn wie jede andere App in ein Team hoch.To test your Connector, upload it to a team as you would with any other app. Sie können ein ZIP-Paket erstellen und dafür die (wie im vorherigen Abschnitt beschrieben modifizierte) Manifestdatei aus dem Entwicklerdashboard für Connectors sowie die beiden Symboldateien verwenden.You can create a .zip package using the manifest file from the Connectors Developer Dashboard (modified as directed in the preceding section) and the two icon files.

Nachdem Sie die App hochgeladen haben, öffnen Sie die Liste der Connectors von einem beliebigen Kanal aus.After you upload the app, open the Connectors list from any channel. Scrollen Sie ganz nach unten bis zu Ihrer App im Abschnitt Hochgeladenen.Scroll to the bottom to see your app in the Uploaded section.

Screenshot des Abschnitts "Hochgeladen" im Connector-Dialogfeld

Sie können nun die Konfigurationsfunktion starten.You can now launch the configuration experience. Beachten Sie, dass dieser Fluss vollständig innerhalb von Microsoft Teams als gehostete Erfahrung auftritt.Be aware that this flow occurs entirely within Microsoft Teams as a hosted experience.

Um zu überprüfen, ob eine HttpPOST Aktion ordnungsgemäß funktioniert, Senden Sie Nachrichten an den Connector.To verify that an HttpPOST action is working correctly, send messages to your connector.

Veröffentlichen von Connectors für Ihre OrganisationPublish Connectors for your organization

In einigen Fällen möchten Sie die Connector-App möglicherweise nicht im öffentlichen AppSource/Store veröffentlichen, sondern nur den Benutzern in Ihrer Organisation zur Verfügung stehen.Sometimes, you may not want to publish your connector app to the public AppSource/Store but would like it to be available only to the users in your organization. In diesen Fällen können Sie Ihre benutzerdefinierte Connector-app in den App-Katalog Ihrer Organisationhochladen.In such cases, you can upload your custom connector app to your organization's App Catalog. Auf diese Weise ist ihre Connector-app nur für diese Organisation verfügbar, und Sie müssen den Connector nicht im öffentlichen Informationsspeicher veröffentlichen.This way, your connector app will be available only to that organization, and you will not need to publish your connector to the public store.

Nachdem Sie Ihr App-Paket hochgeladen haben, können Sie den Connector in einem Team konfigurieren und verwenden, indem Sie die folgenden Schritte ausführen, um aus dem App-Katalog der Organisation zu installieren:Once you've uploaded your app package, to configure and use the connector in a Team it can be installed from the organization's app catalog by following these steps:

  1. Wählen Sie das Apps-Symbol in der vertikalen Navigationsleiste ganz links aus.Select the apps icon from the far left vertical navigation bar.
  2. Wählen Sie im Fenster apps die Option Connectorsaus.In the Apps window select Connectors.
  3. Wählen Sie den Connector aus, den Sie hinzufügen möchten, und ein Popupdialogfeld wird angezeigt.Select the connector that you want to add and a pop-up dialog window will display.
  4. Wählen Sie die Leiste zu einem Team hinzufügen aus.Select the Add to a team bar.
  5. Geben Sie im nächsten Dialogfenster einen Team-oder Kanalnamen ein.In the next dialog window type a team or channel name.
  6. Wählen Sie in der unteren rechten Ecke des Dialogfensters die Option zum Einrichten einer Verbindungs Leiste aus.Select the Set up a connector bar from the bottom right corner of dialog window.
  7. Der Connector wird im Abschnitt ●●● => Weitere Optionen => Connectors => alle => Connectors für Ihr Team für dieses Team verfügbar sein.The connector will be available in the section ●●● => More options => Connectors => All => Connectors for you team for that team. Sie können navigieren, indem Sie zu diesem Abschnitt Scrollen oder nach der Connector-App suchen.You can navigate by scrolling to this section or search for the connector app.
  8. Um den Connector zu konfigurieren oder zu ändern, wählen Sie die Leiste configure aus.To configure or modify the connector select the Configure bar.