Verwenden einer Delta-Abfrage zum Nachverfolgen von Änderungen in Microsoft Graph-DatenUse delta query to track changes in Microsoft Graph data

Mit der Delta-Abfrage können Anwendungen neu erstellte, aktualisierte oder gelöschte Entitäten ermitteln, ohne die Zielressource bei jeder Anforderung vollständig lesen zu müssen. Mit der Delta-Abfrage können Microsoft Graph-Anwendungen Änderungen effizient mit einem lokalen Datenspeicher synchronisieren.Delta query enables applications to discover newly created, updated, or deleted entities without performing a full read of the target resource with every request. Microsoft Graph applications can use delta query to efficiently synchronize changes with a local data store.

Verwenden einer Delta-Abfrage zum Nachverfolgen von Änderungen in einer RessourcensammlungUse delta query to track changes in a resource collection

Das typische Abrufmuster sieht folgendermaßen aus:The typical call pattern is as follows:

  1. Die Anwendung ruft zunächst eine GET-Anforderung mit der Delta-Funktion für die gewünschte Ressource auf.The application begins by calling a GET request with the delta function on the desired resource.

  2. Microsoft Graph sendet dann eine Antwort mit der angeforderten Ressource und einem Statustoken.Microsoft Graph sends a response containing the requested resource and a state token.

    a. Wenn eine nextLink-URL zurückgegeben wird, müssen eventuell zusätzliche Seiten mit Daten in der Sitzung abgerufen werden. Die Anwendung nimmt weiterhin Anforderungen über die nextLink-URL vor, um alle Seiten mit Daten abzurufen, bis eine deltaLink-URL in der Antwort zurückgegeben wird.a. If a nextLink URL is returned, there may be additional pages of data to be retrieved in the session. The application continues making requests using the nextLink URL to retrieve all pages of data until a deltaLink URL is returned in the response.

    b. Wenn eine deltaLink-URL zurückgegeben wird, gibt es keine weiteren Daten über den derzeitigen Status der zurückzugebenden Ressource. Für zukünftige Anforderungen verwendet die Anwendung die deltaLink-URL, um Informationen zu Änderungen an der Ressource zu erhalten.b. If a deltaLink URL is returned, there is no more data about the existing state of the resource to be returned. For future requests, the application uses the deltaLink URL to learn about changes to the resource.

  3. Wenn die Anwendung Informationen zu Änderungen an der Ressource benötigt, nimmt sie eine neue Anforderung mit der in Schritt 2 erhaltenen deltaLink-URL vor. Diese Anforderung kann umgehend nach Abschluss von Schritt 2 oder bei der Prüfung auf Änderungen durch die Anwendung vorgenommen werden.When the application needs to learn about changes to the resource, it makes a new request using the deltaLink URL received in step 2. This request may be made immediately after completing step 2 or when the application checks for changes.

  4. Microsoft Graph gibt eine Antwort, in der die seit der vorherigen Anforderung an der Ressource vorgenommenen Änderungen beschrieben werden, sowie eine nextLink-URL oder eine deltaLink-URL zurück.Microsoft Graph returns a response describing changes to the resource since the previous request, and either a nextLink URL or a deltaLink URL.

Hinweis: In Azure Active Directory gespeicherte Ressourcen (z. B. Benutzer und Gruppen) unterstützen Szenarien im Zusammenhang mit „Synchronisieren ab jetzt“.Note: Resources stored in Azure Active Directory (such as users and groups) support "sync from now" scenarios. Deshalb können Sie die Schritte 1 und 2 oben überspringen (wenn Sie nicht den vollständigen Status der Ressource abrufen möchten) und stattdessen den neuesten deltaLink abrufen.This allows you to skip steps 1 and 2 above (if you are not interested in retrieving the full state of the resource) and ask for the latest deltaLink instead. Fügen Sie $deltaToken=latest an die delta-Funktion an; die Antwort enthält dann ein deltaLink und keine Ressourcendaten.Append $deltaToken=latest to the delta function and the response will contain a deltaLink and no resource data.

StatustokenState tokens

Eine GET-Antwort einer Delta-Abfrage umfasst immer eine URL, die in einem nextLink- oder deltaLink-Antwortheader angegeben ist. Die nextLink-URL umfasst ein skipToken, und eine deltaLink-URL umfasst ein deltaToken.A delta query GET response always includes a URL specified in a nextLink or deltaLink response header. The nextLink URL includes a skipToken, and a deltaLink URL includes a deltaToken.

