Registrieren Sie Ihren Connector beim Connector-Entwicklerdashboard in Office 365.Register your connector with the Office 365 Connectors developer dashboard

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.Building an Office 365 Connector for your application is easy. All you need to do is register your connector in our developer portal, add a Connect to Office 365 button to your application and implement your connector. Once you add a Connect button to your application, your users are able to use it to authorize their Office 365 Groups or Inbox to receive your actionable message cards. You can make it easy for your users to discover the connector by publishing to our catalog.

Erstellen Ihres eigenen ConnectorsBuild your own Connector

Registrieren des ConnectorsRegistering your Connector

  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.Visit the Connector Developer Portal and login with your Office 365 credentials. If you do not have an Office 365 subscription you can get a one year FREE Office 365 Subscription under the Office 365 Developer Program. Alternately, if you have an existing MSDN subscription, you can activate your free Office 365 benefit.

  2. Klicken Sie auf Neuer Connector.Click on New 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.Fill out the basic information such as name, logo, description & redirect URL. When developing the connector you can provide your localhost redirect URL.

  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.To enable your connector with actionable message, you can provide one or more target URLs. This is one or more domains corresponding to URLs that will process the actions. Your target URL can correspond to the top level domain or the subdomain of the TLD. They need to be https enabled URLs. Example: https://api.myservice.com.

  5. Ihr Connector funktioniert für Office 365-Gruppen und den Posteingang. Machen Sie Ihre Benutzer darauf aufmerksam, dass sie die Connectors in diesen Kommunikationsbereichen nutzen sollten.Choose whether your Connector needs to work with Office 365 Groups, Inbox or both. Make sure your users will benefit from those Connectors in those communication spaces.

  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.Once you save the connector information, the html code snippet for the Connect to Office 365 button is generated. The name, logo, description, company website & events you shared are displayed to a user when he tries to add a new configuration or view an existing one.

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.Once your connector is published to our catalog, users would be able to configure your connector from within Office 365. When users try to configure your connector from within Office 365, they would be taken to the link you provide in the Landing page for your users. So we recommend that you provide a deep link to the page in your product where you would add the connect button. Alternately, you can direct the user to documentation on your website on how to configure the connector on your website.

Hinzufügen der Schaltfläche Mit Office 365 verbindenAdding the Connect to Office 365 button

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.The Connect button helps your app obtain a webhook to the Group authorized by your users. Copy the generated html snippet for the Connect to Office 365 button and add it to your app. To use the Connect button your application would need an HTTPS redirect URL to receive the response. Implement the redirect URL you specified at the time of registration to listen on the query parameters state, group_name, webhook_url, error, and app_type.

<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:The query parameters in the html snippet are:

ParameterParameter DetailsDetails
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.You can use the state parameter to save your application state. If you supply a value for state it is returned back to the specified callback_url when the application returns. This is an optional parameter.
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.This is a GUID that uniquely identifies your application. This is a part of the auto-generated HTML snippet that is generated when you create a new connector & save your connector information.
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.This is the redirect URL provided when registering the connector. The callback URL should be a valid HTTPS URL without any query parameters. When the application returns successfully, the state passed, name and webhook URL of the selected group are returned as query parameters to the callback_url. If the application encounters a failure the state passed and the error code are returned to the callback_url.

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.When a user clicks on the button, the user is redirected to an Office 365 login page if the user isn't already logged in. After login the user is taken to a page with a picker that lists all the groups and/or inbox available to the user. Once the user selects a target to receive notifications on & authorizes the application, the user is redirected to the callback URL specified by the developer at the time of application registration. The selected app_type, group_name (if applicable) and the corresponding webhook URL are returned as query parameters. Ensure that you persist the app_type and the webhook URL to send connector cards. Also, make sure to prevent accidental disclosure of the webhook information by following the instructions in Secure the webhook URL. To learn more about sending connector cards see Get started with actionable messages via 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.Once you have registered your connector and implemented it using the connect button, it is fully functional & available to all your users. If you would like your users to discover your connector in our catalog, use the Publish to Store button to submit to us for approval.

Verbinden mit der Office 365-Gruppenauswahl und dem Autorisierungsfenster

Die folgenden Abfrageparameter werden in der Antwort zurückgesendet:The following query parameters are sent back in the response:

ParameterParameter DetailsDetails
state Der Parameter state, der als Abfrageparameter mit der Anforderung angegeben wurde.The state parameter provided as a query parameter with the request.
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.The name of the group selected by the user. The group_name is returned only when the application returns successfully and the user selected a group from the picker page. If the user is configuring the connector for the inbox, this parameter will not be returned.
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.The webhook URL for the selected group. Persist the webhook URL & use it to POST structured JSON to send connector cards to the group. The webhook_url is returned only when application returns successfully.
error Der Fehlercode, der zurückgegeben wird, wenn die Anwendung nicht erfolgreich zurückgegeben wird.The error code that is returned if the application doesn't return successfully.
app_type 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.
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.This is the unique id corresponding to the Office 365 user who initiated set up of the connector. It is returned only when the application returns successfully. It should be secured. This value can be used to associate the user in Office 365 who set up the configuration to the user in your service.

Sichern der Webhook-URLSecure the 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.The URL returned in webhook_url must be persisted securely and not disclosed publicly. If your callback_url webpage has external links (to other websites) there is a possibility of accidentally disclosing the webhook URL (which is present as a query parameter) through the Referrer header to these websites when users click on these links. In order to prevent such accidental disclosures, we recommend that you either implement a 302 redirect or implement a referrer policy.

Implementieren einer 302-UmleitungImplement a 302 redirect

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:After persisting the values of group_name, app_type, user_objectId, and webhook_url securely, redirect back to your callback_url (or any other URL) without these query parameters. For example, if the connector configuration process redirected to:

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:Your app securely stores the values, then redirects to a URL without these query parameters:

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

Implementieren einer VerweiserrichtlinieImplement a referrer policy

Implementieren Sie eine Verweiserrichtlinie durch Hinzufügen eines meta-Tags zum head-Abschnitt Ihrer callback_url-Webseite.Implement a referrer policy by adding a meta tag to the head section of your callback_url webpage. Sie können diese auf eine der zwei unten aufgeführten Optionen festlegen.You can set it to one of the two options listed below.

MetatagMeta tag BeschreibungDescription
<meta name="referrer" content="no-referrer"> None: Es werden nie Verweiserdaten übergeben.None: Never pass referral data.
<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.Origin Only: Sends the scheme, host, and port (basically, the subdomain) stripped of the full URL as a referrer, i.e. https://contoso.com/example.html would simply send https://contoso.com.

FehlerbehandlungError Handling

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.The error code AccessDenied is returned when the user clicks on the Deny button in group picker screen. Nothing is returned if the callback_url is not a valid HTTPS URL or the user closes the window without allowing access to your application. You would get an Invalid Request error if you modify the app_id or the callback_url in the generated html snippet. If there are no groups to select from the user is guided to try again after creating a group.

Verbinden mit dem Office 365-SandkastenConnect to Office 365 Sandbox

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.Now you can use our Sandbox environment to test out the Connect to Office 365 button. Once authorized, the sandbox lets you preview your own connector cards by viewing/editing the structured JSON payload available in the sandbox. The preview shows how your connector card would look within Outlook Groups or Inbox. You can even post the message to the group or inbox you allowed access for directly from the playground.

Veröffentlichen Ihres Connectors im StorePublish your Connector to the 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.Once you have thoroughly tested your connector and it is ready to be listed in the Office 365 connector catalog, you can use the Publish to Store button to submit it for review. Once reviewed and approved your connector would be added to the connector catalog.

