SharePoint-Dateien mittels Fabric Notebook in ein Lakehouse laden

Dort klicken wir dann auf New registration und erstellen eine neue App Registration. 

Wir geben der App Registration einen Namen und wählen Single Tenant aus. 

Die Redirect URI kann leer bleiben. 

Im nächsten Screen klicken wir auf Manage und dann auf API Permissions. 

Wir sehen dass die App bisher die Delegated User.Read Permission hat, mit der sie das Profil des eingeloggten Users lesen darf. 

Wir klicken auf Add a permission und wählen die Microsoft Graph aus. Da die App selber handeln soll, und nicht ein eingeloggter User, wählen wir im nächsten Schritt Application Permissions (s. Permission Types für eine Erklärung was das genau bedeutet) und scrollen dann nach unter bis wir den Punkt Sites finden. 

Wir könnten jetzt der App die Sites.Read.All oder die Sites.ReadWrite.All Permission geben und wären fertig. Mit diesen Permissions können wir Daten aus SharePoint herunterladen. Aber Vorsicht! Mit den Permissions kann die App alle Dateien in SharePoint sehen, nicht nur die in bestimmten Sites. Für die meisten Fälle ist das zu viel, und wir möchten der App nur Zugriffsrechte die SharePoint Sites geben, die wirklich die Daten enthalten die wir laden möchten (Principle of least privilege).

Dazu wählen wir die Sites.Selected Permission. Damit kriegt die App nur Zugriff auf die Sites, auf die wir ihr explizit Zugriff gewährt haben.

Ist die App damit fertig eingerichtet, und wir können jetzt Code schreiben der die Dateien herunterlädt und ins Lakehouse lädt? Leider nicht!

Wie müssen nämlich jetzt noch der App Zugriff auf die Sites geben, die unsere Daten enthalten.

Und das geht leider nur über die Graph API, und nicht über SharePoint direkt.

Die Permissions geben wir über einen Call an diesen Endpoint. Damit wir den aber nutzen können brauchen wir die Sites.FullControl.All Permission! 

Wir gehen also zweistufig vor. Zunächst geben wir der App die Sites.FullControl.All und die Sites.Selected Permission, und richten dann den Zugriff auf alle benötigten SharePoint Sites ein. Danach entfernen wir die Sites.FullControl.All Permission wieder.

Wichtig ist dass diese Permissions erst gültig werden, wenn ein Admin den sog. Admin Consent gegeben hat.

Wir sehen im Screenshot in der Status Zeile, dass dieser noch aussteht, und die Permission daher noch nicht gültig ist. Um diesen Admin Consent zu geben, muss ein Admin den Grant admin consent Button oben im Screenshot drücken. Admin bezeichnet hier eine Person, die in Entra ID die Global Admin, Cloud Application Administrator oder Application Administrator Rolle inne hat.

Wenn wir die Permissions korrekt eingerichtet haben, können wir jetzt anfangen den ersten Code zu schreiben der mittels dieser App Registration auf die Graph API zugreift.

Wir wollen also jetzt auf ein HTTP POST auf den Permissions Endpoint machen um der App Zugriff auf unsere Site SampleSite zu geben. Im Example der Doku finden wir folgendes:

Wir müssen hier zwei Dinge anpassen: Die URL, wo der Request hingeht, und die die application im Body. Fangen wir dem Body an. Unter id und displayName müssen die Client ID und der Name der App Registration eingetragen werden, die auf sie SharePoint Site Zugriff kriegen sollen. Dazu gehen wir zurück ins Azure Portal zu unserer App Registration und klicken auf Overview.

Hier finden wir die Application (client) ID und natürlich auch den Namen der App.

Für die URL benötigen wir die Site ID. Die könnten wir jetzt über einen anderen Endpoint der Graph API abrufen, aber wir machen uns das Leben einfacher und fügen der Site URL einfach _api/site/id an und öffnen das im Browser. Dort wird uns nun die Site ID angezeigt. In unserem Beispiel müssten wir also https://drjve.sharepoint.com/sites/SampleSite/_api/site/id aufrufen, um die Site ID der SampleSite zu erhalten.

Damit sind die URL und der Body für den POST Request, der unserer App Zugriff auf SharePoint gewährt, bereit. Jetzt müssen wir uns noch ein Access Token für die App holen um auch als die App handeln zu können.

