Registrieren Sie Ihren Connector beim Connector-Entwicklerdashboard in Office 365.

Das Erstellen eines Office 365-Connectors für Ihre Anwendung ist ein Kinderspiel. Sie müssen den Connector lediglich in unserem Entwicklerportal registrieren, die Schaltfläche Mit Office 365 verbinden zu Ihrer Anwendung hinzufügen und den Connector implementieren. Sobald Sie diese Schaltfläche zu Ihrer Anwendung hinzugefügt haben, können ihre Benutzer diese verwenden, um ihre Office 365-Gruppen oder ihren Posteingang zum Empfangen Ihrer Nachrichtenkarten mit Aktionen zu autorisieren. Durch eine Veröffentlichung in unserem Katalog können Sie es Ihren Benutzern einfacher machen, den Connector zu finden.

Erstellen Ihres eigenen Connectors

Registrieren des Connectors

  1. Besuchen Sie das Connector-Entwicklerportal, und melden Sie sich mit Ihren Office 365-Anmeldeinformationen an. Wenn Sie nicht über ein Office 365-Abonnement verfügen, können Sie ein KOSTENLOSES Office 365-Abonnement für ein Jahr unter dem Office 365-Entwicklerprogramm abschließen. Wenn Sie über ein vorhandenes MSDN-Abonnement verfügen, können Sie Ihren kostenlosen Office 365-Vorteil aktivieren.

  2. Klicken Sie auf Neuer Connector.

  3. Füllen Sie die grundlegenden Informationen wie Name, Logo, Beschreibung und Umleitungs-URL aus. Beim Entwickeln des Connectors können Sie die localhost-Umleitungs-URL angeben.

  4. Um den Connector mit einer Nachricht mit Aktionen zu aktivieren, können Sie eine oder mehrere Ziel-URLs angeben. Hierbei handelt es sich um eine oder mehrere Domänen, die URLs entsprechen, die die Aktionen verarbeiten. Ihre Ziel-URL kann der Domäne der obersten Ebene oder der Unterdomäne der TLD entsprechen. Es muss sich um https-fähige URLs handeln. Beispiel: https://api.myservice.com.

  5. Wählen Sie aus, ob der Connector für Office 365-Gruppen, den Posteingang oder für beides funktionieren soll. Stellen Sie sicher, dass Ihre Benutzer diese Connectors in diesen Kommunikationsbereichen nutzen.

  6. Nachdem Sie die Connectorinformationen gespeichert haben, wird der HTML-Codeausschnitt für die Schaltfläche Mit Office 365 verbinden generiert. Der Name, das Logo, die Beschreibung, die Unternehmenswebsite und die Ereignisse, die Sie freigegeben haben, werden einem Benutzer angezeigt, wenn er versucht, eine neue Konfiguration hinzuzufügen oder eine vorhandene anzuzeigen.

Nachdem der Connector in unserem Katalog veröffentlicht wurde, können Benutzer Ihren Connector aus Office 365 heraus konfigurieren. Wenn Benutzer versuchen, Ihren Connector aus Office 365 heraus zu konfigurieren, würden sie zu dem Link gelangen, den Sie auf der Zielseite für Ihre Benutzer angeben. Wir empfehlen daher, dass Sie einen Deep-Link zu der Seite in Ihrem Produkt angeben, an dem Sie die Schaltfläche zum Verbinden hinzufügen. Alternativ können Sie den Benutzer zur Dokumentation auf Ihrer Website leiten, wo die Konfiguration des Connectors auf Ihrer Website beschrieben wird.

Hinzufügen der Schaltfläche Mit Office 365 verbinden

Mit der Schaltfläche „Verbinden“ kann Ihre App einen Webhook in die Gruppe abrufen, die von Ihren Benutzern autorisiert wurde. Kopieren Sie den generierten HTML-Codeausschnitt für die Schaltfläche Mit Office 365 verbinden, und fügen Sie diesen Ihrer App hinzu. Um die Schaltfläche „Verbinden“ in Ihrer Anwendung zu verwenden, benötigen Sie eine HTTPS-Umleitungs-URL, um die Antwort zu erhalten. Implementieren Sie die Umleitungs-URL, die Sie zum Zeitpunkt der Registrierung angegeben haben, um für die Abfrageparameter state, group_name, webhook_url, error und app_type zu lauschen.

