Microsoft Flow – Nutzung der SharePoint REST API

Die REST API Endpunkte von SharePoint erlauben den externen Zugriff auf SharePoint und ermöglichen damit die Umsetzung einer Vielzahl von Anwendungsfällen. Sei es das Erstellen oder Löschen von Elementen in Listen, das Anpassen von Metadaten der Dateien in Bibliotheken, Veränderungen an den Listen und Bibliotheken selbst oder auch das Setzen von Permissions. Durch Zugriffe über die REST API lassen sich viele Vorgänge mit Microsoft Flow automatisieren.
Das geht zwar mit einigen Standardaktionen in Flow auch, allerdings sind diese Aktionen häufig zu umfangreich oder sind noch nicht ganz ausgereift und verändern sich deshalb immer wieder.

 

Um die SharePoint API in Flow zu nutzen, muss der Flow sich authentifizieren. Hierfür müssen einige Schritte durchgeführt werden:

Registrieren eines Add-Ins mit den nötigen Zugriffsrechten

Um ein Add-In zu registrieren, ruft man über die folgende URL die Add-In Registrierungsseite auf.

https://<site collection>/_layouts/15/appregnew.aspx

Abbildung 1: Add-In registrieren
Abbildung 1: Add-In registrieren

In dem Formular müssen dann Titel, App Domain und Redirect URL eingetragen werden. Als App Domain wird “localhost” und als Redirect URL “https://localhost” eingetragen. Der Titel ist frei wählbar. Client ID und Client Secret werden durch einen Klick auf den jeweiligen “Generate”-Button automatisch generiert.

Sind alle Informationen eingetragen, wird das Add-In durch einen Klick auf “Create” erstellt. Im Anschluss erhält man folgende Übersicht. Client ID und Client Secret werden in den folgenden Schritten benötigt, deshalb bietet es sich an, diese Informationen in einer Textdatei oder einem OneNote zu notieren.

Abbildung 2: Add-In Übersicht
Abbildung 2: Add-In Übersicht

Nachdem das Add-In erstellt wurde, müssen ihm noch die nötigen Berechtigungen erteilt werden. Welche Berechtigungen benötigt werden, ist davon abhängig welche Aufgaben der Flow über die REST API bewältigen soll. Das Add-In muss die gleichen Berechtigungen erhalten, die auch ein einzelner Nutzer, der diese Aufgaben erledigen kann, besitzt.

Um die Berechtigungen zu gewähren, muss die folgende URL aufgerufen werden:

https://<site collection>/_layouts/15/appinv.aspx

Abbildung 3: Berechtigungen erteilen
Abbildung 3: Berechtigungen erteilen

Zuerst muss man im Feld App ID die vorher erhaltene Client ID eintragen. Durch einen Klick auf “Lookup” sucht SharePoint nach dem Add-In mit der angegebenen Client ID. Wenn SharePoint das Add-In gefunden hat, sollten die ersten vier Felder mit den passenden Werten aus der vorherigen Übersicht ausgefüllt sein.

In das letzte Feld wird das XML zum Erteilen der Berechtigungen eingefügt.

<AppPermissionRequests AllowAppOnlyPolicy=”true”>
    <AppPermissionRequest 
         Scope=”http://sharepoint/content/sitecollection/web” 
         Right=”FullControl” />
</AppPermissionRequests>

Das Attribut “Right” gibt an, welche Berechtigungen die App erhalten soll. In diesem Beispiel erhält das Add-In, respektive unser Flow, Vollzugriff auf die Site Collection und alle darunter liegenden Inhalte.

Für weitere Informationen zu den verschiedenen Berechtigungsstufen und Geltungsbereichen für die Berechtigungen ist dieser Link hilfreich.

Abbildung 4: Add-In vertrauen
Abbildung 4: Add-In vertrauen

War das XML korrekt, wird SharePoint nach einem Klick auf “Create” fragen, ob man dem Add-In vertrauen möchte. Nach einem Klick auf “Trust It” werden die Berechtigungen erteilt und der erste Schritt zur Authentifizierung unseres Flows ist erledigt.

Beziehen der Tenant ID

Als nächstes müssen wir die Tenant ID beziehen. Dazu schicken wir einen GET Request an SharePoint. Um den Request zu versenden, eignet sich am besten die Software Postman.

Der Endpunkt unseres Requests lautet wie folgt:

https://<site collection>/sharepoint.com/_vti_bin/client.svc/

Zusätzlich muss bei unserem Request in den Header der Key “Authorization” mit dem Value “Bearer” eingetragen werden. Anschließend kann der Request abgeschickt werden und wir erhalten folgende Response Headers:

Abbildung 5: Beziehen der Tenant ID
Abbildung 5: Beziehen der Tenant ID

Der Wert von “Bearer realm” ist unsere Tenant ID. Der Wert von “client_id” enthält Ressourceninformationen, die wir ebenfalls im nächsten Schritt benötigen.

Hier nochmal eine kurze Zusammenfassung der benötigten Informationen, die wir gesammelt haben:

  1. Client Id: e9d11d84-1290-xxxx-b278-xxxba720f049
  2. Client Secret: 598CQuPcKUNxxxxxxxxxxxxx8+JftSNlg/qAX6eV4gI=
  3. Tenant Id: b3d594a3-b9ce-xxxx-9ef9-xxxxxxxxxxxx
  4. Resource: 00000003-0000-0ff1-ce00-000000000000

Mit diesen Informationen können wir über einen weiteren Web Request einen Access Token generieren. Der Access Token dient unserem Flow dann bei allen Web Requests als Authentifizierung.

Beziehen des Access Tokens

Es ist empfehlenswert den Request in Postman zu erstellen, um zu prüfen, ob er wie gewünscht funktioniert. Anschließend sollte der Request aber in Flow übernommen werden, da der Token nach einer gewissen Zeit abläuft und deshalb regelmäßig ein neuer Token angefragt werden muss.

Es handelt sich dieses Mal um einen POST Request, der an folgenden Endpunkt gesendet wird:

https://accounts.accesscontrol.windows.net/<TenantID>/tokens

/OAuth/2

Als Header wird der Key “Content-Type” mit dem Value “application/x-www-form-urlencoded” eingetragen.

Der Body ist etwas komplizierter. Während einige Werte direkt übertragen werden können, setzen sich andere Werte aus den weiter oben gesammelten Informationen zusammen.

Im Body Tab unseres Requests in Postman wählen wir zuerst den Radio Button “x-www-form-urlencoded” aus.

Anschließend gibt es vier Einträge:

Key = “grant-type“.
Value = “client_credentials“.

Key = “client_id“.
Der Value dieses Eintrags setzt sich nach folgendem Schema zusammen:
Client Id@Tenant Id

In diesem Beispiel also:
Value = “e9d11d84-1290-xxxx-b278-xxxba720f049@b3d594a3-b9ce-xxxx-9ef9-xxxxxxxxxxxx

Key = “client_secret
Value = “598CQuPcKUNxxxxxxxxxxxxx8+JftSNlg/qAX6eV4gI=” (das Client Secret des registrierten Add-Ins)

Key = “resource
Der Value dieses Eintrags setzt sich nach folgendem Schema zusammen:
resource/SiteDomain@TenantId

In diesem Beispiel also:
Value = “00000003-0000-0ff1-ce00-000000000000/bsp.sharepoint.com@b3d594a3-b9ce-xxxx-9ef9-xxxxxxxxxxxx

Ist alles eingetragen, kann der Request abgeschickt werden und liefert folgendes Ergebnis zurück:

Abbildung 6: Beziehen des Access Tokens
Abbildung 6: Beziehen des Access Tokens

Beziehen des Access Tokens in Flow

Um einen Web Request in Flow zu versenden, sollte man die Aktion “HTTP” nutzen. Zwar gibt es auch eine SharePoint Aktion dafür, allerdings hatte diese bei allen Tests, die ich durchgeführt habe, falsch validiert, wodurch sich der Flow nicht mit den korrekten Werten im Body abspeichern lies.

Um den Access Token in Flow zu beziehen, muss der Request in der HTTP-Aktion gleich aufgebaut werden wie der Request in Postman.
Es ist jedoch notwendig, die Sonderzeichen “+”, “/” und “@” in den Body-Values zu encodieren.
Hier eine kurze Liste der Zeichen mit entsprechenden Codes:

+ = %2B
/ = %2F
@ = %40

Die HTTP-Aktion sieht dann wie folgt aus:

Abbildung 7: Beziehen des Access Tokens in Flow
Abbildung 7: Beziehen des Access Tokens in Flow

Um den Access Token aus der Request-Antwort nutzen zu können, muss die Antwort geparst werden. Hierzu wird die Aktion “Parse JSON” genutzt.
Das Schema zum Parsen lautet wie folgt:

{
    “type”: “object”,
    “properties”: {
        “token_type”: {
            “type”: “string”
        },
        “expires_in”: {
            “type”: “string”
        },
        “not_before”: {
            “type”: “string”
        },
        “expires_on”: {
            “type”: “string”
        },
        “resource”: {
            “type”: “string”
        },
        “access_token”: {
            “type”: “string”
        }
    }
}

Sollte es beim Speichern des Flows Probleme geben oder die Parse JSON Funktion melden, dass kein gültiges JSON eingetragen wurde, sollten die Anführungszeichen geprüft werden. Möglicherweise handelt es sich bei den Anführungszeichen im Blog um andere Zeichen als bei den Anführungszeichen in der Flow Aktion.

Wenn die Funktion ordnungsgemäß konfiguriert wurde, sieht sie wie folgt aus:

Abbildung 8: Parse JSON
Abbildung 8: Parse JSON