Zunächst könnte man meinen, dass wir dafür in Fabric Notebooks notebookutils.credentials.getToken nutzen können. Diese Funktion unterstützt aber leider (Stand heute) nur die vier in der Dokumentation genannten APIs. Die Graph API ist leider nicht dabei. Stattdessen nutzen wir (jetzt für die Permissions, aber auch später um die Dateien aus SharePoint abzurufen) dass azure-identity Paket. Eigentlich ist msal, die Microsoft Authentication Library die SDK, mit der Entra ID Authentifizierung gehandelt wird. msal ist allerdings sehr komplex, deswegen hat Microsoft mit azure-identity ein Paket geschaffen, dass msal wrapped und einige der Funktionen vereinfacht anbietet.

Das Anmelden als App Registration geht mit foldendem Code:

Die Tenant ID und die Client ID erhalten wir wieder von der Overview Seite unserer App. Das Client Secret, quasi das Passwort für die App Registration, müssen wir noch in der App Registration erstellen.

Der String, den wir als Argument der get_token Methode mitgeben, setzt sich aus zwei Teilen zusammen: 

• " https://graph.microsoft.com" ist allgemein nicht unbedingt eine URL im Sinne dass unter dem Namen ein Server zu finden ist. Das ist einfach der Name, unter dem die Graph API in Entra ID angesprochen wird. Im Fall der Microsoft 365 Graph API werden wir aber tatsächlich unsere HTTP Requests an diese URL schicken.
• Die Permission, die wir anfragen. Bei App Registrations kann man nur den sog. Default Scope anfordern, das bedeutet, dass im Token alle Permissions, die die App in Entra ID auf die API bekommen hat, im Token aufgelistet werden. Der Default Scope wird mit .default angefordert. Bei Delegated Permissions, also wenn sich ein User anmeldet, würde hier statt .default eine Permissions stehen, also z. B. https://graph.microsoft.com/Sites.FullControl.All. Wenn man mehrere Permissions benötigt müssen diese im Argument mit Freizeichen getrennt aufgelistet werden.

Dazu gehen wir in der App Registration zu Manage, dann Certificates & secrets, wählen Client Secrets aus, und klicken New client secret. Hier können wir dem Secret einen Namen und einen Gültigkeitszeitraum geben und uns dann den Wert des Secrets rauskopieren. Am besten tut man das Secret in einen Azure Key Vault und ruft es dann aus dem Notebook mit notebookutils.credentials.getSecret('https://<name>.vault.azure.net/', 'secret name') ab.

Damit haben wir nun ein Access Token, dass wir im Authorization Header mitgeben können, um die Permission auf die SharePoint Site zu erstellen. Mit requests würde das z. B. so aussehen:

Nun wo wir der App Zugriff auf die SharePoint Site SampleSite gegeben haben, können und sollten wir die Sites.FullControl.All Permission von der App entfernen.

Die Dateien aus SharePoint abrufen

Nun können wir endlich Dateien aus SharePoint abrufen. Dazu müssen wir zuerst die ID des SharePoint Drives herausfinden, in dem unsere Dateien liegen.

Eine SharePoint Site kann über mehrere Drives verfügen. Mit diesem Code listen wir alle Drives über den List Drives Endpoint der Graph API auf. Im nächsten Schritt muss auf der korrekte Drive ausgewählt werden (die Drives haben einen Namen über den man filtern kann).

Mit der Drive ID können wir nun eine Datei über ihren Dateipfad innerhalb des Drives ansprechen. Um sie herunterladen zu können benötigen wir die Download URL der Datei, die wir in den Metadaten finden.

Diese erhalten wir über den Get DriveItem Endpoint. In Python könnte das z. B. so aussehen:

Damit können wir jetzt endlich die Datei aus SharePoint abrufen. Die einfachste Art, sie auch direkt in ein Lakehouse zu schreiben, ist dieses Lakehouse an ein Fabric Notebook anzuschließen, und in diesem Notebook die Datei im /lakehouse/default/ Ordner zu speichern. An dieser Stelle wird das Default Lakehouse in der VM, auf der das Notebook ausgeführt wird, als Teil des lokalen Dateisystems gemountet. Wir können einfach eine Datei in dieses Verzeichnis schreiben, und der Mount Driver kümmert sich automatisch darum, dass diese Datei in den OneLake geschrieben wird.

Das würde in Python z. B. so aussehen: