Bewährte Methoden zum Ermitteln von Dateien und zum Erkennen von Änderungen im großen Maßstab

  • Artikel

In SharePoint und OneDrive werden Millionen von Dateien gespeichert. Es ist wichtig, die richtigen Aufrufmuster zu verwenden, wenn Sie versuchen, alle Dateien und Änderungen im großen Maßstab zu ermitteln. Historisch gesehen gibt es viele APIs für den Zugriff auf Dateien auf Detailebene. Viele dieser APIs sind bei großen Mengen nicht effizient, funktionieren aber gut im Hinblick auf eine einzelne Benutzerinteraktion. In diesem Leitfaden wird beschrieben, wie Sie einen Office 365-Mandanten oder OneDrive überwachen können, damit Ihre Anwendung mit Office 365 mit maximaler Leistung und Effizienz integriert wird. Anwendungen, bei denen in der Regel ein solcher Bedarf besteht, sind Synchronisierungsmodule, Sicherungstools Suchindexer, Klassifizierungsmodule und Tools für die Verhinderung von Datenverlust.

Die richtigen Berechtigungen erhalten

Zum Erstellen einer Vertrauensstellung gegenüber Benutzern ist es wichtig, den richtigen minimalen Satz von Berechtigungsbereichen zu verwenden, die für das Funktionieren einer App erforderlich sind. Die meisten Scananwendungen fordern Anwendungsberechtigungen zum Arbeiten an. Dies weist darauf hin, dass eine Anwendung unabhängig von einem bestimmten Benutzer ausgeführt wird. Für den Zugriff auf Dateien sollten Sie entweder den Bereich Files.Read.All oder Files.ReadWrite.All anfordern. Für den Zugriff auf SharePoint-Ressourcen, einschließlich der Liste aller Sitesammlungen, ist Sites.Read.All oder Sites.ReadWrite.All geeignet. Damit Berechtigungen korrekt verarbeitet werden, müssen Sie auch Sites.FullControl.All anfordern.

Autorisierungstypen, Berechtigungsbereiche und Benutzer

Beim Konfigurieren von Berechtigungen einer Anwendung in Microsoft Azure können Sie zwischen Anwendungsberechtigungen und delegierten Berechtigungen wählen. Wie oben erwähnt, benötigen die meisten Scananwendungen Anwendungsberechtigungen. Delegierte Berechtigungen erfordern, dass Ihre Anwendung im Kontext eines angemeldeten Benutzers und nicht global ausgeführt wird. Beim delegierten Modell sind Sie auf Inhalte beschränkt, auf die der aktuelle Benutzer Zugriff hat.

Ein wichtiger Aspekt von Berechtigungen ist, dass, wenn ein Administrator Berechtigungen für eine Anwendung erteilt, die Anwendungsberechtigungen anfordert (anstelle delegierter Berechtigungen), die Berechtigungsgewährung dem Mandanten und der Anwendung und nicht dem Administratorbenutzer zugeordnet wird. Obwohl ein Administrator den Zugriff gewähren muss, gewährt die Zugriffsgewährung der Anwendung keine speziellen Administratorberechtigungen, die über den Zugriff auf die von der Anwendung angeforderten Ressourcenbereiche hinausgehen.

Für Anwendungen, die große Datenmengen aus SharePoint und OneDrive verarbeiten, sollten Sie ein einheitliches Aufrufmuster wie das folgende verwenden.

  1. Ermitteln: Legen Sie fest, welche Speicherorte gescannt werden sollen.
  2. Durchforsten: Ermitteln und verarbeiten Sie den gesamten Satz von Dateien, an denen Sie interessiert sind.
  3. Benachrichtigen: Überwachen Sie Änderungen an diesen Dateien mittels Benachrichtigungen.
  4. Prozessänderungen: Verarbeiten Sie mithilfe der Deltaabfrage nur solche Dateien erneut, die geändert wurden.

