WMS 1.1.4

Microsoft Graph ist eine umfangreiche Sammlung verschiedener RESTful-Web-APIs, mit der auf Microsoft Cloud-Dienstressourcen zugegriffen werden kann. Um Microsoft Graph mit der Aktivität “HTTP-Request senden” nutzen zu können, benötigen Sie neben einem Registrierungsschlüssel der Anwendung auch einen geheimen Schlüssel. Wie Sie dabei vorgehen, wurde bereits bei den https://accantum.atlassian.net/wiki/spaces/APM2019DE/pages/395608065 beschrieben, Sie können dies jedoch auch direkt in der API-Beschreibung von Microsoft Graph nachlesen.

Endpunkte:

Microsoft Login: https://login.microsoftonline.com/<Verzeichnis-ID>/oauth2/v2.0/token
Microsoft Graph: https://graph.microsoft.com/v1.0

Wie wird authentifiziert? Eigener Login-Endpunkt mit Token
Wo finde ich Hilfe?

Authentifizierung: https://docs.microsoft.com/de-de/graph/auth/
Kalender: https://docs.microsoft.com/de-de/graph/outlook-calendar-concept-overview
Event-Beschreibung:

Key-Features

Verwenden von Header
Verwenden eines Contents im Format “form-url-encoded”
Verwenden eines durch Login ermittelten Bearer-Tokens

Voraussetzungen

Es liegt ein Microsoft-Konto vor, um Anwendungen zu registrieren und Berechtigungen für die Anwendungen im Azure-Portal vergeben zu können
Es wurde die Anwendung auf dem Azure-Portal registriert
Es wurde ein geheimer Clientschlüssel auf dem Azure-Portal erstellt
Berechtigung für die Anwendung, um auf den Kalender schreibend zugreifen zu können

Inhalt

1 Key-Features
2 Voraussetzungen
3 WMS: Konfiguration des HTTP-Endpunkts
- 3.1 HTTP-Endpunkt für den Login
  - 3.1.1 Test der Verbindung
- 3.2 HTTP-Endpunkt für die Graph-API (z.B. zur Termin-Erstellung)
4 Aktivität “Http-Request” 1: Token per Login ermitteln
- 4.1 Ergebnis des Logins
5 Aktivität Json-Werte ermitteln
6 Aktivität “Http-Request” 2: Termin erstellen
7 Verwandte Themen

WMS: Konfiguration des HTTP-Endpunkts

Um einen Termin in den Outlook-Kalender einzutragen, müssen zwei Endpunkte konfiguriert werden. Mit dem einen Endpunkt wird über einen Login ein Bearer-Token ermittelt, welches dann für den eigentlichen Aufruf zur Terminerstellung im Header mitgegeben werden muss. Mit dem anderen Endpunkt wird dann der Termin im Kalender erstellt.

Name	Beschreibung
Name	Name für den Endpunkt, z.B. “Microsoft Graph Login“. Aus dem Namen wird eine Zuordnungsvariable erstellt, welche bei der Aktivität verwendet werden muss.
URL	https://login.microsoftonline.com/<Verzeichnis-ID>/oauth2/v2.0/token Die Verzeichnis-ID ist aus dem Azure-Portal bei der App-Registrierung zu entnehmen
Authentifizierungsart	Keine
Header	Im Header müssen folgende Einträge hinzugefügt werden: “User-Agent” : <Name der registrierten App> “cache-control” : “no-cache”
Content	Alle für die Authentifizierung notwendigen Daten werden als FormUrlEncoded-Content angegeben. Entsprechend können folgende Parameter bereits beim Endpunkt konfiguriert werden: “client_id” : <Anwendungs-ID> (ist aus dem Azure-Portal bei der App-Registrierung zu entnehmen) “client_secret” : <Dev secret> (wird bei der Registrierung der Anwendung erzeugt und ist danach nicht mehr einsehbar!) “grant_type” : “client_credentials” “scope” : “https://graph.microsoft.com/.default“

Test der Verbindung

Wurden alle Angaben korrekt eingegeben, kann die Verbindung zum Login-Endpunkt getestet werden. Hierzu muss die HTTP-Methode “POST” angegeben werden, eine relative URL ist nicht notwendig, sofern die vollständige URL bereits wie oben beschrieben angegeben wurde.

