Verwenden einer Delta-Abfrage zum Nachverfolgen von Änderungen in Microsoft Graph-Daten

  • Artikel

Deltaabfrage, auch als Änderungsnachverfolgung bezeichnet, ermöglicht Es Anwendungen, neu erstellte, aktualisierte oder gelöschte Entitäten zu ermitteln, ohne bei jeder Anforderung einen vollständigen Lesevorgang der Zielressource durchzuführen. Mit der Delta-Abfrage können Microsoft Graph-Anwendungen Änderungen effizient mit einem lokalen Datenspeicher synchronisieren.

Die Verwendung von Delta-Abfragen hilft Ihnen, das ständige Abfragen von Microsoft Graph zu vermeiden, da die App nur Daten anfordert, die sich seit der letzten Anforderung geändert haben. Dieses Muster ermöglicht es der Anwendung, die menge der von ihr angeforderten Daten zu reduzieren, wodurch die Kosten für die Anforderung reduziert werden und daher wahrscheinlich die Wahrscheinlichkeit eingeschränkt wird, dass die Anforderungen gedrosselt werden.

Verwenden einer Delta-Abfrage zum Nachverfolgen von Änderungen in einer Ressourcensammlung

Das typische Abrufmuster sieht folgendermaßen aus:

  1. Die Anwendung stellt eine GET-Anforderung mit der Delta-Funktion für die gewünschte Ressource. Beispiel: GET https://graph.microsoft.com/v1.0/users/delta.

    Tipp

    /delta ist eine Verknüpfung für den vollqualifizierten Namen /microsoft.graph.delta. Von Microsoft Graph SDKs generierte Anforderungen verwenden den vollqualifizierten Namen.

  2. Microsoft Graph antwortet mit der angeforderten Ressource und einem Zustandstoken.

    a. Wenn Microsoft Graph eine @odata.nextLink URL zurückgibt, müssen in der Sitzung weitere Seiten mit Daten abgerufen werden, auch wenn die aktuelle Antwort ein leeres Ergebnis enthält. Die Anwendung verwendet die @odata.nextLink URL, um weiterhin Anforderungen zum Abrufen aller Datenseiten zu senden, bis Microsoft Graph eine @odata.deltaLink URL in der Antwort zurückgibt.

    b. Wenn Microsoft Graph eine @odata.deltaLink URL zurückgibt, gibt es keine Weiteren Daten zum vorhandenen Zustand der Ressource, die in der aktuellen Sitzung zurückgegeben werden sollen. Für zukünftige Anforderungen verwendet die Anwendung die @odata.deltaLink-URL, um Informationen zu Änderungen an der Ressource zu erhalten.

    Hinweis

    Die Microsoft Graph-Antwort in Schritt 2 enthält die Ressourcen, die derzeit in der Sammlung vorhanden sind. Ressourcen, die vor der ersten Deltaabfrage gelöscht wurden, werden nicht zurückgegeben. Updates, die vor der anfänglichen Anforderung vorgenommen wurden, werden in der Ressource zusammengefasst, die als neuester Status zurückgegeben wird.

  3. Wenn sich die Anwendung über Änderungen an der Ressource informieren muss, verwendet sie die URL, die @odata.deltaLink sie in Schritt 2 erhalten hat, um Anforderungen zu stellen. Die Anwendung kann diese Anforderung sofort nach Abschluss von Schritt 2 oder bei der Überprüfung auf Änderungen stellen.

  4. Microsoft Graph gibt eine Antwort, in der die seit der vorherigen Anforderung an der Ressource vorgenommenen Änderungen beschrieben werden, sowie eine @odata.nextLink-URL oder eine @odata.deltaLink-URL zurück.

Hinweis

  • Ressourcen, die in Microsoft Entra ID (z. B. Benutzer und Gruppen) gespeichert sind, unterstützen "Jetzt synchronisieren"-Szenarien. Deshalb können Sie die Schritte 1 und 2 überspringen (wenn Sie nicht den vollständigen Status der Ressource abrufen möchten) und stattdessen den neuesten @odata.deltaLink abrufen. Fügen Sie $deltatoken=latest an die delta-Funktion an; die Antwort enthält dann ein @odata.deltaLink und keine Ressourcendaten. Ressourcen in OneDrive und SharePoint unterstützen dieses Feature ebenfalls, erfordern token=latest aber stattdessen.
  • $selectDie Abfrageparameter und $deltaLink werden für einige Microsoft Entra Ressourcen unterstützt, sodass Kunden die Eigenschaften ändern können, die sie für ein vorhandenes @odata.deltaLinknachverfolgen möchten. Deltaabfragen mit und $select$skiptoken werden nicht unterstützt.