Diese Token sind für den Client nicht transparent. Nachfolgend finden Sie alles, was Sie darüber wissen müssen:These tokens are opaque to the client. The following details are what you need to know about them:

  • Jedes Token gibt den Status an und ist eine Momentaufnahme der Ressource in dieser Runde der Änderungsnachverfolgung.Each token reflects the state and represents a snapshot of the resource in that round of change tracking.

  • Die Statustoken codieren und umfassen auch andere Abfrageparameter (z. B. $select), die in der anfänglichen Delta-Abfrageanforderung angegeben sind. Es ist daher nicht erforderlich, diese in nachfolgenden Delta-Abfrageanforderungen zu wiederholen.The state tokens also encode and include other query parameters (such as $select) specified in the initial delta query request. Therefore, it's not required to repeat them in subsequent delta query requests.

  • Beim Ausführen von Delta-Abfragen können Sie die nextLink- oder deltaLink-URL kopieren und auf den nächsten delta-Funktionsaufruf anwenden, ohne den Inhalt der URL, einschließlich ihres Statustoken, zu überprüfen.When carrying out delta query, you can copy and apply the nextLink or deltaLink URL to the next delta function call without having to inspect the contents of the URL, including its state token.

Optionale AbfrageparameterOptional query parameters

Wenn ein Client einen Abfrageparameter verwendet, muss dieser in der ursprünglichen Anforderung angegeben sein. Microsoft Graph codiert automatisch den angegebenen Parameter in den in der Antwort enthaltenen nextLink oder deltaLink. Die aufrufende Anwendung muss die gewünschten Abfrageparameter nur einmal im Vorfeld angeben. Microsoft Graph fügt die angegebenen Parameter automatisch für alle nachfolgenden Anforderungen hinzu.If a client uses a query parameter, it must be specified in the initial request. Microsoft Graph automatically encodes the specified parameter into the nextLink or deltaLink provided in the response. The calling application only needs to specify their desired query parameters once upfront. Microsoft Graph adds the specified parameters automatically for all subsequent requests.

Für Benutzer und Gruppen gibt es Einschränkungen im Hinblick auf die Verwendung einiger Abfrageparameter:For users and groups, there are restrictions on using some query parameters:

  • Wenn ein $select-Abfrageparameter verwendet wird, bedeutet dies, dass der Client nur Änderungen an den Eigenschaften oder Beziehungen nachverfolgen möchte, die in der $select-Anweisung angegeben sind. Wenn eine Änderung an einer nicht ausgewählten Eigenschaft vorgenommen wird, wird die Ressource, für die diese Eigenschaft geändert wurde, nach einer nachfolgenden Anforderung nicht in der Delta-Antwort angezeigt.If a $select query parameter is used, the parameter indicates that the client prefers to only track changes on the properties or relationships specified in the $select statement. If a change occurs to a property that is not selected, the resource for which that property changed does not appear in the delta response after a subsequent request.

  • $expand wird nur für die Navigationseigenschaften manager und members jeweils für Benutzer und Gruppen unterstützt.$expand is only supported for the manager and members navigational property for users and groups respectively.

  • Mit Bereichsfiltern können Sie Änderungen an einem oder mehreren bestimmten Benutzern bzw. einer oder mehreren bestimmten Gruppen nach objectId nachverfolgen.Scoping filters allow you to track changes to one or more specific users or groups by objectId. Die folgende Anforderung gibt beispielsweise Änderungen für die Gruppen zurück, die mit den im Abfragefilter angegebenen IDs übereinstimmen: https://graph.microsoft.com/beta/groups/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ae5f' or id eq '004d6a07-fe70-4b92-add5-e6e37b8acd8e'For example, the following request: https://graph.microsoft.com/beta/groups/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ae5f' or id eq '004d6a07-fe70-4b92-add5-e6e37b8acd8e' returns changes for the groups matching the ids specified in the query filter.

Ressourcendarstellung in der Delta-AbfrageantwortResource representation in the delta query response

  • Neu erstellte Instanzen einer unterstützten Ressourcen werden in der Delta-Abfrageantwort mithilfe ihrer standardmäßigen Darstellung dargestellt.Newly created instances of a supported resource are represented in the delta query response using their standard representation.

  • Aktualisierte Instanzen werden anhand ihrer ID mit mindestens den Eigenschaften dargestellt, die aktualisiert wurden. Es können aber auch weitere Eigenschaften eingeschlossen werden.Updated instances are represented by their id with at least the properties that have been updated, but additional properties may be included.

  • Beziehungen für Benutzer und Gruppen werden als Anmerkungen in der standardmäßigen Ressourcendarstellung dargestellt. Diese Anmerkungen haben das Format propertyName@delta. Die Anmerkungen sind in der Antwort auf die erste Delta-Abfrageanforderung enthalten.Relationships on users and groups are represented as annotations on the standard resource representation. These annotations use the format propertyName@delta. The annotations are included in the response of the initial delta query request.

Entfernte Instanzen werden durch ihre ID und ein @removed-Objekt dargestellt. Das @removed-Objekt kann zusätzliche Informationen zum Grund der Entfernung der Instanz enthalten. Beispiel: "@removed": {"reason": "changed"}.Removed instances are represented by their id and an @removed object. The @removed object may include additional information about why the instance was removed. For example, "@removed": {"reason": “changed”}.