Übermittlungscheckliste für den ConnectorConnector submission checklist

  • Stellen Sie sicher, dass der Connector voll funktionsfähig ist und sorgfältig getestet wurde, bevor Sie ihn an den Store übermitteln.Ensure that your connector is fully functional & thoroughly tested before submitting it to the Store.
  • 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.Test your connector cards in various clients where your users would use it: Outlook on the Web, Outlook 2016 & Outlook Groups mobile apps.
  • Stellen Sie sicher, dass Sie zur Textdekoration ausschließlich Markdown verwenden und keine HTML in der Nutzlast der Connectorkarte senden.Ensure that you strictly use Markdown for text decoration and not send HTML in your connector card payload.
  • Behalten Sie ein Gleichgewicht zwischen Mehrwert und zu viel Rauschen bei. Stellen Sie sicher, dass der Benutzer nicht durch zu viele Benachrichtigungen blockiert wird.Maintain a balance between adding value and generating too much noise. Ensure that the user is not bogged down with too many notifications.
  • 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.Identify the right events to send connector cards for. Ensure that the information you send to the group is valuable to the members of the group.
  • 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.When sending reports or summaries, use a digest format and allow the user to choose the time and frequency of the reports.
  • Setzen Sie beim Senden von Connectorkarten Markdown richtig ein, um wichtige Teile der Karte hervorzuheben.When sending connector cards make the best use of Markdown to highlight important parts of the card.
  • Sorgen Sie dafür, dass Ihre Connectorkarten umsetzbar sind, indem Sie, wann immer möglich, relevante Aktionen bereitstellen.Make your connector cards actionable by providing relevant actions whenever possible.
  • Aufgerufene Aktionen sollten eine wirklich niedrige Fehlerrate und eine schnelle Antwort durch Ihren Endpunkt aufweisen.Actions invoked should be really low in failure rate and should have fast response by your endpoint.
  • Stellen Sie sicher, dass der Benutzer die Konfiguration anhalten oder entfernen kann.Ensure that you have provisions for the user to pause or remove the configuration.
  • Sorgen Sie dafür, dass Sie eine klare, an den Benutzer gerichtete Dokumentation zu den Funktionen, die der Connector bietet, bereitstellen.Have clear user-facing documentation on the capabilities your connector offers.
  • 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.Make sure that you have implemented a 302 redirect or a referrer policy on the callback_url webpage to prevent accidental disclosure of the webhook URL.
  • Beim Registrieren des Connectors:When registering your connector:
    • 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.Ensure that the name and logo of your connector does not infringe upon a trademark or copyright of any other product or service.
    • Stellen Sie ein qualitativ hochwertiges Logo vom Typ „jpg“, „jpeg“, „png“ oder „gif“ bereit, das nicht größer als 60 KB ist.Provide a high quality logo of type jpg, jpeg, png or gif that is under 60KB in size.
    • Geben Sie eine kurze Beschreibung der Anwendung ein (z. B. „Contoso-Helpdesk vereint Firmen und Kunden“).Provide a short description of your application (e.g. 'Contoso Helpdesk brings companies & customers together').
    • 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“).Provide a detailed description of your connector (e.g. 'The Contoso Helpdesk connector notifies your Office 365 group about activity on your customer's tickets').
    • 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.The landing page for your users is the page where users would be directed to complete the connector configuration. Make sure that you deep link to the page where you have added the connect button. If this is not possible, point this to your documentation page that has detailed on how to setup your connector.
  • Beim Veröffentlichen des Connectors im Store:When publishing your connector to Store:
    • Füllen Sie die schrittweisen Anweisungen aus, und teilen Sie uns die Testkontoinformationen mit, damit wir Ihren Connector testen können.Make sure to fill out step by step instructions and share test account information to let us test your connector.

Nächste SchritteNext steps

Feedback können Sie auf UserVoice abgeben. Veröffentlichen Sie Ihre Fragen auf Stack Overflow, und markieren Sie sie mit Office365Connectors.If you have any feedback share it on UserVoice. Post your questions on Stack Overflow and tag them with Office365Connectors.