<a href="https://outlook.office.com/connectors/Connect?state=myAppsState&app_id=a3c4ef20-68aa-42e1-b037-f75624dacf21&callback_url=http://localhost:3000/callback">
  <img src="https://o365connectors.blob.core.windows.net/images/ConnectToO365Button.png" alt="Connect to Office 365"></img>
</a>

Die Abfrageparameter im HTML-Codeausschnitt sind:

Parameter Details
state Sie können den Parameter state verwenden, um den Anwendungsstatus zu speichern. Wenn Sie einen Wert für state angeben, wird dieser an die angegebene callback_url zurückgegeben, wenn die Anwendung zurückgegeben wird. Der Parameter ist optional.
app_id Dies ist eine GUID, die Ihre Anwendung eindeutig identifiziert. Dies ist ein Teil des automatisch generierten HTML-Codeausschnitts, der generiert wird,wenn Sie einen neuen Connector erstellen und die Connectorinformationen speichern.
callback_url Dies ist die Umleitungs-URL, die bei der Registrierung des Connectors angegeben wird. Die Rückruf-URL sollte eine gültige HTTPS-URL ohne Abfrageparameter sein. Wenn die Anwendung erfolgreich zurückgegeben wird, werden der übergebene Status, der Name und die Webhook-URL der ausgewählten Gruppe als Abfrageparameter an die callback_url zurückgegeben. Wenn die Anwendung auf einen Fehler stößt, werden der übergebene Status und der Fehlercode an die callback_url zurückgegeben.

Wenn ein Benutzer auf die Schaltfläche klickt, wird der Benutzer zu einer Office 365-Anmeldeseite umgeleitet, wenn der Benutzer nicht bereits angemeldet ist. Nach der Anmeldung wird der Benutzer zu einer Seite mit einer Auswahl geleitet, in der alle Gruppen und/oder Posteingänge aufgeführt sind, die für den Benutzer verfügbar sind. Nachdem der Benutzer ein Ziel zum Empfangen von Benachrichtigungen ausgewählt und die Anwendung autorisiert hat, wird der Benutzer zur Rückruf-URL weitergeleitet, die vom Entwickler zum Zeitpunkt der Anwendungsregistrierung angegeben wurde. Das ausgewählte app_type, group_name (falls zutreffend) und die entsprechende Webhook-URL werden als Abfrageparameter zurückgegeben. Stellen Sie sicher, dass Sie app_type und die Webhook-URL speichern, um Connectorkarten zu senden. Stellen Sie außerdem sicher, dass eine unbeabsichtigte Veröffentlichung der Webhook-Informationen verhindert wird, indem Sie die Anweisungen in Sichern der Webhook-URL befolgen. Weitere Informationen zum Senden von Connectorkarten finden Sie unter Erste Schritte mit Nachrichten mit Aktionen über Connectors.

Sobald Sie den Connector registriert und mithilfe der Schaltfläche „Verbinden“ implementiert haben, ist er voll funktionsfähig und für alle Benutzer verfügbar. Wenn Sie möchten, dass Ihre Benutzer den Connector in unserem Katalog finden können, verwenden Sie die Schaltfläche Im Store veröffentlichen, um ihn an uns zur Genehmigung zu übermitteln.

Verbinden mit der Office 365-Gruppenauswahl und dem Autorisierungsfenster

Die folgenden Abfrageparameter werden in der Antwort zurückgesendet:

Parameter Details
state Der Parameter state, der als Abfrageparameter mit der Anforderung angegeben wurde.
group_name Der Name der vom Benutzer ausgewählten Gruppe. group_name wird nur zurückgegeben, wenn die Anwendung erfolgreich zurückgegeben wird und der Benutzer eine Gruppe auf der Auswahlseite ausgewählt hat. Wenn der Benutzer den Connector für den Posteingang konfiguriert, wird dieser Parameter nicht zurückgegeben.
webhook_url Die Webhook-URL für die ausgewählte Gruppe. Speichern Sie die Webhook-URL, und verwenden Sie sie zum POSTEN von strukturiertem JSON, um Connectorkarten an die Gruppe zu senden. webhook_url wird nur zurückgegeben, wenn Anwendung erfolgreich zurückgegeben wird.
error Der Fehlercode, der zurückgegeben wird, wenn die Anwendung nicht erfolgreich zurückgegeben wird.
app_type Die zurückgegebenen Werte werden können mail, groups bzw. teams entsprechend Office 365-Mail, Office 365-Gruppen oder Microsoft Teams sein.
user_objectId Hierbei handelt es sich um die eindeutige ID, die dem Office 365-Benutzer entspricht, der die Einrichtung des Connectors initiiert hat. Sie wird nur zurückgegeben, wenn die Anwendung erfolgreich zurückgegeben wird. Sie sollte gesichert werden. Dieser Wert kann verwendet werden, um den Benutzer in Office 365 zuzuweisen, der die Konfiguration für den Benutzer in Ihrem Dienst eingerichtet hat.

