Freigeben über

driveItem: delta

  • Artikel

Namespace: microsoft.graph

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

Nachverfolgen von Änderungen in einem driveItem und seinen untergeordneten Elemente im Laufe der Zeit.

Die App ruft zunächst delta ohne Parameter auf. Der Dienst beginnt mit dem Aufzählen der Laufwerkhierarchie und gibt Seiten mit Elementen und entweder oder @odata.nextLink zurück @odata.deltaLink. 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.

Nachdem Sie alle Änderungen erhalten haben, können Sie sie auf Ihren 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: Sie sollten einen Ordner nur lokal löschen, wenn er nach dem Synchronisieren aller Änderungen leer ist.

Berechtigungen

Wählen Sie für diese API die Als am wenigsten privilegierten Berechtigungen gekennzeichneten Berechtigungen aus. Verwenden Sie nur dann eine Berechtigung mit höheren Berechtigungen , wenn dies für Ihre App erforderlich ist. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) Files.Read Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegiert (persönliches Microsoft-Konto) Files.Read Files.Read.All, Files.ReadWrite, Files.ReadWrite.All
App 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

Funktionsparameter

Parameter Typ 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. Wenn ein vorheriges Deltatoken seit diesem Token einen neuen Zustand zurückgibt.

Optionale Abfrageparameter

Diese Methode unterstützt die $selectOData-Abfrageparameter , $expandund $top zum Anpassen der Antwort.

Anforderungsheader

Name Beschreibung
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über die Authentifizierung und Autorisierung.
deltaExcludeParent Zeichenfolge. Wenn dieser Anforderungsheader enthalten ist, enthält die Antwort die elemente, die geändert wurden, und nicht die übergeordneten Elemente in der Hierarchie.

Anforderungstext

Geben Sie keinen Anforderungstext für diese Methode an.

Antwort

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

Zusätzlich zur Auflistung von DriveItems enthält die Antwort auch eine der folgenden Eigenschaften:

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

Beispiele

Beispiel 1: Ursprüngliche Anforderung

Hier sehen Sie ein Beispiel dafür, wie Sie diese API aufrufen, um Ihren lokalen Zustand einzurichten.

Anforderung

Hier sehen Sie ein Beispiel für die erste Anforderung.

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

Antwort

Das folgende Beispiel zeigt die 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 der Änderungen, und die @odata.nextLink-Eigenschaft gibt an, dass mehr Elemente in der aktuellen Gruppe von Elementen verfügbar sind. Ihre App sollte weiterhin den URL-Wert von @odata.nextLink anfordern, bis alle Seiten mit Elementen abgerufen werden.

Beispiel 2: Letzte Seite in einem Satz

Das folgende Beispiel zeigt, wie Sie diese API aufrufen, um Ihren lokalen Zustand zu aktualisieren.

Anforderung

Das folgende Beispiel zeigt eine Anforderung nach der ersten Anforderung.

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

Antwort

Das folgende Beispiel zeigt die 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 der Elemente enthält die eigenschaft @odata.deltaLink , die die URL bereitstellt, die später zum Abrufen von Änderungen seit dem aktuellen Elementsatz verwendet werden kann.

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 die Verbindung für längere Zeit getrennt wurde, oder wenn sich der Serverstatus geändert hat und ein neues Token erforderlich ist). In diesen Fällen gibt der Dienst einen HTTP 410 Gone Fehler mit einer Fehlerantwort mit einem Fehlercode und einem Location Header zurück, der einen neuen nextLink enthält, der eine neue Delta-Enumeration von Grund auf startet. Vergleichen Sie nach Abschluss der vollständigen Enumeration die zurückgegebenen Elemente mit Ihrem lokalen Zustand, und befolgen Sie diese Anweisungen.

Fehlertyp Anweisungen
resyncChangesApplyDifferences Ersetzen Sie alle lokalen Elemente durch die Version des Servers (einschließlich Löschvorgängen), wenn Sie sicher sind, dass der Dienst bei der letzten Synchronisierung mit Ihren lokalen Änderungen auf dem neuesten Stand war. 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 des Servers unterscheiden (behalten Sie beide Kopien bei, wenn Sie nicht sicher sind, welche aktueller ist).

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 Ihre App nur über Änderungen informiert werden möchte und keine Informationen zu vorhandenen Elementen benötigt. 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

Das folgende Beispiel zeigt eine Anfrage.

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

Antwort

Das folgende Beispiel zeigt die 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"
}

Beispiel 4: Abrufen von Delta-Ergebnissen mithilfe eines Zeitstempels

In einigen Szenarien kennt der Client möglicherweise den Zustand eines Laufwerks bis zu einem bestimmten Zeitpunkt, verfügt zu diesem Zeitpunkt jedoch nicht über einen deltaLink. In diesem Fall kann der Client mit einem URL-codierten Zeitstempel für den Wert des token Abfragezeichenfolgenparameters aufrufendelta, ?token=2021-09-29T20%3A00%3A00Z z. B. oder '?token=2021-09-29T12%3A00%3A00%2B8%3A00'.