Mögliche @removed-Gründe sind changed und deleted.Possible @removed reasons can be changed or deleted.

  • Changed gibt an, dass das Element gelöscht wurde und aus deletedItems wiederhergestellt werden kann.Changed indicates the item was deleted and can be restored from deletedItems.

  • Deleted gibt an, dass das Element gelöscht wurde und nicht wiederhergestellt werden kann.Deleted indicates the item is deleted and cannot be restored.

Das @removed-Objekt kann in der Antwort auf die erste Delta-Abfrage und in nachverfolgten (deltaLink-)Antworten zurückgegeben werden. Clients, die Delta-Abfrageanforderungen verwenden, sollten so konzipiert sein, dass sie diese Objekte in den Antworten behandeln.The @removed object can be returned in the initial delta query response and in tracked (deltaLink) responses. Clients using delta query requests should be designed to handle these objects in the responses.

Unterstützte RessourcenSupported resources

Die Delta-Abfrage wird derzeit für die folgenden Ressourcen unterstützt:Delta query is currently supported for the following resources.

RessourcensammlungResource collection APIAPI
Anwendungen (Vorschau)Applications (preview) Delta-Funktion der application-Ressource (Vorschau)delta function of the application resource (preview)
Classes (Vorschau)Classes (preview) Delta-Funktion der Class-Ressource (Vorschau)delta function of the directoryObjects resource (preview)
Verzeichnisobjekte (Vorschau)Directory objects (preview) Delta-Funktion der directoryObjects-Ressource (Vorschau)delta function of the directoryObjects resource (preview)
VerzeichnisrollenDirectory roles Delta-Funktion der directoryRole-Ressource (Vorschau)delta function of the directoryRole resource
Laufwerk-Elemente*Drive items* Delta-Funktion der driveItem-Ressourcedelta function of the driveItem resource
Education-Benutzer (Vorschau)Education users (preview) Delta-Funktion der Education user-Ressource (Vorschau)delta function of the user resource
Ereignisse in einer Kalenderansicht (Datumsbereich) des primären KalendersEvents in a calendar view (date range) of the primary calendar Delta-Funktion der event-Ressourcedelta function of the event resource
GruppenGroups Delta-Funktion der group-Ressourcedelta function of the group resource
E-Mail-OrdnerMail folders Delta-Funktion der mailFolder-Ressourcedelta function of the mailFolder resource
Nachrichten in einem OrdnerMessages in a folder Delta-Funktion der message-Ressourcedelta function of the message resource
Ordner mit persönlichen KontaktenPersonal contact folders Delta-Funktion der contactFolder-Ressourcedelta function of the contactFolder resource
Persönliche Kontakte in einem OrdnerPersonal contacts in a folder Delta-Funktion der contact-Ressourcedelta function of the contact resource
Schulen (Preview)Schools (preview) Delta-Funktion der School-Ressource (Vorschau)delta function of the servicePrincipal resource (preview)
Dienstprinzipale (Vorschau)Service principals (preview) Delta-Funktion der servicePrincipal-Ressource (Vorschau)delta function of the servicePrincipal resource (preview)
BenutzerUsers Delta-Funktion der user-Ressourcedelta function of the user resource
Planner-Elemente** (Vorschau)Planner items** (preview) Delta-Funktion des all-Segments der plannerUser-Ressource (Vorschau)delta function of the all segment of plannerUser resource (preview)

* Das Verwendungsmuster für OneDrive-Ressourcen ähnelt dem der anderen unterstützten Ressourcen, mit geringen Unterschieden in der Syntax.* The usage pattern for OneDrive resources is similar to the other supported resources with some minor syntax differences. Die Delta-Abfrage für Laufwerke wird zwecks Konsistenz mit anderen Ressourcentypen demnächst aktualisiert.Delta query for drives will be updated in the future to be consistent with other resource types. Weitere Informationen zur aktuellen Syntax finden Sie unter Laufwerksänderungen nachverfolgen.For more detail about the current syntax, see Track changes for a drive.

** Das Verwendungsmuster für Planner-Ressourcen ähnelt anderen unterstützten Ressourcen bis auf ein paar Unterschiede.** The usage pattern for Planner resources is similar to other supported resources with a few differences. Weitere Informationen finden Sie unter Änderungen für Planner nachverfolgen.For details, see Track changes for Planner.

VoraussetzungenPrerequisites

Dieselben Berechtigungen, die zum Lesen einer bestimmten Ressource erforderlich sind, werden auch zur Durchführung der Delta-Abfrage für diese Ressource benötigt.The same permissions that are required to read a specific resource are also required to perform delta query on that resource.

Beispiele für die Delta-AbfrageanforderungDelta query request examples