Sichern der Webhook-URL

Die in webhook_url zurückgegebene URL muss sicher gespeichert und darf nicht veröffentlicht werden. Wenn Ihre callback_url-Webseite externe Links (zu anderen Websites) aufweist, besteht die Möglichkeit, dass die Webhook-URL (die als Abfrageparameter vorhanden ist) versehentlich über den Referrer-Header auf diesen Websites veröffentlicht wird, wenn Benutzer auf diese Links klicken. Um solche versehentlichen Veröffentlichungen zu verhindern, wird empfohlen, dass Sie entweder eine 302-Umleitung implementieren oder eine Verweiserrichtlinie implementieren.

Implementieren einer 302-Umleitung

Nach dem sicheren Speichern der Werte group_name, app_type, user_objectId und webhook_url werden Sie zurück an Ihre callback_url (oder eine andere URL) ohne diese Abfrageparameter geleitet. Wenn der Konfigurationsvorgang des Connectors beispielsweise folgendermaßen umgeleitet wurde:

http://contoso.com/integrations/Office365/callback?state=myState&webhook_url=myWebhookUrl&group_name=selectedGroupName&user_objectId=uniqueIdOfUser&app_type=Groups

Ihre App speichert die Werte sicher und führt dann eine Umleitung zu einer URL ohne die Abfrageparameter aus:

http://contoso.com/integrations/Office365/callback

Implementieren einer Verweiserrichtlinie

Implementieren Sie eine Verweiserrichtlinie durch Hinzufügen eines meta-Tags zum head-Abschnitt Ihrer callback_url-Webseite. Sie können diese auf eine der zwei unten aufgeführten Optionen festlegen.

Metatag Beschreibung
<meta name="referrer" content="no-referrer"> None: Es werden nie Verweiserdaten übergeben.
<meta name="referrer" content="origin"> Nur Herkunft: Sendet Schema, Host und Port (im Grunde die Subdomäne) ohne die vollständige URL als Verweiser, d.h. https://contoso.com/example.html würde nur https://contoso.com senden.

Fehlerbehandlung

Der Fehlercode AccessDenied wird zurückgegeben, wenn der Benutzer auf die Schaltfläche Verweigern auf dem Gruppenauswahlbildschirm klickt. Es wird nichts zurückgegeben, wenn callback_url keine gültige HTTPS-URL ist oder der Benutzer das Fenster schließt, ohne Zugriff auf Ihre Anwendung zu gewähren. Sie würden einen Invalid Request-Fehler erhalten, wenn Sie app_id oder callback_url im generierten HTML-Codeausschnitt ändern. Wenn es keine Gruppen zur Auswahl gibt, sollte der Benutzer den Vorgang nach dem Erstellen einer Gruppe erneut versuchen.

Verbinden mit dem Office 365-Sandkasten

Jetzt können Sie unsere Sandkastenumgebung zum Testen der Schaltfläche Mit Office 365 verbinden verwenden. Nach der Autorisierung können Sie Ihre eigenen Connectorkarten im Sandkasten in der Vorschau anzeigen, indem Sie die strukturierte JSON-Nutzlast anzeigen/bearbeiten, die im Sandkasten verfügbar ist. Die Vorschau zeigt, wie Ihre Connectorkarte innerhalb von Outlook-Gruppen oder im Posteingang aussehen würde. Sie können sogar die Nachricht in der Gruppe oder in dem Posteingang veröffentlichen, für die bzw. den Sie direkt aus dem Playground Zugriff gewährt haben.

Veröffentlichen Ihres Connectors im Store

