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 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 the query parameters once upfront. Microsoft Graph adds the specified parameters automatically for all subsequent requests.

Beachten Sie im Hinblick auf optionale Abfrageparameter Folgendes:Note the following regarding optional query parameters:

  • $orderby wird für Delta-Abfragen nicht unterstützt.$orderby is not a supported for delta queries.
    • Gehen Sie nicht von einer bestimmten Reihenfolge bei den von einer Delta-Abfrage zurückgegebenen Antworten aus.Do not assume a specific sequence of the responses returned from a delta query. Gehen Sie davon aus, dass das selbe Element an beliebigen Stellen in der Sequenz nextLink angezeigt werden kann, und berücksichtigen Sie dies in Ihrer Zusammenführungslogik.Assume that the same item can show up anywhere in the nextLink sequence and handle that in your merge logic.
  • $top wird für Delta-Abfragen nicht unterstützt, und die Anzahl der Objekte auf jeder Seite kann je nach Ressourcentyp und Art der Änderungen an der Ressource variieren.$top is not supported for delta queries, and the number of objects in each page can vary depending on the resource type and the type of changes made to the resource.

Für Benutzer und Gruppen gelten die folgenden Einschränkungen im Hinblick auf die Verwendung einiger Abfrageparameter:For users and groups, the following restrictions apply to using using some query parameters:

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.

  • $select unterstützt zudem die Navigationseigenschaften manager und members jeweils für Benutzer und Gruppen.$select is only supported for the manager and members navigational property for users and groups respectively. Wenn Sie diese Eigenschaften auswählen, können Sie Änderungen an Manager- und Gruppenmitgliedschaften des Benutzers nachverfolgen.Selecting those properties allows tracking of changes to user's manager and group memberships.

  • Mit Bereichsfiltern können Sie Änderungen an einem oder mehreren bestimmten Benutzern bzw. einer oder mehreren bestimmten Gruppen nach Objekt-ID nachverfolgen.Scoping filters allow you to track changes to one or more specific users or groups by object ID. Die folgende Anforderung gibt beispielsweise Änderungen für die Gruppen zurück, die den im Abfragefilter angegebenen IDs entsprechen.For example, the following request returns changes for the groups matching the IDs specified in the query filter.

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-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.Removed instances are represented using only their id and an @removed node. Das @removed-Objekt kann zusätzliche Informationen zum Grund der Entfernung der Instanz enthalten.The @removed node may include additional information about why the instance was removed. Beispiel: "@removed": {"reason": "changed"}.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 Class 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 Education user resource (preview)
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 School 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)
chatMessages in einem Kanal (Vorschau)chatMessages in a channel (preview) Delta-Funktion der chatMessagedelta function of the chatMessage

* 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.

EinschränkungenLimitations

Außerhalb des primären Datenspeichers gespeicherte EigenschaftenProperties stored outside of the main data store

Einige Ressourcen enthalten Eigenschaften, die außerhalb des primären Datenspeichers für die Ressource gespeichert sind (die Benutzerressource wird beispielsweise meist im Azure Ad-System gespeichert, während einige Eigenschaften wie skills in SharePoint Online gespeichert werden).Some resources contain properties that are stored outside of the main data store for the resource (for example, the user resource is mostly stored in the Azure AD system, while some properties, like skills, are stored in SharePoint Online). Derzeit werden diese Eigenschaften im Rahmen der Änderungsnachverfolgung nicht unterstützt. Änderungen an einer dieser Eigenschaften führen nicht dazu, dass ein Objekt in der Delta-Abfrageantwort angezeigt wird.Currently, those properties are not supported as part of change tracking; a change to one of those properties will not result in an object showing up in the delta query response. Aktuell lösen nur die im Hauptdatenspeicher gespeicherten Eigenschaften Änderungen in der Delta-Abfrage aus.Currently, only the properties stored in the main data store trigger changes in the delta query.

Um zu überprüfen, ob eine Eigenschaft in der Delta-Abfrage verwendet werden kann, versuchen Sie, einen normalen GET-Vorgang für die Ressourcensammlung auszuführen, und wählen Sie die gewünschte Eigenschaft aus.To verify that a property can be used in delta query, try to perform a regular GET operation on the resource collection, and select the property you're interested in. Sie können z. B. die Eigenschaft skills für die Benutzersammlung ausprobieren.For example, you can try the skills property on the users collection.

GET https://graph.microsoft.com/v1.0/users/?$select=skills

Da die Eigenschaft skills außerhalb von Azure AD gespeichert ist, sieht die Antwort wie folgt aus.Because the skills property is stored outside of Azure AD, the following is the response.

HTTP/1.1 501 Not Implemented
Content-type: application/json

{
    "error": {
        "code": "NotImplemented",
        "message": "This operation target is not yet supported.",
        "innerError": {
            "request-id": "...",
            "date": "2019-09-20T21:47:50"
        }
    }
}

Dies weist darauf hin, dass die Eigenschaft skills für die Delta-Abfrage der Ressource user nicht unterstützt wird.This tells you that the skills property is not supported for delta query on the user resource.

Navigationseigenschaften werden nicht unterstützt.Navigation properties are not supported. Sie können beispielsweise keine Änderungen an der Benutzersammlung nachverfolgen, die Änderungen an deren Eigenschaft photo umfassen würden. photo ist eine Navigationseigenschaft, die außerhalb der Benutzerentität gespeichert ist, und Änderungen daran führen nicht dazu, dass das Benutzerobjekt in die Delta-Antwort einbezogen wird.For example, you cannot track changes to the users collection that would include changes to their photo property; photo is a navigation property stored outside of the user entity, and changes to it do not cause the user object to be included in the delta response.

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