Da wir jetzt den Access Token haben, können wir ihn nutzen, um mit Flow die SharePoint API im berechtigten Bereich zu nutzen. In diesem Beispiel habe ich eine .xlsx-Datei in der Standardbibliothek Documents umbenannt. Welche Header und Body Werte eingetragen werden müssen, kann man in der Dokumentation der SharePoint API nachlesen.

Eine fertige REST-Anfrage sieht dann zum Beispiel so aus:

Abbildung 9: Beispiel REST-Call
Abbildung 9: Beispiel REST-Call

Die Nutzung der SharePoint API ermöglicht es, unabhängig von den vorhandenen Flow-Aktionen, SharePoint mit dem gesamten Funktionsumfang der API zu nutzen. Dieser Funktionsumfang ist eine hilfreiche Ergänzung gegenüber den vorhandenen Flow-Aktionen und ermöglicht es, komplexere Vorgänge mit Flow abzubilden ohne wegen Kleinigkeiten an die Grenzen zu stoßen.

Zwar gibt es kleinere Hindernisse, wie die nicht immer aktuelle Dokumentation der SharePoint REST API, allerdings lassen sich diese meist durch kurzes Herumprobieren überwinden.

Quellen:
Authentifizierung des Requests per Access Token
Umsetzen der Authentifizierung in Flow
Dokumentation der SharePoint REST API

Erfahren Sie mehr

Valo ist neuer Partner der novaCapta für Intranets
News
News

Valo ist neuer Partner der novaCapta für Intranets

Durch die Partnerschaft mit Valo, dem Ready-2-Go Intranet-Baukasten aus Finnland baut die novaCapta ihr Angebot bei der Umsetzung von schnellen und funktionalen...

novaCapta auf der Fachtagung für Interne Revision
Event
Event

novaCapta auf der Fachtagung für Interne Revision

Das Expertenteam der novaCapta präsentiert am 15. und 16. November ihre innovative Audit Management Lösung auf dem DIIR-Kongress in Dresden. Besuchen Sie unsere...

Jan
25
Webcast mit Microsoft: Fit für die digitale Arbeitswelt
Webinar
Webinar

Webcast mit Microsoft: Fit für die digitale Arbeitswelt

Die digitale Transformation und die Veränderung der Arbeitswelt ist längst in vielen Unternehmen und in den öffentlichen Einrichtungen angekommen. Dennoch stell...

Office 365 Groups als Evolution von SharePoint?
Blog
Blog

Office 365 Groups als Evolution von SharePoint?

Zusätzlich zu SharePoint erlauben die Office 365 Groups es mir als Anwender, schnell und einfach neue Gruppen anzulegen und selbständig Benutzer hinzuzufügen.

Strukturen lernen und leben – Praxis Informationsarchitektur
Blog
Blog

Strukturen lernen und leben – Praxis Informationsarchitektur

Teil 1 – Strukturen lernen – Informationsarchitektur erfolgreich vertreten

Farben zur Optimierung des SharePoint-Kalender
Blog
Blog

Farben zur Optimierung des SharePoint-Kalender

Auch in SharePoint kann man Kategorien für Teamkalender-Einträge farblich abheben und damit die Lesbarkeit erhöhen. Wir zeigen Ihnen, wie das geht.

Die Micro-Info-Architektur
Blog
Blog

Die Micro-Info-Architektur

Vertiefung zum Thema Informationsarchitektur moderner Intranets mit SharePoint: Das Micro-Management.

SharePoint Framework Client-Side Webparts mit React
Blog
Blog

SharePoint Framework Client-Side Webparts mit React

React ist ein Framework zur Erstellen von Benutzeroberflächen. In der SharePoint Online Entwicklung bietet es sich für die Entwicklung von Client-Side Webparts...

Referenz: Heidelberger Druckmaschinen AG

Referenz: Heidelberger Druckmaschinen AG

Ziel der Heidelberger Druckmaschinen AG war es eine neue innovative Arbeitsumgebung zu schaffen.

Das neuste Mitglied der Office 365 Familie: Delve
Blog
Blog

Das neuste Mitglied der Office 365 Familie: Delve

Microsoft legt nach: Mit Delve startet eine neue Form des Suchens und des Auffinden von Dokumenten und Informationen.

Corporate News – Das zentrale Medium interner Kommunikation
Blog
Blog

Corporate News – Das zentrale Medium interner Kommunikation

Um die Akzeptanz des unternehmenseigenen Intranets zu steigern, sind Corporate News ein erster Schritt, um Neuigkeiten, Strategie und Strukturen gleichmäßig zu ...

SharePoint-Migration unter Einhaltung der BITV 2
Blog
Blog

SharePoint-Migration unter Einhaltung der BITV 2

Einhaltung aller Vorgaben durch die BITV 2 bei einer Migration von SharePoint Server 2013 zu 2016.