© S&S Media
Office-365-Daten in die eigene App integrieren

Microsoft Graph verwenden


Um aus der eigenen App auf Office-365-Daten zuzugreifen, gibt es verschiedenste APIs: eins für Azure Active Directory, eins für Outlook, eins für OneDrive, eins für OneDrive for Business, eins für Office in SharePoint Online, eins für das Windows-Live-Profil, eins für das SharePoint-Profil usw. Als Entwickler ist dieser API-Dschungel für verschiedene Office-365-Dienste etwas schwierig zu handhaben. Aus diesem Grund hat Microsoft eine Fassade namens Microsoft Graph eingeführt.

Office 365 ist ein Paket aus mehreren Diensten. Es ist logisch, dass bei Microsoft die Arbeit aufgeteilt wurde und verschiedene Teams an diesen Diensten arbeiten. So gibt es beispielsweise ein Team für Azure Active Directory (AD), eins für OneDrive, eins für Outlook usw. Aufgrund der verschiedenen Teams ist es auch nicht verwunderlich, dass jeder Office-365-Dienst sein eigenes API hat. Diese Tatsache macht das Entwickeln von Anwendungen natürlich nicht einfacher: Wenn mehrere Office-365-Dienste benötigt werden, muss man im eigenen Code mit verschiedenen APIs zurechtkommen. Manchmal haben die APIs dabei Entitäten, die eigentlich das Gleiche repräsentieren, wie beispielsweise einen „User“. Aber genau dieser User ist dann in unterschiedlichen APIs anders abgebildet und hat unterschiedliche Eigenschaften. Somit kämpft man als Entwickler nicht nur mit unterschiedlichen APIs, sondern auch mit inkonsistenten Entitäten über die APIs hinweg. Microsoft Graph ist ein einziger Endpunkt, mit dem Entwickler auf Office-365-Daten zugreifen und auch Aktionen ausführen können, wie beispielsweise Dateien bearbeiten oder E-Mails versenden. Dieser Artikel zeigt die Grundlagen zu Microsoft Graph.

Ein detaillierter Blick auf die APIs

Schaut man sich die APIs für Office-365-Dienste zum ersten Mal an, ist es schwierig, einen Überblick zu bekommen. Zum Zugriff auf OneDrive lautet das API https://api.onedrive.com/v1.0/drive. Dieses API ist für das persönliche Konto. Hat ein Benutzer ein Office-365-Abo mit einem Geschäfts-/Schulkonto, dann nutzt er OneDrive for Business. Das API lautet dann https://contoso-my.sharepoint.com/personal/user_contoso_com/_api/v2.0/drive. Dabei stellt contoso-my den Tenant der Firma dar und user_contoso_com den Benutzer.

Mit Office 365 kommt auch Azure AD zum Einsatz. Mit folgenden APIs lassen sich Benutzer https://graph.windows.net/contoso.com/users und Gruppen https://graph.windows.net/contoso.com/groups abfragen. Auch ein Zugriff auf Outlook ist möglich. So lassen sich Nachrichten https://outlook.office.com/api/v2.0/me/Messages und Termine https://outlook.office.com/api/v2.0/me/Events abfragen.

Möchte man das Profil eines Benutzers abfragen, um in der eigenen App bspw. Benutzerinformationen darzustellen, gibt es für das persönliche Konto das API https://apis.live.net/v5.0/me und für das Geschäfts-/Schulkonto das API https://contoso.sharepoint.com/_api/SP.UserProfiles.PeopleManager/GetMyProperties.

Die Liste mit verschiedenen APIs ließe sich noch weiter fortsetzen. Doch glücklicherweise hat Microsoft mit Microsoft Graph eine große Vereinfachung eingeführt, um auf Office-365-Dienste einheitlich zuzugreifen.

Microsoft Graph