Einstellung des Endpunkts

Header für den Login-Endpunkt

HTTP-Endpunkt für die Graph-API (z.B. zur Termin-Erstellung)

Name	Beschreibung

Name	Beschreibung
Name	Name, z.B. “Microsoft Graph”
URL	https://graph.microsoft.com/v1.0 Dies ist die Basis-Adresse der Microsoft Graph API und muss mit einer relativen URL ergänzt werden.
Authentifizierungsart	Keine
Header	Im Header müssen folgende Einträge hinzugefügt werden: “User-Agent”: <Name der registrierten App aus dem Azure Portal>

Fügen Sie Ihrem Workflow nun die Aktivität hinzu. Damit soll zunächst ein Login erfolgen.

Name	Beschreibung

Name	Beschreibung
Endpunkt	Variable für den HTTP-Endpunkt (hier: “http_MicrosoftGraphLogin”) aus den .
Relative URL	Es ist keine relative URL erforderlich
HTTP-Methode	POST
Header	Es sind keine Header erforderlich
Content	Wenn die für die Authentifizierung notwendigen Daten bereits beim Endpunkt konfiguriert wurden, brauchen hier keine weiteren form-url-encoded-Contents angegeben werden. Im Dialog zum Bearbeiten des Contents werden die beim Endpunkt konfigurierten Contents angezeigt, können jedoch nicht bearbeitet werden.

Ergebnis des Logins

Mit dem Senden des Requests wird ein Json-String als Ergebnis zurückgegeben. In dem Json-String befindet sich das “access_token”, welches für die weiteren Aufrufe angegeben werden muss (im Beispiel der Wert “xxx”).

{   
  "token_type": "Bearer",   
  "expires_in": 3599,   
  "ext_expires_in": 3599,   
  "access_token": "xxx"
}

Aktivität Json-Werte ermitteln

Fügen Sie nach dem HTTP-Request die Json-Werte ermitteln-Aktivität ein. Es soll aus der Antwort in strContent das access_token ermittelt werden.

Geben Sie in der Json-Aktivität die strContent-Variable an. Aus ihr soll die passende Eigenschaft ermittelt werden. Der Abfragetext lautet: “access_token”.

Im Ergebnis erhalten Sie nun die Eigenschaft access_token aus dem JSON-Ergebnis der Http-Aktivität (im Beispiel “xxx”). Komplexere Ausdrück können Sie auf der JMESPath-Seite nachlesen:

Mit einem Assign können Sie das Ergebnis der strToken-Variable zuweisen: strToken = aStringList.First() oder aStringList(0).

Aktivität “Http-Request” 2: Termin erstellen

Mit einem POST und mit Hilfe des Tokens aus dem Login-Request soll nun ein Termin im Outlook-Kalender eingetragen werden

Name	Beschreibung

Name	Beschreibung
Endpunkt	Variable für den HTTP-Endpunkt (hier: “http_MicrosoftGraph”) aus den .
Relative URL	users/<E-Mailadresse des Senders>/events
HTTP-Methode	POST
Header	Im Header muss das Bearer-Token übergeben werden, welches aus dem Ergebnis des Logins ausgelesen werden kann: “Authorization” : “Bearer <ermitteltes Token>“ (Leerzeichen zwischen “Bearer” und Token beachten!)
Content	Im Content werden die Daten für den Kalendereintrag im Json-Format mitUTF-8 übergeben. Details zum Content und den notwendigen Einstellungen finden sich in der Microsoft Graph API-Beschreibung. Daraus ergeben sich folgende Einstellungen: Content-Type: application/json Content: Kalender-Objekt im Json-Format Encoding: Unicode (UTF-8) mit BOM Es ist einfacher, den JSON-Text in einer Text-Datei bzw. Ressource zu erstellen und mit Platzhalter zu versehen, welche dann mit den richtigen Daten ersetzt werden, anstatt den JSON-Text direkt hier im Content einzugeben. Ggf müssen auch Sonderzeichen (z.B. das Hochkommas mit einem zweiten Hochkomma) “escaped” werden. Das kann schnell unübersichtlich werden und damit zu einem ein ungültigem Json-Objekt führen.