Statustoken

Eine GET-Antwort einer Delta-Abfrage umfasst immer eine URL, die in einem @odata.nextLink- oder @odata.deltaLink-Antwortheader angegeben ist. Die @odata.nextLink URL enthält ein $skiptoken, und eine @odata.deltaLink URL enthält eine $deltatoken.

Diese Token sind für die Client-App nicht transparent, aber wichtig wie folgt:

  • Jedes Token gibt den Status an und ist eine Momentaufnahme der Ressource in dieser Runde der Änderungsnachverfolgung.
  • Die Zustandstoken codieren und enthalten Abfrageparameter (z $select. B. ), die in der anfänglichen Deltaabfrageanforderung angegeben sind. Ändern Sie daher keine nachfolgenden Deltaabfrageanforderungen, um diese Abfrageparameter zu wiederholen.
  • Beim Ausführen von Delta-Abfragen können Sie die @odata.nextLink- oder @odata.deltaLink-URL kopieren und auf den nächsten delta-Funktionsaufruf anwenden, ohne den Inhalt der URL, einschließlich ihres Statustoken, zu überprüfen.

Optionale Abfrageparameter

Wenn ein Client einen Abfrageparameter verwendet, muss dieser in der ersten Anforderung angegeben werden. Microsoft Graph codiert den angegebenen Abfrageparameter automatisch in oder @odata.nextLink@odata.deltaLink in der Antwort und in allen nachfolgenden @odata.nextLink - oder @odata.deltaLink -URLs.

Beachten Sie die allgemein eingeschränkte Unterstützung für die folgenden optionalen Abfrageparameter:

  • $orderby

    Gehen Sie nicht von einer bestimmten Sequenz der Von einer Deltaabfrage zurückgegebenen Antworten aus. Gehen Sie davon aus, dass das selbe Element an beliebigen Stellen in der Sequenz @odata.nextLink angezeigt werden kann, und berücksichtigen Sie dies in Ihrer Zusammenführungslogik.

  • $top

    Die Anzahl der Objekte auf jeder Seite kann je nach Ressourcentyp und Art der Änderungen an der Ressource variieren.

Für die Ressource message schauen Sie sich die Einzelheiten zur Unterstützung von Abfrageparametern in einer Delta-Abfrage an.

Für die Ressourcen user und group gibt es Einschränkungen im Hinblick auf die Verwendung einiger Abfrageparameter:

  • $expand wird nicht unterstützt.

  • $top wird nicht unterstützt.

  • $orderby wird nicht unterstützt.

  • Wenn ein $select Abfrageparameter verwendet wird, gibt der -Parameter an, dass der Client es vorzieht, nur Änderungen an den in der $select -Anweisung angegebenen Eigenschaften oder Beziehungen nachzuverfolgen. Wenn eine Änderung an einer Eigenschaft auftritt, die nicht ausgewählt ist, wird die Ressource, für die diese Eigenschaft geändert wurde, nach einer nachfolgenden Anforderung nicht in der Deltaantwort angezeigt.

  • $select unterstützt außerdem Nagivationseigenschaften für Vorgesetzte und Mitglieder für Benutzer bzw. Gruppen. Wenn Sie diese Eigenschaften auswählen, können Sie Änderungen an Manager- und Gruppenmitgliedschaften des Benutzers nachverfolgen.

  • Mithilfe von Bereichsfiltern können Sie Änderungen an einem oder mehreren bestimmten Benutzern oder Gruppen nachverfolgen und nur nach Objekt-ID filtern. Die folgende Anforderung gibt beispielsweise Änderungen für die Gruppen zurück, die den im Abfragefilter angegebenen IDs entsprechen.

https://graph.microsoft.com/beta/groups/delta/?$filter=id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ae5f' or id eq '004d6a07-fe70-4b92-add5-e6e37b8acd8e'