Das Muster sieht wie in der folgenden Darstellung aus. In diesem Artikel werden die einzelnen Schritte für die Umsetzung ausführlich erläutert.

Ablauf der Scanaufrufe zwischen Microsoft Graph und Clientanwendung

Für jedes dieser Elemente kann es mehrere Mechanismen für ihre Erledigung in der Microsoft Graph-API und vorhandenen SharePoint-APIs geben. Ziel dieses Artikels ist es, Ihnen die beste derzeit verfügbare Methode zur Ausführung der einzelnen Aufgaben an die Hand zu geben.

Ermitteln der Speicherorte, die überprüft werden sollen

Das Festlegen der Speicherorte, die Ihre Anwendung überprüfen soll, erfolgt derzeit manuell. In vielen Fällen sollten Sie für diesen Schritt eine für den Benutzer sichtbare Anwendungsumgebung bereitstellen. Wie Sie diese Funktion verfügbar machen und ob sie für alle Benutzer oder nur Administratoren verfügbar gemacht wird, liegt bei Ihnen. Sie sollten ermitteln, welche OneDrives der Benutzer und welche SharePoint-Sitesammlungen und -Untersites zu überprüfen sind.

Das OneDrive jedes Benutzers umfasst ein einzelnes Laufwerk, das Sie überwachen können. SharePoint-Sitesammlungen und -Untersites umfassen möglicherweise mehrere Laufwerke, eines für jede Dokumentbibliothek auf der Site. Sie können jedes Laufwerk auf einer Site mithilfe des /drives-Endpunkts ermitteln. Um beispielsweise alle Laufwerke der Stammwebsite des Mandanten zu ermitteln, können Sie Folgendes verwenden:

https://graph.microsoft.com/v1.0/sites/root/drives

Das Laufwerk ist der Ausgangspunkt für umfangreiche Dateiaktivitäten. Sie werden diese Laufwerke verwenden, um vollständige Dateilisten abzurufen und Webhooks für Benachrichtigungen zu verbinden, und Sie werden mithilfe von Delta-Abfragen Änderungen an Elementen auf den Laufwerken abrufen.

Suchen nach SharePoint-Sitesammlungen und OneDrive for Business-Laufwerken

Wenn Sie Microsoft Graph mit Anwendungsberechtigungen verwenden, können Sie die vollständige Liste der Sitesammlungen abrufen, einschließlich Sites, die OneDrive for Business Laufwerke umfassen. Verwenden Sie zum Abrufen dieser Liste den folgenden API-Aufruf:

GET /sites

Die Siteenumerations-API unterstützt auch Delta-Abfragen, um Informationen zu neu erstellten Sites oder zu Änderungen an der Sitestruktur zu erhalten. Das Rollout der Unterstützung von Delta-Abfragen für die Siteenumeration erfolgt derzeit für die Microsoft Graph-Betaversion. Lesen Sie weiter, um weitere Informationen zur Delta-Abfrage zu erhalten.

Um Benachrichtigungen zu neuen Sitesammlungen zu erhalten, können Sie mithilfe des Microsoft Graph-Abonnementendpunkts Webhooks abonnieren. Die Zielressource für diese Benachrichtigungen ist /sites. Sie erhalten Benachrichtigungen, wenn neue Sitesammlungen erstellt oder gelöscht bzw. wenn Untersites oder Listen erstellt werden.

Durchforsten und Verarbeiten mithilfe von Delta-Abfragen

Um die anfängliche Liste der Dateien auf einem Laufwerk abzurufen, führen Sie einen einzelnen Delta-Abfrageaufruf ohne Parameter aus. Die Delta-Abfrage führt eine anfängliche Durchforstung aller Inhalte einer App durch und sucht anschließend nach ab einem bestimmten Zeitpunkt erfolgten Änderungen. Die Delta-Abfrage gibt den Link zurück, der erforderlich ist, um bei jedem Aufruf spätere Änderungen abzurufen.

