Laufwerksänderungen nachverfolgen

Artikel
04/08/2023

Mit dieser Methode kann Ihre App Änderungen nachverfolgen, die im Laufe der Zeit an Laufwerken sowie deren untergeordneten Elementen vorgenommen werden.

Die App ruft zunächst delta ohne Parameter auf. Der Dienst startet dann eine Enumeration der Laufwerkshierarchie und gibt Seiten mit Elementen sowie entweder einen @odata.nextLink oder einen @odata.deltaLink zurück, wie unten beschrieben. Die App sollte die Aufrufe solange mit dem @odata.nextLink fortführen, bis kein @odata.nextLink mehr zurückgegeben wird oder bis eine Antwort mit einem leeren Satz an Änderungen zurückgegeben wird.

Sobald alle Änderungen empfangen wurden, können Sie sie auf den lokalen Zustand anwenden. Wenn Sie zu einem späteren Zeitpunkt nochmals auf Änderungen prüfen möchten, rufen Sie erneut delta auf, mit dem @odata.deltaLink aus der vorherigen Antwort.

Gelöschte Elemente werden mit dem deletedFacet zurückgegeben. Elemente, für die diese Eigenschaft gesetzt ist, sollten Sie aus Ihrem lokalen Zustand entfernen.

Hinweis: Löschen Sie Ordner nur lokal, wenn sie nach der Synchronisierung aller Änderungen leer sind.

Berechtigungen

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie unter Berechtigungen.

Berechtigungstyp	Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)
Delegiert (Geschäfts-, Schul- oder Unikonto)	Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegiert (persönliches Microsoft-Konto)	Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All
Anwendung	Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

HTTP-Anforderung

GET /drives/{drive-id}/root/delta
GET /groups/{groupId}/drive/root/delta
GET /me/drive/root/delta
GET /sites/{siteId}/drive/root/delta
GET /users/{userId}/drive/root/delta

Optionale Abfrageparameter

Diese Methode unterstützt die OData-Abfrageparameter von $select, $expand und $top zur Anpassung der Antwort.

Parameter

Name	Wert	Beschreibung
token	string	Optional. Falls nicht angegeben, wird der aktuelle Status der Hierarchie aufgelistet. Für `latest` wird eine leere Antwort mit dem neuesten Delta-Token zurückgegeben. Im Fall eines vorherigen Delta-Token wird der neue Status seit diesem Token zurückgegeben.

Antwort

Bei Erfolg gibt diese Methode den Antwortcode 200 OK und eine Sammlung von Ressourcen des Typs DriveItem im Antworttext zurück.

Zusätzlich zu der Sammlung von DriveItems enthält die Antwort außerdem eine der folgenden Eigenschaften:

Name	Wert	Beschreibung
@odata.nextLink	url	Eine URL zum Abrufen der nächsten verfügbaren Seite von Änderungen, sofern weitere Änderungen im aktuellen Satz vorhanden sind
@odata.deltaLink	url	Eine URL, die anstelle eines @odata.nextLink zurückgegeben wird, sobald alle aktuellen Änderungen zurückgegeben wurden. Sie wird verwendet, um zu einem späteren Zeitpunkt den nächsten Satz von Änderungen zu lesen.

Beispiel (ursprüngliche Anforderung)

Hier sehen Sie ein Beispiel für einen Aufruf dieser API zur Ermittlung Ihres lokalen Zustands.

Anforderung

Unten ein Beispiel für eine ursprüngliche Anforderung:

GET https://graph.microsoft.com/v1.0/me/drive/root/delta

Antwort

Nachfolgend sehen Sie ein Beispiel der Antwort.

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
        {
            "id": "0123456789abc",
            "name": "folder2",
            "folder": { }
        },
        {
            "id": "123010204abac",
            "name": "file.txt",
            "file": { }
        },
        {
            "id": "2353010204ddgg",
            "name": "file5.txt",
            "deleted": { }
        }
    ],
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/drive/delta(token=1230919asd190410jlka)"
}

Diese Antwort enthält die erste Seite von Änderungen. Die Eigenschaft @odata.nextLink gibt an, dass im aktuellen Satz von Elementen weitere Elemente verfügbar sind. Die App sollte nun solange den URL-Wert von @odata.nextLink anfordern, bis alle Seiten von Elementen abgerufen wurden.

Beispiel (letzte Seite in einem Satz)

Unten sehen Sie ein Beispiel für einen Aufruf dieser API zur Aktualisierung Ihres lokalen Zustands.

Anforderung

Hier sehen Sie ein Beispiel für eine Anforderung nach der ursprünglichen Anforderung:

GET https://graph.microsoft.com/v1.0/me/drive/root/delta(token='1230919asd190410jlka')

Antwort

Nachfolgend sehen Sie ein Beispiel der Antwort.

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
        {
            "id": "0123456789abc",
            "name": "folder2",
            "folder": { },
            "deleted": { }
        },
        {
            "id": "123010204abac",
            "name": "file.txt",
            "file": { }
        }
    ],
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?(token='1230919asd190410jlka')"
}

Diese Antwort gibt an, dass im Zeitraum zwischen der ursprünglichen Anforderung und dieser Anforderung zur Aktualisierung des lokalen Zustands das Element folder2 gelöscht wurde und das Element file.txt entweder hinzugefügt oder geändert wurde.

Die letzte Seite mit Elementen enthält die Eigenschaft @odata.deltaLink. Sie spezifiziert die URL, über die zu einem späteren Zeitpunkt Änderungen abgerufen werden können, die bis dahin an dem jetzt aktuellen Elementsatz vorgenommen wurden.

Es kann vorkommen, dass der Dienst keine Liste der Änderungen für ein bestimmtes Token bereitstellen kann (z. B. wenn ein Client versucht, ein altes Token wiederzuverwenden, nachdem er längere Zeit nicht verbunden war, oder wenn sich der Serverstatus geändert hat und ein neues Token erforderlich ist). In solchen Fällen gibt der Dienst einen Fehler des Typs HTTP 410 Gone zurück. Die Fehlerantwort enthält einen der unten aufgeführten Fehlercodes und einen Header Location mit einem neuen „nextLink“, der eine vollständig neue „delta“-Enumeration startet. Nach Abschluss der vollständigen Enumeration die zurückgegebenen Elemente mit Ihrem lokalen Zustand vergleichen und diese Anweisungen befolgen.

Fehlertyp	Anweisungen
`resyncChangesApplyDifferences`	Ersetzen Sie alle lokalen Elemente durch die Serverversion (einschließlich gelöschter Elemente), wenn Sie sicher sind, dass der Dienst bei der letzten Synchronisierung mit den lokalen Änderungen aktualisiert wurde. Laden Sie alle lokalen Änderungen hoch, die dem Server noch nicht bekannt sind.
`resyncChangesUploadDifferences`	Laden Sie alle lokalen Elemente hoch, die der Dienst nicht zurückgegeben hat, und laden Sie alle Dateien hoch, die sich von der Version auf dem Server unterscheiden (wobei Sie beide Kopien beibehalten, wenn Sie nicht sicher sind, welche die aktuelle ist).

Abrufen des aktuellen deltaLink

In einigen Fällen kann es sinnvoll sein, den aktuellen Wert von DeltaLink anzufordern, ohne zunächst die bereits auf dem Laufwerk vorhandenen Elemente aufzulisten.

Dies kann hilfreich sein, wenn die App nur über Änderungen informiert werden möchte und vorhandene Elemente keine Rolle spielen. Rufen Sie zum Abrufen des aktuellen deltaLink delta mit dem Abfragezeichenfolgenparameter ?token=latest auf.

Hinweis: Wenn Sie versuchen, eine vollständige lokale Darstellung der Elemente in einem Ordner oder Laufwerk beizubehalten, müssen Sie delta für die anfängliche Enumeration verwenden. Andere Methoden, z. B. Auslagerung über die children-Sammlung eines Ordners, geben nicht unbedingt jedes einzelne Element zurück, wenn während der Enumeration ein Schreibvorgang ausgeführt wird. Die Verwendung von delta ist die einzige Möglichkeit, um sicherzustellen, dass Sie alle benötigten Daten gelesen haben.

Anforderung

GET /me/drive/root/delta?token=latest

Antwort

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [ ],
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?token=1230919asd190410jlka"
}

Hinweise

Der „delta“-Feed zeigt den aktuellen Zustand jedes Elements, nicht jede Änderung. Wenn ein Element beispielsweise zweimal umbenannt wurde, wird es nur einmal angezeigt, mit seinem neuesten Namen.
Ein Element kann mehrmals in einem delta-Feed aufgeführt werden, aus jeweils unterschiedlichen Gründen. Verwenden Sie das letzte Vorkommen in der Auflistung.
Die Eigenschaft parentReference von Elementen enthält keinen Wert für path. Der Grund: Wenn ein Ordner umbenannt wird, gibt delta keine Nachfolger dieses Ordners zurück. Bei Verwendung von „delta“ sollten Sie Elemente immer anhand ihrer ID nachverfolgen.
Für freigegebene Ordner, die einem Laufwerk hinzugefügt wurden, gibt Delta keine Informationen zu Änderungen innerhalb des freigegebenen Ordners zurück. Stattdessen sollte ein weiterer Delta-Aufruf vorgenommen werden, der sich auf den freigegebenen Ordner ausrichtet.
Delta bietet zusätzliche Einschränkungen für OneDrive for Business. Einzelheiten hierzu finden Sie in den Versionshinweisen.

Fehlerantworten

Zusätzlich zu den vorstehend beschriebenen Fehlern bei der erneuten Synchronisierung finden Sie unter Fehlerantwortenweitere Informationen darüber, wie Fehler zurückgegeben werden.

Freigeben über

Laufwerksänderungen nachverfolgen

Berechtigungen

HTTP-Anforderung

Optionale Abfrageparameter

Parameter

Antwort

Beispiel (ursprüngliche Anforderung)

Anforderung

Antwort

Beispiel (letzte Seite in einem Satz)

Anforderung

Antwort

Abrufen des aktuellen deltaLink

Anforderung

Antwort

Hinweise

Fehlerantworten

Zusätzliche Ressourcen