Utiliser la requête delta pour suivre les modifications apportées aux données Microsoft GraphUse delta query to track changes in Microsoft Graph data

La requête delta permet aux applications de découvrir des entités nouvellement créées, mises à jour ou supprimées sans parcourir la totalité de la ressource cible à chaque requête. Les applications Microsoft Graph peuvent utiliser une requête delta pour synchroniser efficacement les modifications avec une banque de données locale.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.

Utilisation de la requête delta pour suivre les modifications apportées à une collection de ressourcesUse delta query to track changes in a resource collection

Voici comment se déroule un appel classique :The typical call pattern is as follows:

  1. L’application commence par appeler une requête GET avec la fonction delta sur la ressource souhaitée.The application begins by calling a GET request with the delta function on the desired resource.

  2. Microsoft Graph envoie une réponse contenant la ressource demandée et un jeton d’état.Microsoft Graph sends a response containing the requested resource and a state token.

    a. Si une URL nextLink est renvoyée, d’autres pages de données peuvent être récupérées dans la session. L’application continue d’effectuer des requêtes à l’aide de l’URL nextLink pour récupérer toutes les pages de données jusqu’à ce qu’une URL deltaLink soit renvoyée dans la réponse.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. Si une URL deltaLink est renvoyée, il n’existe aucune autre donnée sur l’état de la ressource à renvoyer. Pour les prochaines requêtes, l’application utilise l’URL deltaLink pour connaître les modifications apportées à la ressource.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. Lorsque l’application a besoin de connaître les modifications apportées à la ressource, elle effectue une nouvelle requête à l’aide de l’URL deltaLink reçue à l’étape 2. Cette requête peut être effectuée immédiatement après l’étape 2 ou quand l’application vérifie les modifications apportées.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 renvoie une réponse décrivant les modifications apportées à la ressource depuis la dernière requête, ainsi qu’une URL nextLink ou deltaLink.Microsoft Graph returns a response describing changes to the resource since the previous request, and either a nextLink URL or a deltaLink URL.

Remarque : les ressources stockées dans Azure Active Directory (par exemple, les utilisateurs et groupes) prennent en charge les scénarios « synchroniser à partir de maintenant ».Note: Resources stored in Azure Active Directory (such as users and groups) support "sync from now" scenarios. Vous pouvez ainsi ignorer les étapes 1 et 2 susmentionnées (s’il ne vous intéresse pas de récupérer l’état complet de la ressource) et demandez la dernière URL deltaLink à la place.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. Ajoutez $deltaToken=latest à la fonction delta et la réponse contiendra une URL deltaLink, mais aucune donnée de ressources.Append $deltaToken=latest to the delta function and the response will contain a deltaLink and no resource data.

Jetons d’étatState tokens

Une requête GET effectuée avec la fonction delta comporte toujours une URL spécifiée dans un en-tête de réponse nextLink ou deltaLink. L’URL nextLink inclut un jeton skipToken, tandis que l’URL deltaLink inclut un jeton 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.

Ces jetons sont opaques pour le client. Voici ce que vous devez savoir à leur sujet :These tokens are opaque to the client. The following details are what you need to know about them:

  • Chaque jeton reflète l’état et offre une capture instantanée de la ressource dans cette série de suivi des modifications.Each token reflects the state and represents a snapshot of the resource in that round of change tracking.

  • Les jetons d’état encodent et incluent également d’autres paramètres de requête (tels que $select) spécifiés dans la demande de requête delta initiale. Par conséquent, il n’est pas nécessaire de les répéter dans les demandes de requête delta suivantes.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.

  • Lorsque vous effectuez une requête delta, vous pouvez copier et appliquer l’URL nextLink ou deltaLink dans le prochain appel de la fonction delta, sans inspecter le contenu de l’URL ni son jeton d’état.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.

Paramètres facultatifs de la requêteOptional query parameters

Si un client utilise un paramètre de requête, il doit être indiqué dans la première requête. Microsoft Graph encode automatiquement le paramètre spécifié dans l’URL nextLink ou deltaLink fournie dans la réponse. L’application appelante doit, au préalable, spécifier les paramètres de requête (requis une seule fois). Microsoft Graph ajoute automatiquement les paramètres spécifiés à toutes les demandes ultérieures.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.

Notez les paramètres de requête facultatifs suivants :Note the following regarding optional query parameters:

  • Le paramètre de requête $orderby n’est pas pris en charge pour les requêtes delta.$orderby is not a supported query parameter for delta queries.
  • Ne présupposez pas qu’une séquence spécifique de réponses sera renvoyée par une requête Delta.Do not assume a specific sequence of the responses returned from a delta query. Partez du principe que le même élément peut apparaître n’importe où dans la séquence nextLink et traiter les éléments de votre logique de fusion.Assume that the same group could show up anywhere in the nextLink sequence and handle that in your merge logic.

Les restrictions suivantes s’appliquent à l’utilisation de certains paramètres de requête pour les utilisateurs et les groupes :For users and groups, the following restrictions apply to using using some query parameters:

L’utilisation de certains paramètres de requête est restreinte pour les utilisateurs et les groupes :For users and groups, there are restrictions on using some query parameters:

  • Si le paramètre de requête $select est utilisé, cela signifie que le client préfère suivre uniquement les modifications apportées aux propriétés ou aux relations spécifiées dans la déclaration $select. Si une propriété qui n’est pas sélectionnée est modifiée, la ressource concernée par cette modification n’apparaît pas dans la réponse delta de la requête suivante.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 est uniquement pris en charge pour la propriété de navigation manager et members pour les utilisateurs et les groupes respectivement.$expand is only supported for the manager and members navigational property for users and groups respectively.

  • Les filtres d’étendue vous permettent d’effectuer le suivi des modifications sur un ou plusieurs utilisateurs ou groupes spécifiques par objectId.Scoping filters allow you to track changes to one or more specific users or groups by objectId. Par exemple, la requête suivante : https://graph.microsoft.com/beta/groups/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ae5f' or id eq '004d6a07-fe70-4b92-add5-e6e37b8acd8e' renvoie les modifications des groupes correspondants aux ID spécifiés dans le filtre de requête.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.