Wenn Sie beispielsweise alle Dateien in der Standarddokumentbibliothek einer SharePoint-Site abrufen möchten, können Sie diese Abfrage verwenden:

/sites/{siteId}/drive/root/delta

Diese API gibt Seiten mit Ergebnissen zurück, die alle Dateien auf dem Laufwerk darstellen. Nachdem Sie alle Seiten von Dateien mithilfe des zurückgegebenen @odata.nextLinkabgerufen haben, können Sie die Deltaabfrage mit dem zurückgegebenen @odata.deltaLink erneut ausführen, um Änderungen seit dem letzten Aufruf der Delta-Abfrage abzurufen. Denken Sie immer daran, die von @odata.deltaLink zurückgegebene URL beizubehalten, damit Sie später effizient nach den Änderungen suchen können.

Die von der Delta-Abfrage zurückgegebenen Links sehen wie folgt aus:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(driveItem)",
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?$select=*%2csharepointIds&token=MzslMjM0OyUyMzE7MzsyM2YwNDVhMS1lNmRmLTQ1N2MtOGQ5NS1hNmViZDVmZWRhNWQ7NjM2NzExNzY2MzIxMDcwMDAwOzE5ODAzMzU5ODslMjM7JTIzOyUyMzQ",
    "value": [
        {
            "@odata.type": "#microsoft.graph.driveItem",
            "createdDateTime": "2017-07-27T02:41:36Z",
…
}

Ein ausführlicheres Beispiel finden Sie in der Dokumentation zu Delta-Abfragen.

Eine Delta-Abfrage gibt ein Array von driveItemszurück. Wenn Sie im Voraus wissen, dass Sie bestimmte Informationen benötigen, können Sie sie in einer Select-Anweisung in die Delta-Abfrage einschließen. Bei Bedarf können Sie den Delta-Aufruf zusätzlich mit einer Anforderung für ein bestimmtes driveItem nachverfolgen. Die Delta-Abfrage hilft außerdem dabei, die Anzahl der Elemente einzugrenzen, die auf Änderungen überprüft werden sollen, wodurch Ihre Anwendung effizienter wird.

Benachrichtigung zu Änderungen mithilfe von Webhooks

Um die Delta-Abfrage für die Suche nach Änderungen auf einem Laufwerk optimal zu nutzen, benötigen Sie eine effektive Strategie, um zu wissen, wann nach den Änderungen gesucht werden soll. In der Vergangenheit haben Sie Ihre App möglicherweise so programmiert, dass OneDrive und SharePoint in einem bestimmten festen Intervall überprüft wurden und haben die Änderungen selbst aufgezählt. Mit der Delta-Abfrage wird Ihnen das Aufzählen abgenommen, sodass Sie nur wissen müssen, wann nach den Änderungen gesucht werden soll. Webhooks ermöglichen es Ihnen, das Abfragen des Diensts zu vermeiden und stattdessen eine Benachrichtigung zu erhalten, wenn sich etwas von Interesse geändert hat. Wenn Sie den Dienst wiederholt oder häufig abfragen, wird Ihre App aufgrund übermäßiger Abrufmuster eingeschränkt.

Webhooks werden mithilfe der Abonnement-API für Microsoft Graph angefügt. Die vollständige Dokumentation zu Microsoft Graph-Webhooks und die Subscriptions-API finden Sie auf der Microsoft Graph-Website.

Sie müssen ein Abonnement erstellen, das einer bestimmten Ressource (in diesem Fall einem Laufwerk) zugeordnet ist. Laufwerke unterstützen den Änderungstyp "update" für Webhooks. Ein "Update" gibt an, dass Inhalte auf dem Laufwerk geändert wurden oder dass neue Inhalte hinzugefügt oder gelöscht wurden. Webhook-Abonnements weisen ein zugeordnetes Timeout auf, das regelmäßig aktualisiert werden muss. Informationen zum Aktualisieren Ihrer Abonnements finden Sie in der zuvor erwähnten Dokumentation. Wir empfehlen die Verwendung der Delta-Abfrage mit Ihrem letzten Änderungstoken unmittelbar nach dem Abonnieren von Webhooks, um sicherzustellen, dass Sie keine Änderungen verpassen, die zwischen der anfänglichen Durchforstung und dem Einrichten Ihrer Webhooks erfolgt sind.

Selbst wenn Webhooks eingerichtet sind, die Ihnen Anwendungsbenachrichtigungen senden, sollten Sie regelmäßige Delta-Abfrage durchführen, um sicherzustellen, dass keine Änderungen verpasst werden, wenn Sie länger keine Benachrichtigung erhalten haben. Wir empfehlen, diese regelmäßige Überprüfung nicht öfter als einmal pro Tag durchzuführen. Mit Delta-Abfragen können Sie trotzdem problemlos auf dem Laufenden bleiben und vermeiden, dass Sie Änderungen im System verpassen.

Erhalt von Webhook-Benachrichtigungen zu Sicherheitsereignissen

OneDrive und SharePoint unterstützen das Senden von Anwendungsbenachrichtigungen zu Sicherheitsereignissen, die auf einem DriveItem-Konto auftreten. Um diese Ereignisse zu abonnieren, müssen Sie der Anforderung zum Registrieren eines Webhooks den Header "prefer:includesecuritywebhooks" hinzufügen. Nach der Registrierung des Webhooks erhalten Sie Benachrichtigungen, wenn sich die Berechtigungen für ein Element ändern. Dieser Header gilt für SharePoint und OneDrive for Business, jedoch nicht für OneDrive-Verbraucherkonten.

Verarbeitung von Änderungen

Nachdem Ihre Anwendung eine Benachrichtigung über einen Webhook erhalten hat, muss die Benachrichtigung durch das sofortige Zurücksenden eines 202 – Accepted-Codes an Microsoft Graph bestätigt werden. Dieser Code sollte gesendet werden, bevor mit einer zeitaufwändigen Verarbeitung begonnen wird. Andernfalls werden weitere Versuche gesendet, die von Ihrer App möglicherweise als falsche Benachrichtigungen betrachtet werden.

Führen Sie anschließend an die Bestätigung eine Delta-Abfrage zu den neuesten Änderungen durch. Ihre App sollte dann auf dem neuesten Stand sein. Wenn Sie auf einem bestimmten Laufwerk hohe Datenverkehrsmuster erwarten, sollten Sie erwägen, die Delta-Abfrage in reduzierten Intervallen anstatt nach jeder Änderungsbenachrichtigung aufzurufen. Speichern Sie außerdem unbedingt den im deltaLink-Parameter zurückgegebenen neuen Wert, um ein neues Token zum erneuten Aufrufen der API zu erhalten.

Wenn für die Verarbeitung das Herunterladen des Inhalts einer einzelnen Datei erforderlich ist, können Sie mithilfe der cTag-Eigenschaft ermitteln, ob sich der Inhalt der Datei seit dem letzten Herunterladen geändert hat. Sobald feststeht, dass die Datei heruntergeladen werden soll, können Sie auf die /content-Eigenschaft des DriveItem zugreifen, das in einer Delta-Abfrageantwort zurückgegeben wird.

Überprüfen von Berechtigungshierarchien

Standardmäßig enthält die Delta-Abfrageantwort Freigabeinformationen zu Elementen, auch wenn sie ihre Berechtigungen vom übergeordneten Element erben und selbst keine direkten Freigabeänderungen aufweisen. Beachten Sie, dass die Delta-Abfrageantwort nur Elemente mit direkten Änderungen an ihren Inhalten oder Metadaten und die übergeordnete Hierarchie der geänderten Elemente enthält. Dies führt in der Regel zu einem Folgeaufruf, um die Berechtigungsdetails für jedes Element und nicht nur für diejenigen abzurufen, deren Freigabeinformationen sich geändert haben. Sie können Berechtigungsänderungen besser nachvollziehen, indem Sie den "Prefer: hierarchicalsharing"-Header zu Ihrer Delta Abfrageanforderung hinzufügen.

Wenn der "Prefer: hierarchicalsharing"-Header bereitgestellt wird, werden Freigabeinformationen zum Stamm der Berechtigungshierarchie sowie Elemente zurückgegeben, an denen explizit Freigabeänderungen vorgenommen wurden. In Fällen, in denen die Freigabeänderung darin besteht, dass die Freigabe für ein Element entfernt wird, finden Sie ein leeres Freigabefacet, um zwischen Elementen zu unterscheiden, die von ihren übergeordneten Elementen erben, und denen, die einmalig sind, aber keine Freigabelinks aufweisen. Außerdem wird dieses leere Freigabeelement im Stamm einer Berechtigungshierarchie angezeigt, die nicht freigegeben ist, um den anfänglichen Bereich festzulegen.

In vielen Überprüfungsszenarien möchten Sie wahrscheinlich insbesondere Änderungen an Berechtigungen überprüfen. Wenn aus der Delta-Abfrageantwort deutlich hervorgehen soll, welche Änderungen das Ergebnis von Berechtigungsänderungen sind, können Sie den "Prefer: deltashowsharingchanges"-Header angeben. Wenn dieser Header angegeben wird, weisen alle Elemente, die in der Delta-Abfrageantwort aufgrund von Berechtigungsänderungen aufgeführt sind, beim Aufrufen von Microsoft Graph die OData-Anmerkung microsoft.graph.sharedChanged":"True" auf. Bei direkter Verwendung der SharePoint- oder OneDrive-API lautet die Anmerkung "@oneDrive.sharedChanged":"True". Wie bei Sicherheitswebhooks ist dieses Feature für SharePoint und OneDrive for Business geeignet, jedoch nicht für OneDrive-Verbraucherkonten.

Was geschieht bei einer Drosselung?

In einigen Szenarien gibt Microsoft Graph möglicherweise eine 429- oder 503-Antwort an Ihre Anwendung zurück. Dies weist darauf hin, dass Ihre Anforderung momentan gedrosselt wird. Bedenken Sie immer, dass SharePoint Anwendungen basierend auf der Verwendung einer Anwendung mit jedem Kundenmandanten drosselt. Wenn eine Anforderung für eine Ressource in einem Mandanten ausgeführt wird, bewirkt dies entsprechend weniger Ressourcen, um einen Aufruf an eine andere Ressource für denselben Mandanten auszuführen. Letztendlich kann es mehrere Gründe geben, warum Ihre App eine Drosselungsantwort erhält, und es ist wichtig, dass die App in diesen Situationen richtig reagiert.

Bei 429- und 503-Antwortcodes kann es helfen, einen erneuten Versuch nach dem im Retry-After-Feld im Antwortheader angegebenen Zeitintervall zu machen. Wenn die Drosselung weiterhin besteht, kann der Retry-After-Wert im Laufe der Zeit länger werden, sodass das System sich erholen kann. Apps, welche den angegebenen Intervall vor einem erneuten Aufruf nicht berücksichtigen, werden wegen missbräuchlicher Aufrufmuster blockiert.

Während Sie darauf warten, dass eine 429- oder 503-Situation aufgehoben wird, sollten Sie alle weiteren Anforderungen an den Dienst anhalten. Dies ist insbesondere in Multithreadszenarien wichtig. Das Ausführen zusätzlicher Aufrufe beim Erhalt von Drosselungsantworten führt dazu, dass es noch länger dauert, bis die Drosselung der Anwendung aufgehoben wird.

Ausführlichere Informationen zur Funktionsweise von Microsoft Graph-Ressourcen bei einer Drosselung finden Sie im Leitfaden zu Einschränkungen in Microsoft Graph.