Die Verwendung eines Zeitstempels anstelle eines Tokens wird nur für OneDrive for Business und SharePoint unterstützt.

Hinweis: Clients sollten nach Möglichkeit den deltaLink verwenden, der von delta Abfragen bereitgestellt wird, anstatt ein eigenes Token zu generieren. Diese Funktion sollte nur verwendet werden, wenn der deltaLink nicht bekannt ist.

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

GET /me/drive/root/delta?token=2021-09-29T20%3A00%3A00Z

Antwort

Das folgende Beispiel zeigt die 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')"
}

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 parentReference -Eigenschaft für Elemente enthält keinen Wert für path. Dies liegt daran, dass das Umbenennen eines Ordners nicht dazu führt, dass Nachfolger des Ordners von delta zurückgegeben werden. Wenn Sie Delta verwenden, sollten Sie Elemente immer nach ID nachverfolgen.

  • Delta-Abfragen geben je nach Vorgang und Diensttyp einige DriveItem-Eigenschaften nicht zurück, wie in den folgenden Tabellen gezeigt.

    OneDrive for Business

    Typ des Vorgangs Eigenschaften, die von der Delta-Abfrage ausgelassen werden
    Create/Modify ctag
    Delete ctag, name

    OneDrive (Consumer)

    Typ des Vorgangs Eigenschaften, die von der Delta-Abfrage ausgelassen werden
    Create/Modify n/v
    Delete ctag, size

Überprüfen von Berechtigungshierarchien

Standardmäßig umfasst die Delta-Abfrageantwort die Freigabe von Informationen für alle Elemente in der Abfrage, die sich geändert haben, auch wenn sie ihre Berechtigungen vom übergeordneten Element erben und keine direkten Freigabeänderungen selbst vorgenommen haben. Dies führt dann in der Regel zu einem Folgeaufruf, um die Berechtigungsdetails für jedes Element und nicht nur für diejenigen abzurufen, deren Freigabeinformationen geändert wurden. Sie können Ihre Kenntnisse über die Vorgehensweise von Berechtigungsänderungen optimieren, indem Sie die Prefer: hierarchicalsharing-Kopfzeile zu Ihrer Delta Abfrageanforderung hinzufügen.

Wenn der Prefer: hierarchicalsharing Header bereitgestellt wird, werden Freigabeinformationen für den Stamm der Berechtigungshierarchie sowie für Elemente zurückgegeben, die explizit Änderungen an der Freigabe aufweisen. In Fällen, in denen die Freigabeänderung darin besteht, die Freigabe von einem Element zu entfernen, finden Sie ein leeres Freigabefacet, um zwischen Elementen zu unterscheiden, die von ihrem übergeordneten Element erben, und solchen, die eindeutig sind, aber keine Freigabelinks haben. Sie können dieses leere Freigabefacet auch im Stamm einer Berechtigungshierarchie sehen, die nicht freigegeben ist, um den ursprünglichen Bereich festzulegen.

In vielen Überprüfungsszenarien möchten Sie vielleicht insbesondere Änderungen an Berechtigungen überprüfen. Wenn Sie in der Delta-Abfrageantwort deutlich machen möchten, welche Änderungen das Ergebnis der Berechtigungsänderungen sind, können Sie die Prefer: deltashowsharingchanges-Kopfzeile angeben. Wenn dieser Header bereitgestellt wird, haben alle Elemente, die aufgrund von Berechtigungsänderungen in der Deltaabfrageantwort angezeigt werden, die @microsoft.graph.sharedChanged":"True" OData-Anmerkung. Dieses Feature ist für SharePoint und OneDrive for Business, aber nicht für OneDrive-Konten von Verbrauchern geeignet.

Hinweis

  • Für die Verwendung von Prefer: deltashowsharingchanges -Headern müssen Sie und Prefer: deltatraversepermissiongapsverwendenPrefer: deltashowremovedasdeleted. Diese Kopfzeilenwerte können in einer einzigen Kopfzeile verbunden werden: Prefer: deltashowremovedasdeleted, deltatraversepermissiongaps, deltashowsharingchanges.

  • Um Berechtigungen ordnungsgemäß zu verarbeiten, muss Ihre Anwendung Sites.FullControl.All-Berechtigungen anfordern.

Weitere Informationen zu Scanszenarien finden Sie unter Bewährte Methoden zum Ermitteln von Dateien und Erkennen von Änderungen im großen Stil.

Fehlerantworten

Ausführliche Informationen zur Rückgabe von Fehlern finden Sie zusätzlich zu den ausführlichen Fehlern unter Fehlerantworten .

Verwandte Inhalte

Verwenden einer Delta-Abfrage zum Nachverfolgen von Änderungen in Microsoft Graph-Daten. Bewährte Methoden zum Ermitteln von Dateien und Erkennen von Änderungen im großen Stil.