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

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.

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

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.

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:

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:

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:

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:

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:

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