Ressourcendarstellung in der Delta-Abfrageantwort

  • Neu erstellte Instanzen einer unterstützten Ressourcen werden in der Delta-Abfrageantwort mithilfe ihrer standardmäßigen Darstellung dargestellt.

  • Aktualisierte Instanzen werden durch ihre ID mit mindestens den aktualisierten Eigenschaften dargestellt, andere Eigenschaften können jedoch enthalten sein.

  • Beziehungen zu Benutzern und Gruppen werden in der Standardressourcendarstellung als Anmerkungen dargestellt. Diese Anmerkungen verwenden das Format propertyName@delta. Die Anmerkungen sind in der Antwort der anfänglichen Deltaabfrageanforderung enthalten.

  • Entfernte Instanzen werden durch ihre ID und ein @removed-Objekt dargestellt. Das @removed-Objekt kann zusätzliche Informationen darüber enthalten, warum die instance entfernt wurde. Beispiel: "@removed": {"reason": "changed"}. Mögliche @removed-Gründe sind changed oder deleted.

    • changed gibt an, dass das Element gelöscht wurde und aus deletedItems wiederhergestellt werden kann.

    • deleted gibt an, dass das Element gelöscht wurde und nicht wiederhergestellt werden kann.

      Das @removed-Objekt kann in der ersten Deltaabfrageantwort und in nachverfolgten (@odata.nextLink)-Antworten zurückgegeben werden. Beispielsweise wird ein gelöschtes Verzeichnisobjekt, das aus gelöschten Elementen wiederhergestellt werden kann, als "@removed": {"reason": "changed"}angezeigt. Clients, die Delta-Abfrageanforderungen verwenden, sollten so konzipiert sein, dass sie diese Objekte in den Antworten verarbeiten.

  • Instanzen, die von deletedItems wiederhergestellt wurden , werden in der Delta-Abfrageantwort als neu erstellte Instanzen angezeigt.

Hinweis

Eine einzelne Entität kann mehrmals in der Antwort enthalten sein, wenn diese Entität mehrmals und unter bestimmten Bedingungen geändert wurde. Mit Hilfe von Delta-Abfragen kann Ihre Anwendung alle Änderungen auflisten, aber sie kann nicht sicherstellen, dass die Entitäten in einer einzigen Antwort vereinheitlicht werden.

Unterstützte Ressourcen

Die Delta-Abfrage wird derzeit für die folgenden Ressourcen unterstützt: Einige Ressourcen, die in v1.0 verfügbar sind, verfügen über die entsprechenden Deltafunktionen, die sich wie angegeben noch in der Vorschau status befinden.

Hinweis: Die Delta-Funktion für Ressourcen, die mit einem Sternchen (*) gekennzeichnet sind, sind nur auf dem /beta Endpunkt verfügbar.

Ressourcensammlung API
application Application: Delta-Funktion
administrativeUnit administrativeUnit: delta-Funktion
callRecording * callRecording: delta-Funktion
callTranscript * callTranscript: Delta-Funktion
chatMessage chatMessage: Delta-Funktion
device device: delta-Funktion
directoryRole directoryRole: delta-Funktion
directoryObject directoryObject: delta-Funktion
driveItem1 driveItem: Delta-Funktion
educationAssignment educationAssignment: Delta-Funktion
educationCategory educationCategory: Delta-Funktion
educationClass educationClass: Delta-Funktion
educationSchool educationSchool: Delta-Funktion
educationUser educationUser: Delta-Funktion
Ereignis Event: Delta-Funktion
Gruppe group: delta-Funktion
listItem1 listItem: delta-Funktion
mailFolder mailFolder: Delta-Funktion
Nachricht message: Delta-Funktion
orgContact orgContact: delta-Funktion
oAuth2PermissionGrant oAuth2PermissionGrant: delta-Funktion
contactFolder contactFolder: delta-Funktion
Kontaktressource contact: delta-Funktion
plannerBucket * plannerBucket: delta-Funktion
plannerUser2 plannerUser: delta-Funktion
sites delta-Funktion der Standortressource
servicePrincipal servicePrincipal: delta-Funktion
todoTask todoTask: delta-Funktion
todoTaskList todoTaskList: Delta-Funktion
user user: delta function

Hinweis

1 Das Verwendungsmuster für OneDrive- und SharePoint-Ressourcen ähnelt den anderen unterstützten Ressourcen mit einigen geringfügigen Syntaxunterschieden. Weitere Informationen zur aktuellen Syntax finden Sie unter driveItem: delta und listItem: delta.

2 Das Verwendungsmuster für Planner Ressourcen ähnelt anderen unterstützten Ressourcen mit einigen Unterschieden. Weitere Informationen finden Sie unter planner: delta.

Nationale Clouds

Delta-Abfragen für unterstützte Ressourcen sind für Kunden verfügbar, die in der öffentlichen Cloud, Microsoft Cloud for US Government und Microsoft Cloud China gehostet werden, die von 21Vianet betrieben wird.

Begrenzungen

Änderungen an Eigenschaften, die außerhalb des Standard Datenspeichers gespeichert sind, werden nicht nachverfolgt.

