SharePoint.Files vs. SharePoint.Contents in Power Query: Welches sollten Sie verwenden?
- Admin
- 9. Nov.
- 7 Min. Lesezeit
Überblick
Wenn Sie Power Query / Power BI mit einer SharePoint-Website (oder Dokumentbibliothek) verbinden, gibt es (mindestens) zwei gängige M-Funktionen, die Sie möglicherweise sehen oder verwenden:
SharePoint.Files(siteUrl as text, optional options as record) as tableSharePoint.Contents(siteUrl as text, optional options as record) as tableObwohl sie ähnlich klingen, unterscheiden sie sich in ihrem Verhalten, ihrer Leistung, den zurückgegebenen Metadaten und der Navigation. Das Verständnis dieser Unterschiede hilft dabei, robustere und leistungsfähigere Abfragen zu erstellen.
Im Folgenden erkläre ich die Funktionsweise der einzelnen Komponenten, vergleiche sie und zeige beispielhafte Anwendungsmuster sowie Einschränkungen auf.
1. Funktionsweise von SharePoint.Files
1.1 Verhalten
SharePoint.Files ist so konzipiert, dass es alle Dateien (und typischerweise auch einige Metadaten) unter einer bestimmten SharePoint-Website oder -Bibliothek (und deren Unterordnern) auflistet.
Es ruft Metadaten für jedes Dokument auf der gesamten Website (oder Bibliothek) ab – was sehr aufwendig sein kann.
Der UI-Connector „SharePoint-Ordner“ in Power BI / Excel generiert häufig im Hintergrund eine Abfrage mit SharePoint.Files(...).
Es wird eine Tabelle mit Spalten wie Inhalt (binär), Name, Erweiterung, Änderungsdatum, Erstellungsdatum, Attribute, Ordnerpfad usw. zurückgegeben.
1.2 Vorteile
Unkompliziert, wenn Ihre Website oder Dokumentenbibliothek klein oder nur über eine geringe Anzahl von Dateien verfügt.
Gut geeignet, wenn Sie Dateien „kombinieren“ möchten (z. B. viele Excel-/CSV-Dateien in einer Ordnerstruktur), da Sie bereits die Spalte mit dem Binärinhalt haben.
Sie erhalten alle Metadaten auf Dateiebene (z. B. Dateigröße, Ordnerpfad, Dateierweiterung) auf einmal.
1.3 Nachteile / Einschränkungen
Leistungsprobleme bei großem Umfang : Da Metadaten für jede Datei auf der Website geladen werden, kann es bei großen Websites oder Bibliotheken (Hunderte oder Tausende von Dateien) sehr langsam werden oder sogar zu einem Timeout kommen.
Es werden möglicherweise mehr Daten abgerufen, als Sie benötigen, wodurch das Filtern weniger effizient wird, wenn es nicht frühzeitig erfolgt.
Es enthält möglicherweise nicht bestimmte SharePoint-spezifische Metadaten (benutzerdefinierte Bibliotheksspalten), die im Dokumentbibliotheksschema der Website definiert wurden.
2. Funktionsweise von SharePoint.Contents
2.1 Verhalten
SharePoint.Contents(siteUrl, optionale Optionen) gibt eine Tabelle zurück, die Ordner und Dateien als strukturierten Inhalt unter der Website auflistet.
Es verhält sich eher wie ein Ordnernavigationsmodell: Man kann über die Spalte „Inhalt“ (die eine Tabelle enthält) in Unterordner erweitern und nach unten navigieren.
Da nicht sofort alles vereinfacht wird, werden möglicherweise weniger Metadaten im Voraus aufgelistet (und die Datei ist somit leichter).
2.2 Vorteile
Bessere Leistung bei großen SharePoint-Websites : Da Metadaten nicht überall gleichzeitig abgerufen werden, kann es in größeren Szenarien schneller sein.
Mehr „explorative“ / hierarchische Navigation: Sie sehen die Ordnerstruktur und können gezielt nach Ihren Dateien suchen, anstatt von einer riesigen, flachen Liste überwältigt zu werden.
Hilft dabei, den anfänglichen Ladeaufwand zu reduzieren; Sie können früher filtern (z. B. nur in einen relevanten Ordner navigieren).
Da standardmäßig weniger Spalten zurückgegeben werden, kann vermieden werden, dass irrelevante Metadaten überabgerufen werden.
2.3 Nachteile / Vorbehalte
Authentifizierungs-/Berechtigungsprobleme : Einige Benutzer berichten, dass SharePoint.Contents in Szenarien, in denen SharePoint.Files einwandfrei funktioniert, nicht authentifiziert werden kann – insbesondere dann, wenn die Benutzer keinen Zugriff auf die gesamte Website haben (sondern nur auf einen Unterordner).
Fehlende bibliotheksspezifische Metadaten: Standardmäßig ruft SharePoint.Contents keine zusätzlichen Spalten (z. B. benutzerdefinierte Metadatenfelder, die Sie in der Bibliothek festgelegt haben) ab, es sei denn, Sie ergänzen diese über andere Abfragen (wie OData) und verknüpfen sie.
Bei einigen Kombinationsschritten bzw. Schritten zum Zusammenführen von Dateien kann es zu Fehlern kommen, da Binärinhalte auf eine bestimmte Weise dargestellt werden, insbesondere bei Verwendung neuerer API-Versionen.
Im Vergleich zum alles umfassenden Ansatz von SharePoint.Files ist etwas mehr manuelle Navigation erforderlich (Sie navigieren in Unterordner, erweitern Inhaltstabellen).
3. Direkter Vergleich
Merkmal / Dimension | SharePoint.Dateien | SharePoint.Contents |
anfängliche Abflachung | Gibt eine flache Liste aller Dateien unter dem Verzeichnis „site/library“ (mit Binärinhalt) zurück. | Gibt eine hierarchische Ordner- und Dateistruktur zurück; die Navigation erfolgt über die Spalte „Inhalt“. |
Metadatenreichtum | Umfangreiche Dateimetadaten (Größe, Attribute) | Grundlegende Datei-/Ordnermetadaten; benutzerdefinierte Bibliotheksspalten werden nicht automatisch einbezogen |
Leistung | Kann bei großen Websites (viele Dateien) stark beeinträchtigt werden. | Oft schneller, da weniger Vorab-Aufzählung erforderlich ist. |
Filterstrategie | Es ist wichtig, frühzeitig zu filtern (z. B. nach Ordnerpfad oder Dateiendung), um eine hohe Datenlast zu vermeiden. | Besser geeignet zum Filtern auf Ordnerebene |
Navigationserfahrung | Direkte Dateilistenliste; weniger intuitiv für die Struktur | Natürliche Bohrstruktur |
Authentifizierung / Berechtigungen | Funktioniert tendenziell, wenn der Zugriff auf einen Unterordner beschränkt ist. | Kann fehlschlagen, wenn Sie keinen Zugriff auf die vollständige Website oder die übergeordneten Ebenen haben. |
Unterstützung für das Kombinieren von Dateien | Funktioniert gut mit „Dateien kombinieren“ (z. B. Excel-Dateien). | Je nach API-Version bzw. Inhaltsformat können gelegentlich Fehler beim Zusammenführen von Dateien auftreten. |
Benutzerdefinierte Metadaten-/Bibliotheksspalten | Benutzerdefinierte Spalten werden ebenfalls nicht angezeigt (gleiche Einschränkung). | Noch eingeschränkter bei den Standardmetadaten; es müssen ergänzende Abfragen (OData) verwendet werden. |
4. Wann welches Produkt verwenden (Empfehlungen)
Hier finden Sie Richtlinien und Szenarien, die Ihnen bei der Entscheidung für das eine oder das andere helfen:
Kleine Websites oder eine begrenzte Anzahl von Dateien : Verwenden Sie SharePoint.Files für Einfachheit und Benutzerfreundlichkeit, da die Leistung akzeptabel ist und Sie problemlos auf Dateiebene Inhalte und Metadaten erhalten.
Große Bibliotheken / viele Dateien / Leistungsprobleme : Beginnen Sie mit SharePoint.Contents, navigieren Sie zum gewünschten Ordner (z. B. mit Source{[Name="Documents"]}[Content] oder ähnlich) und filtern und erweitern Sie ihn anschließend. Dadurch wird vermieden, alle Dateimetadaten gleichzeitig zu laden.
Wenn Sie auf den Binärinhalt einer Datei zugreifen müssen (z. B. zum Zusammenführen von CSV- und Excel-Dateien) , funktionieren beide Ansätze. Die Verwendung von „Contents“ mit Navigation zum entsprechenden Ordner kann jedoch den Aufwand reduzieren. Testen Sie den Schritt „Dateien zusammenführen“ sorgfältig (einige Benutzer berichteten von Problemen mit SharePoint.Contents in Verbindung mit API-Version 15).
Wenn Sie benutzerdefinierte Metadatenspalten (aus einer Bibliothek) benötigen : Keine der beiden Funktionen liefert direkt benutzerdefinierte Bibliotheksspalten. Verwenden Sie in diesen Fällen einen Hybridansatz: Nutzen Sie SharePoint.Contents (oder Files), um die Dateistruktur und den Inhalt abzurufen, und verwenden Sie anschließend OData.Feed oder die SharePoint-Listen-/Bibliotheks-API, um die Bibliotheksmetadaten abzurufen und zusammenzuführen.
Bei eingeschränktem Zugriff : Wenn Ihr Benutzerkonto nur Zugriff auf einen Unterordner hat, funktioniert SharePoint.Files möglicherweise noch, während SharePoint.Contents aufgrund der erforderlichen Zugriffsrechte auf übergeordneter Ebene fehlschlagen könnte.
In vielen realen Anwendungsfällen verwenden Entwickler einen kombinierten Ansatz: Sie nutzen Contents für Struktur, Navigation und Filterung und wechseln dann gegebenenfalls zu Files oder verwenden eine Hilfsabfrage (OData), um zusätzliche Metadaten abzurufen und diese zusammenzuführen.
5. Beispielcode / Muster
Hier sind vereinfachte M-Code-Ausschnitte zur Veranschaulichung der Verwendung.
5.1 Verwendung von SharePoint.Dateien
let
siteUrl = "https://yourtenant.sharepoint.com/sites/YourSite",
allFiles = SharePoint.Files(siteUrl, [ApiVersion=15]),
filtered = Table.SelectRows(allFiles, each Text.EndsWith([Extension], ".xlsx") and Text.Contains([Folder Path], "Reports")),
// Expand or combine as needed
// e.g. filter out nested folders, combine binaries etc.
result = filtered
in
result
5.2 SharePoint.Contents mit Navigation verwenden
let
siteUrl = "https://yourtenant.sharepoint.com/sites/YourSite",
root = SharePoint.Contents(siteUrl, [ApiVersion=15]),
// Navigate into the library or folder (e.g. “Documents”)
docLib = root{[Name = "Shared Documents"]}[Content],
// Now filter to subfolders or files
sub = docLib{[Name = "Reports"]}[Content],
files = Table.SelectRows(sub, each [Extension] = ".xlsx"),
// Add full URL or binary content, etc.
result = files
in
result
Diese Logik lässt sich in eine parametrisierte Hilfsfunktion kapseln, sodass man den Ordnerpfad übergibt und die Funktion die gewünschten Dateien durchsucht und zurückgibt. Viele Anwender nutzen diese Methode, um die Komplexität zu verbergen und den Code wiederzuverwenden.
5.3 Hybridmuster zum Abrufen benutzerdefinierter Metadaten
Ein weiterentwickeltes Muster (basierend auf öffentlichen Gemeinschaftslösungen) ist:
Verwenden Sie SharePoint.Contents (oder SharePoint.Files), um bei Bedarf die Dateiliste und die Binärdateien zu erhalten.
Verwenden Sie OData.Feed oder die SharePoint REST API (_api), um Bibliotheksmetadaten (benutzerdefinierte Spalten) abzurufen.
Diese Tabellen werden anhand der Datei-URL oder des Dateipfads zusammengeführt.
Beispielskelett (vereinfacht):
let
siteUrl = "https://yourtenant.sharepoint.com/sites/YourSite",
// part A: file list
fileList = let
root = SharePoint.Contents(siteUrl, [ApiVersion=15]),
lib = root{[Name="Shared Documents"]}[Content],
// flatten to files
filesTable = Table.SelectRows(lib, each [Attributes][Kind] <> "Folder")
in
filesTable,
// part B: metadata via REST / OData
meta = OData.Feed(siteUrl & "/_api/web/lists/getbytitle('Shared Documents')/items", null, [Implementation="2.0"]),
cleanMeta = Table.SelectColumns(meta, {"FileLeafRef", "CustomColumn1", "CustomColumn2"}),
// join
merged = Table.NestedJoin(fileList, {"Name"}, cleanMeta, {"FileLeafRef"}, "Meta", JoinKind.LeftOuter),
expanded = Table.ExpandTableColumn(merged, "Meta", {"CustomColumn1", "CustomColumn2"}, {"Custom1", "Custom2"})
in
expanded
Dadurch erhalten Sie Dateiinhalte und Ihre benutzerdefinierten Metadaten in einer Ergebnistabelle. Beachten Sie jedoch die Aktualisierungsleistung und das Paging.
6. Häufige Fehler und Tipps
Um die Ladezeit zu verkürzen und die Geschwindigkeit zu erhöhen, sollten Filter- und Navigationsvorgänge immer so früh wie möglich durchgeführt werden (d. h. bevor viele Zeilen erweitert werden).
Achten Sie auf die API-Versionseinstellungen (14 vs. 15). Einige Benutzer berichteten von Fehlern mit kombinierten SharePoint.Contents-Dateien nur bei Verwendung von Version 15.
Vermeiden Sie es, zu viele irrelevante Dateien (z. B. Nicht-Excel- oder Nicht-CSV-Dateien) einzuschließen – filtern Sie frühzeitig nach Dateierweiterung.
Wenn bei der Verwendung von SharePoint.Contents Authentifizierungsfehler auftreten, Files jedoch funktioniert, überprüfen Sie Ihre Berechtigungen (möglicherweise fehlen Ihnen die Berechtigungen der übergeordneten Website).
Seien Sie vorsichtig mit Dateinamen, die Sonderzeichen (#, %, $, etc.) enthalten – diese können Pfade oder URIs beschädigen.
Bei sehr großen Bibliotheken empfiehlt es sich, diese nach Möglichkeit in kleinere Bereiche (eigene Ordner/Websites) aufzuteilen.
Seien Sie darauf vorbereitet, Hybridabfragen (Zusammenführung von Daten aus zwei Quellen) zu verwenden, wenn keine der Funktionen allein alle benötigten Ergebnisse liefert.
7. Zusammenfassung und Empfehlung
SharePoint.Files ist einfacher und unkomplizierter, wenn Ihre Dateimenge klein bis mittelgroß ist; Sie erhalten alle Dateimetadaten und den Binärinhalt auf einmal.
SharePoint.Contents bietet in der Regel eine höhere Leistung in größeren Umgebungen und ein übersichtlicheres Ordnernavigationsmodell, verfügt jedoch nicht über automatisch generierte umfangreiche Metadaten und hat gelegentlich Probleme mit den Authentifizierungsberechtigungen.
In der Praxis verwenden viele robuste Lösungen einen Hybridansatz : Sie nutzen Inhalte für Strukturierung und Filterung und rufen optional Metadaten über REST oder OData ab und führen diese zusammen.
Testen Sie immer in Ihrer spezifischen SharePoint-Umgebung (Dateianzahl, Berechtigungen, Aktualisierungsverhalten), da die theoretischen Leistungssteigerungen in realen Fällen abweichen können.
👉 Der Schlüssel liegt darin , frühzeitig zu filtern, das Laden unnötiger Dateien zu vermeiden und die Leistung in Ihrer Umgebung zu testen .
Benötigen Sie in jedem Power BI- oder Excel-Projekt ein Power Query-Starterpaket? Mit nur wenigen Anpassungen für schnelle und effiziente Berechnungen? Entdecken Sie diese unverzichtbaren benutzerdefinierten Funktionen.
Kommentare