Nachdem Sie Ihren Connector sorgfältig getestet haben und er im Office 365- Connectorkatalog aufgeführt werden kann, können Sie die Schaltfläche Im Store veröffentlichen verwenden, um ihn zur Überprüfung zu übermitteln. Nach Überprüfung und Genehmigung wird der Connector dem Connectorkatalog hinzugefügt.

Übermittlungscheckliste für den Connector

  • Stellen Sie sicher, dass der Connector voll funktionsfähig ist und sorgfältig getestet wurde, bevor Sie ihn an den Store übermitteln.
  • Testen Sie Ihre Connectorkarten in verschiedenen Clients, auf denen die Benutzer sie verwenden würden: Outlook im Web-, Outlook 2016- und Mobile Outlook Groups-Apps.
  • Stellen Sie sicher, dass Sie zur Textdekoration ausschließlich Markdown verwenden und keine HTML in der Nutzlast der Connectorkarte senden.
  • Behalten Sie ein Gleichgewicht zwischen Mehrwert und zu viel Rauschen bei. Stellen Sie sicher, dass der Benutzer nicht durch zu viele Benachrichtigungen blockiert wird.
  • Identifizieren Sie die richtigen Ereignisse, für die Sie Connectorkarten senden. Stellen Sie sicher, dass die Informationen, die Sie an die Gruppe senden, für die Mitglieder der Gruppe hilfreich sind.
  • Verwenden Sie beim Senden von Berichten oder Zusammenfassungen ein Digestformat, und ermöglichen Sie dem Benutzer, die Uhrzeit und die Häufigkeit der Berichte auszuwählen.
  • Setzen Sie beim Senden von Connectorkarten Markdown richtig ein, um wichtige Teile der Karte hervorzuheben.
  • Sorgen Sie dafür, dass Ihre Connectorkarten umsetzbar sind, indem Sie, wann immer möglich, relevante Aktionen bereitstellen.
  • Aufgerufene Aktionen sollten eine wirklich niedrige Fehlerrate und eine schnelle Antwort durch Ihren Endpunkt aufweisen.
  • Stellen Sie sicher, dass der Benutzer die Konfiguration anhalten oder entfernen kann.
  • Sorgen Sie dafür, dass Sie eine klare, an den Benutzer gerichtete Dokumentation zu den Funktionen, die der Connector bietet, bereitstellen.
  • Stellen Sie sicher, dass Sie eine 302-Umleitung oder eine Verweiserrichtlinie auf der callback_url-Webseite implementiert haben, um eine unbeabsichtigte Veröffentlichung der Webhook-URL zu verhindern.
  • Beim Registrieren des Connectors:
    • Stellen Sie sicher, dass der Name und das Logo des Connectors keinen Verstoß gegen ein Markenzeichen oder ein Urheberrecht eines anderen Produkts oder Diensts darstellen.
    • Stellen Sie ein qualitativ hochwertiges Logo vom Typ „jpg“, „jpeg“, „png“ oder „gif“ bereit, das nicht größer als 60 KB ist.
    • Geben Sie eine kurze Beschreibung der Anwendung ein (z. B. „Contoso-Helpdesk vereint Firmen und Kunden“).
    • Stellen Sie eine ausführliche Beschreibung des Connectors bereit (z. B. „Der Connector des Contoso-Helpdesks benachrichtigt Ihre Office 365-Gruppe bei Aktivitäten bei den Tickets Ihrer Kunden“).
    • Die Zielseite für Ihre Benutzer ist die Seite, auf die Benutzer geleitet werden, um die Connectorkonfiguration abzuschließen. Vergewissern Sie sich, dass Sie einen Deep-Link zu der Seite bereitstellen, auf der Sie die Schaltfläche zum Verbinden hinzugefügt haben. Wenn dies nicht möglich ist, verweisen Sie auf Ihre Dokumentationsseite, die ausführliche Informationen darüber enthält, wie der Connector eingerichtet wird.
  • Beim Veröffentlichen des Connectors im Store:
    • Füllen Sie die schrittweisen Anweisungen aus, und teilen Sie uns die Testkontoinformationen mit, damit wir Ihren Connector testen können.

Nächste Schritte

Feedback können Sie auf UserVoice abgeben. Veröffentlichen Sie Ihre Fragen auf Stack Overflow, und markieren Sie sie mit Office365Connectors.