Die vielen verschiedenen Endpunkte für Office-365-Daten werden mit Microsoft Graph zu einem einzigen, REST-basierten Endpunkt als „einheitlichen API-Endpunkt für den Zugriff auf Daten, Informationen und Einblicke aus der Microsoft Cloud“ zusammengefasst [1]. Dieser Endpunkt lautet: http://graph.microsoft.com. Stand heute gibt es zwei Versionen des Endpunkts: v1.0 und beta. In der Betaversion werden neue Funktionen hinzugefügt, die mit der nächsten Releaseversion von Microsoft Graph erscheinen werden. v1.0 ist für den produktiven Einsatz gedacht. Die Version wird einfach entsprechend im URL mit angegeben https://graph.microsoft.com/v1.0 bzw. ­https://graph.microsoft.com/beta.

Nach der Version wird an den URL die gewünschte Ressource angehängt. So lässt sich bspw. mit /me auf das Profil des angemeldeten Benutzers zugreifen. Mit / me/drive/root/children werden die Dateien und Ordner des Wurzelverzeichnisses von OneDrive aufgelistet. Mit / me/photo/$value wird das Bild des Benutzers abgerufen, mit /me/messages die Nachrichten aus Outlook und mit me/calendar der Kalender. Mit /users und /groups wird auf die Benutzer und Gruppen des Azure ADs zugegriffen. Listing 1 zeigt einen kleinen Ausschnitt der verschiedenen Ressourcen, die unter https://graph.microsoft.com/ zur Verfügung stehen.

Listing 1

https://graph.microsoft.com/v1.0/me https://graph.microsoft.com/v1.0/me/drive/ root/children https://graph.microsoft.com/v1.0/me/photo/$value https://graph.microsoft.com/v1.0/me/messages https://graph.microsoft.com/v1.0/me/calendar https://graph.microsoft.com/v1.0/me/manager https://graph.microsoft.com/v1.0/me/memberOf https://graph.microsoft.com/v1.0/users https://graph.microsoft.com/v1.0/groups https://graph.microsoft.com/beta/me/people https://graph.microsoft.com/beta/me/tasks https://graph.microsoft.com/beta/me/notes/notebooks https://graph.microsoft.com/beta/me/trendingAround

Das Portal

Unter https://graph.microsoft.io befindet sich das offizielle Portal für Microsoft Graph. Es enthält Dokumentation, Beispiele und SDKs. Das Interessanteste ist jedoch der berühmte Graph Explorer. Er wird in der deutschen Ausgabe des Portals im Menü „Graph-Tester“ genannt [2]. Im Folgenden wird jedoch weiterhin von Graph Explorer gesprochen, da auch die Detailansicht des deutschen Portals eine kleine Inkonsistenz in der Übersetzung aufweist und ebenfalls vom Graph Explorer spricht.

Mit dem Graph Explorer lassen sich REST-Abfragen an Microsoft Graph direkt im Browser absetzen und testen. Aber ist das nicht üblich? Das ist doch der Sinn und Zweck von REST, dass über einen URL einfach Abfragen mit den HTTP-Verben GET, POST, PUT und DELETE möglich sind. Das ist natürlich richtig. Jedoch kommen bei Microsoft Graph Securitymechanismen ins Spiel, was ein direktes Abfragen über den URL ohne gültiges Securitytoken (JSON Web Token) nicht möglich macht. Denkt man darüber nach, ist es logisch. Wie sollte bspw. https://graph.microsoft.com/v1.0/me das Benutzerprofil zurückgeben, wenn nicht bekannt ist, um welchen Benutzer es sich eigentlich handelt. Es wird also ein Mechanismus zum Authentifizieren und Autorisieren benötigt, den man in die eigene App einbauen muss. Der Graph Explorer ist bereits eine App und enthält diesen Securitymechanismus in Form eines einfachen Sign-in-Links (Abb. 1).

huber_officeapps_1.tif_fmt1.jpgAbb. 1: Der Graph Explorer hat einen Sign-in-Link

Somit kann man sich beim Graph Explorer direkt mit dem eigenen Geschäfts-/Schulkonto seines Office-365-Accoun...

Neugierig geworden? Wir haben diese Angebote für dich:

Angebote für Gewinner-Teams

Wir bieten Lizenz-Lösungen für Teams jeder Größe: Finden Sie heraus, welche Lösung am besten zu Ihnen passt.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang