inchorus MSGraph Plugin Dokumentation

Das MSGraph-Plugin bietet Ihnen die wesentlichsten Möglichkeiten um eine Verbindung zu einem MS Graph Server herzustellen und Anfragen an ihn zu senden.

Folgende Funktionalitäten stehen zur Verfügung:

Die wesentlichen Klassen, die die Operationen am MSGraph Server bereitstellen, sind MSGraphSession zum Verwalten der Verbindung, MSGraphRequest zum definieren von Anfragen an den Server und MSGraphResponse zum Auslesen der Server-Antwort. Im Folgenden wird die grundlegende Verwendung dieser Klassen beschrieben, die Dokumentation der einzelnen Klassen finden Sie in der API Dokumentation.

Plugin einbinden

Öffnen Sie die Datei pom.xml Ihres inchorus Gadget Projektes und ergänzen Sie folgende Zeilen im Abschnitt "dependencies":

<dependency>
	<groupId>de.guh.plugin</groupId>
	<artifactId>inchorus-msgraph-plugin</artifactId>
	<version>1.0.0</version>
</dependency>

Verbindungsaufbau

Die Verbindung zum MS Graph Server wird beim Instanziieren eines MSGraphSession Objekts initialisiert, indem der Accesstoken am Login-Server angefragt wird:

String AUTHORITY = "https://login.microsoftonline.com/";
String TENANT = "87fdb820-...";
String CLIENTID = "5b18c6fe-...";
String SECRET = "XDnf.j36P8...";
String SCOPE ="https://graph.microsoft.com/.default";

MSGraphSession msgraph = new MSGraphSession(
	AUTHORITY,
	TENANT,
	CLIENTID,
	SECRET,
	SCOPE
);

if (msgraph.isReady()) {
	// Anfragen senden
} else {
	// Fehlertext anzeigen
	System.out.println(msgraph.getStatusmessage());
}

Mit dieser Instanziierung wird der Accesstoken für den, mittels seiner GUID angegebenen, Tenant am Login-Server https://login.microsoftonline.com/ angefragt. Als CLIENTID wird die am MS Graph Server registrierte ID (auch als "Application-ID" bezeichnet) angegeben, die den Nutzer bzw. das Gadget identifiziert. SECRET ist das für den Client festgelegte Passwort und SCOPE gibt den Berechtigungsbereich für die Anfragen an, in diesem Fall werden die vordefinierten Standardberechtigungen gewählt.

Die entsprechenden Parameter können z.B. in einer Konfigurationsdatei hinterlegt und von dort ausgelesen werden. Mit der Methode isReady() kann überprüft werden, ob das Generieren des Accesstokens erfolgreich war und im Anschluss können mit diesem Token HTTP Anfragen gesendet werden.

Ein expliziter Logout oder ein Schließen der Verbindung ist nicht notwendig, da jede Anfrage über den Accesstoken autorisiert wird und keine dauerhafte Verbindung besteht. Sobald der Token verfällt oder nicht mehr verfügbar ist, muss für eine weitere Anfrage erneut ein Token erstellt werden, indem ein neues MSGraphSession Objekt instantiiert wird.

Senden von Anfragen an den MS Graph Server

Anfragen an den MS Graph Server werden mit der Klasse MSGraphRequest definiert und über das oben definierte Objekt vom Typ MSGraphSession an den Server gesendet:

String resource = "users";
String select = "displayName,givenName,userType,createdDateTime";

MSGraphRequest request = new MSGraphRequest(MSGraphRequest.type_GET, resource);

request.addParameter("$select", select);

MSGraphResponse response = msgraph.sendRequest(request);

XML data = response.getDataAsXML();

Der Parameter resource bestimmt auf welche Resource sich die Anfrage bezieht, in diesem Fall auf die Resource users. Beim Erstellen eines MSGraphRequests wird der Typ der Anfrage festgelegt, in Version 1.0.0 des MSGraph Plugins sind ausschließlich Anfragen von Typ MSGraphRequest.type_GET möglich. Um die Anfrage zu spezifizieren, können weitere Parameter angehängt werden, z.B. der Parameter $select, um die abgefragten Werte der Resource zu bestimmen. Mit request.addVariable() können auch Variablen vom Typ MSGraphVariable der Anfrage hinzugefügt werden.

Das Senden der Anfrage an den MS Graph Server liefert die Antwort als Instanz einer MSGraphResponse Klasse, die im Folgenden ausgelesen werden kann. Die Klasse MSGraphResponse ist dafür verantwortlich die Antwort des Servers in einer XML Datenstruktur verfügbar zu machen. Sobald ein Objekt als Antwort auf eine Anfrage erstellt wurde, sind die entsprechenden Daten verfügbar und lassen sich mit einem Aufruf von response.getDataAsXML() auslesen.

Um bei einer Anfrage mit Paging über die Seiten zu navigieren, kann über request.setNexturi(response.getNexturi()) die Folgeanfrage erstellt werden, ohne ein neues MSGraphRequest Object definieren zu müssen. Solange response.hasNext() anzeigt, dass weitere Seiten existieren, können die entsprechenden URIs (auch als nextLink bezeichnet) aus der Server-Antwort ausgelesen werden. Eine Beispielimplementierung dazu und weitere Anwendungsbeispiele finden sich in den Beispielen.

Nähere Informationen zu den Klassen und Methoden finden sie in der API Dokumentation.

Beispiele finden Sie im Ordner Beispiele.

Bei Fragen und Anregungen nutzen Sie unser inchorus Forum.

Dieses Dokument erhalten sie hier auch als PDF.

G+H Systems GmbH

Professionell, effizient und zuverlässig.

Ludwigstraße 8

63067 Offenbach am Main

Deutschland

Telefon: +49 (0) 69 85 00 02 - 0

Fax: +49 (0) 69 85 00 02 - 51

Email: info@guh-systems.de

Web: www.guh-systems.de

Die G+H Systems leistet keinerlei Gewähr bezüglich des Inhaltes oder Gebrauchs dieser Dokumentation. Insbesondere werden keine ausdrücklichen oder stillschweigenden Gewährleistungen hinsichtlich der handelsüblichen Qualität oder Eignung für einen bestimmten Zweck übernommen. Die G+H Systems behält sich weiterhin das Recht vor, diese Dokumentation zu revidieren und ihren Inhalt jederzeit und ohne vorherige Ankündigung zu ändern.

Des Weiteren übernimmt die G+H Systems für Software keinerlei Haftung und schließt insbesondere jegliche ausdrücklichen oder impliziten Gewährleistungsansprüche bezüglich der Marktfähigkeit oder der Eignung für einen bestimmten Zweck aus. Außerdem behält sich die G+H Systems das Recht vor, G+H Software ganz oder teilweise jederzeit inhaltlich zu ändern, ohne dass für die G+H Systems die Verpflichtung entsteht, Personen oder Organisationen von diesen Überarbeitungen oder Änderungen in Kenntnis zu setzen.

Copyright © inchorus ist ein Produkt der G+H Systems GmbH

Ohne ausdrückliche, schriftliche Genehmigung des Herausgebers darf kein Teil dieser Veröffentlichung reproduziert, fotokopiert, übertragen oder in einem Speichersystem verarbeitet werden.