driveItem: delta
Namespace: microsoft.graph
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 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 deleted
Facet 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
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. Im Fall eines vorherigen Delta-Token wird der neue Status seit diesem Token zurückgegeben. |
Optionale Abfrageparameter
Diese Methode unterstützt die $select
OData-Abfrageparameter , $expand
und $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 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 mit Änderungen, wenn weitere Änderungen in der aktuellen Gruppe 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. |
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/v1.0/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 wurden.
Beispiel 2: Letzte Seite in einem Satz
Hier ist ein Beispiel dafür, wie Sie diese API aufrufen, um Ihren lokalen Zustand zu aktualisieren.
Anforderung
Hier sehen Sie eine Beispielanforderung nach der ersten Anforderung.
GET https://graph.microsoft.com/v1.0/me/drive/root/delta(token='MzslMjM0OyUyMzE7MzsyM2YwNDVhMS1lNmRmLTQ1N2MtOGQ5NS1hNmViZDVmZWRhNWQ7NjM3OTQzNzQwODQ3NTcwMDAwOzU4NTk2OTY0NDslMjM7JTIzOyUyMzA')
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='MzslMjM0OyUyMzE7MzsyM2YwNDVhMS1lNmRmLTQ1N2MtOGQ5NS1hNmViZDVmZWRhNWQ7NjM3OTQzNzQwODQ3NTcwMDAwOzU4NTk2OTY0NDslMjM7JTIzOyUyMzA')"
}
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 zurück, die einen der folgenden Fehlercodes enthält, sowie einen Location
Header, der einen neuen nextLink enthält, der eine neue Deltaaufzählung 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). |
Beispiel 3: 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 diechildren
-Sammlung eines Ordners, geben nicht unbedingt jedes einzelne Element zurück, wenn während der Enumeration ein Schreibvorgang ausgeführt wird. Die Verwendung vondelta
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"
}
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
GET /me/drive/root/delta?token=2021-09-29T20%3A00%3A00Z
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')"
}
HinwBemerkungeneise
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. Bei Verwendung von „delta“ sollten Sie Elemente immer anhand ihrer 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. Dieses leere Freigabefacet wird auch im Stamm einer Berechtigungshierarchie angezeigt, die nicht zum Einrichten des ursprünglichen Bereichs freigegeben ist.
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 undPrefer: deltatraversepermissiongaps
verwendenPrefer: 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
Zusätzlich zu den vorstehend beschriebenen Fehlern bei der erneuten Synchronisierung finden Sie unter Fehlerantwortenweitere Informationen darüber, wie Fehler zurückgegeben werden.
Verwandte Inhalte
Verwenden von Deltaabfragen zum Nachverfolgen von Änderungen in Microsoft Graph-DatenBewährte Methoden zum Ermitteln von Dateien und Erkennen von Änderungen im großen Stil