Représentation des ressources dans la réponse à la requête deltaResource representation in the delta query response

  • Les nouvelles instances d’une ressource prise en charge sont représentées dans la réponse à la requête delta selon leur représentation standard.Newly created instances of a supported resource are represented in the delta query response using their standard representation.

  • Les instances mises à jour sont représentées par leur id avec au moins les propriétés qui ont été mises à jour, mais d’autres propriétés peuvent être incluses.Updated instances are represented by their id with at least the properties that have been updated, but additional properties may be included.

  • Les relations sur les utilisateurs et les groupes sont représentées par des annotations dans la représentation standard de la ressource. Ces annotations utilisent le format propertyName@delta. Les annotations sont incluses dans la réponse de la demande de requête delta initiale.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.

Les instances supprimées sont représentées par leur id et un objet @removed. L’objet @removed peut également contenir des informations supplémentaires sur la raison de la suppression de l’instance. Par exemple, « @supprimé » : {« motif » : « modifié »}.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”}.

Les raisons possibles de @supprimé peuvent être modifié ou supprimé.Possible @removed reasons can be changed or deleted.

  • Modifié indique que l’élément a été supprimé et peut être restauré à partir de deletedItems.Changed indicates the item was deleted and can be restored from deletedItems.

  • Supprimé indique que l’élément est supprimé et ne peut pas être restauré.Deleted indicates the item is deleted and cannot be restored.

L’objet @removed peut être renvoyé dans la réponse à la requête delta initiale et dans les réponses suivies (deltaLink). Les clients utilisant des requêtes delta doivent être conçus pour traiter ces objets dans les réponses.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.

Ressources prises en chargeSupported resources

La requête delta est actuellement prise en charge pour les ressources suivantes :Delta query is currently supported for the following resources.

Collection de ressourcesResource collection APIAPI
Applications (aperçu)Applications (preview) fonction delta de la ressource d’application (aperçu)delta function of the application resource (preview)
Classes (préversion)Classes (preview) fonction delta de la ressource Class (préversion)delta function of the servicePrincipal resource (preview)
Objets d’annuaire (préversion)Directory objects (preview) fonction delta de la ressource directoryObjects (aperçu)delta function of the directoryObjects resource (preview)
Rôles d’annuaireDirectory roles fonction delta de la ressource directoryRoledelta function of the directoryRole resource
Éléments de lecteur*Drive items* Fonction delta de la ressource driveItemdelta function of the driveItem resource
Utilisateurs éducation (préversion)Education users (preview) fonction delta de la ressource Education user (préversion)delta function of the user resource
Événements dans un affichage Calendrier (plage de dates) du calendrier principalEvents in a calendar view (date range) of the primary calendar Fonction delta de la ressource eventdelta function of the event resource
GroupesGroups Fonction delta de la ressource groupdelta function of the group resource
Dossiers des courriers électroniquesMail folders Fonction delta de la ressource mailFolderdelta function of the mailFolder resource
Messages dans un dossierMessages in a folder Fonction delta de la ressource messagedelta function of the message resource
Dossiers des contacts personnelsPersonal contact folders Fonction delta de la ressource contactFolderdelta function of the contactFolder resource
Contacts personnels dans un dossierPersonal contacts in a folder Fonction delta de la ressource contactdelta function of the contact resource
Établissements scolaires (préversion)Schools (preview) fonction delta de la ressource School (préversion)delta function of the servicePrincipal resource (preview)
Principaux de service (aperçu)Service principals (preview) fonction delta de la ressource servicePrincipal (aperçu)delta function of the servicePrincipal resource (preview)
UsersUsers Fonction delta de la ressource userdelta function of the user resource
Éléments du planificateur** (préversion)Planner items** (preview) fonction delta du segment de la ressource plannerUser (préversion)delta function of the all segment of plannerUser resource (preview)
chatMessages dans un canal (préversion)chatMessages in a channel (preview) Fonction delta de chatMessagedelta function of the contactFolder resource

*Le schéma d’utilisation des ressources OneDrive est semblable à celui des autres ressources prises en charge avec quelques différences de syntaxe mineures.* The usage pattern for OneDrive resources is similar to the other supported resources with some minor syntax differences. La requête delta pour les lecteurs sera prochainement mise à jour pour correspondre aux autres types de ressources.Delta query for drives will be updated in the future to be consistent with other resource types. Pour plus d’informations sur la syntaxe actuelle, voir Suivi des modifications pour un lecteur.For more detail about the current syntax, see Track changes for a drive.

** Le schéma d’utilisation des ressources Planner est plus ou moins semblable à celui des autres ressources prises en charge.** The usage pattern for Planner resources is similar to other supported resources with a few differences. Pour en savoir plus, consultez l’article relatif au suivi des modifications pour le planificateur.For details, see Track changes for Planner.

Conditions préalablesPrerequisites

Les autorisations requises pour lire une ressource spécifique sont également requises pour exécuter la requête delta sur cette ressource.The same permissions that are required to read a specific resource are also required to perform delta query on that resource.

Exemples de requêtes effectuées avec la fonction deltaDelta query request examples