Einige Ressourcen enthalten Eigenschaften, die außerhalb des Standard Datenspeichers für die Ressource gespeichert sind. Beispielsweise werden die Benutzerressourcendaten größtenteils in Microsoft Entra ID gespeichert, aber einige ihrer Eigenschaften, z. B. Skills, werden in SharePoint Online gespeichert. Derzeit lösen nur die im Standard Datenspeicher gespeicherten Eigenschaften Änderungen in der Deltaabfrage aus. Eigenschaften, die außerhalb des Standard Datenspeichers gespeichert sind, werden im Rahmen der Änderungsnachverfolgung nicht unterstützt. Daher führt eine Änderung an einer dieser Eigenschaften nicht dazu, dass ein Objekt in der Deltaabfrageantwort angezeigt wird.

Weitere Informationen zu Eigenschaften, die außerhalb des Standard Datenspeichers gespeichert sind, finden Sie in der Dokumentation zu Benutzern und Gruppen.

Verarbeitungsverzögerungen

Erwarten Sie unterschiedliche Verzögerungen zwischen dem Zeitpunkt, zu dem sich eine Ressource instance ändert, und dem Zeitpunkt, zu dem die nachverfolgte Änderung in einer Deltaabfrageantwort widergespiegelt wird.

Manchmal werden die Änderungen am Objekt aufgrund von Replikationsverzögerungen möglicherweise nicht sofort angezeigt, wenn Sie oder @odata.nextLink@odata.deltaLinkauswählen. Wiederholen Sie die @odata.nextLink oder @odata.deltaLink nach einiger Zeit, um die neuesten Änderungen abzurufen.

Wiederholungen

Ihre Anwendung muss für Wiederholungen vorbereitet werden, die auftreten, wenn die gleiche Änderung in nachfolgenden Antworten erscheint. Deltaabfragen bemühen sich zwar nach besten Kräften, Die Wiedergaben zu reduzieren, sie sind jedoch weiterhin möglich.

Synchronisierungszurücksetzung

Die Deltaabfrage kann den Antwortcode 410 Gone und einen Location-Header zurückgeben, der eine Anforderungs-URL mit einem leeren $deltatoken enthält (identisch mit der ursprünglichen Abfrage). Dies status in der Regel geschieht, um Dateninkonsistenzen aufgrund interner Wartung oder Migration des Zielmandanten zu verhindern, und ist ein Hinweis darauf, dass die Anwendung mit einer vollständigen Synchronisierung des Zielmandanten neu gestartet werden muss.

Tokendauer

Delta-Tokens sind nur für eine bestimmte Dauer gültig, bevor die Client-Anwendung erneut eine vollständige Synchronisierung ausführen muss.

  • Für Verzeichnisobjekte beträgt der Grenzwert sieben Tage.
  • Bei Objekten für Schulung und Weiterbildung (educationSchool, educationUser und educationClass) beträgt das Limit ebenfalls sieben Tage.
  • Für Outlook-Entitäten (message, mailFolder, event, contact, contactFolder, todoTask und todoTaskList) ist die Obergrenze nicht festgelegt. Dies hängt von der Größe des internen Deltatokencaches ab. Während neue Delta-Token im Cache kontinuierlich hinzugefügt werden, werden nach Überschreitung der Cachekapazität die älteren Delta-Token gelöscht.

Wenn das Token abläuft, sollte der Dienst mit einem Fehler der 40X-Serie mit Fehlercodes wie syncStateNotFoundreagieren. Weitere Informationen finden Sie unter Fehlercodes in Microsoft Graph.

Kombinieren von Deltaabfragen und Änderungsbenachrichtigungen

Eine App kann Microsoft Graph-Änderungsbenachrichtigungen verwenden, um eine Benachrichtigung zu erhalten, wenn sich eine bestimmte Ressource ändert. Die Anwendung kann dann die Delta-Abfrage verwenden, um alle Änderungen seit der letzten Anforderung abzurufen.

Anwendungen können diese Strategie verwenden, um (nur für unterstützte Ressourcen) die Notwendigkeit, Microsoft Graph häufig abzufragen und diese Änderungen zu verarbeiten, um einen lokalen Datenspeicher synchron zu halten, nahezu zu eliminieren, wodurch die Wahrscheinlichkeit, dass ihre Anforderungen gedrosselt werden, erheblich reduziert wird.

Verwandte Inhalte

Weitere Informationen zur Deltaabfrage finden Sie in den folgenden Tutorials: