Utiliser la requête delta pour suivre les modifications apportées aux données Microsoft Graph

  • Article

La requête Delta, également appelée suivi des modifications, permet aux applications de découvrir les entités nouvellement créées, mises à jour ou supprimées sans effectuer une lecture complète 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.

L’utilisation de la requête delta vous permet d’éviter d’interroger constamment Microsoft Graph, car l’application demande uniquement les données qui ont changé depuis la dernière requête. Ce modèle permet à l’application de réduire la quantité de données qu’elle demande, ce qui réduit le coût de la requête et, par conséquent, limite probablement les risques de limitation des requêtes.

Utilisation de la requête delta pour suivre les modifications apportées à une collection de ressources

Voici comment se déroule un appel classique :

  1. L’application effectue une requête GET avec la fonction delta sur la ressource souhaitée. Par exemple : GET https://graph.microsoft.com/v1.0/users/delta.

    Conseil

    /delta est un raccourci pour le nom /microsoft.graph.deltacomplet . Les demandes générées par les sdk Microsoft Graph utilisent le nom complet.

  2. Microsoft Graph répond avec la ressource demandée et un jeton d’état.

    a. Si Microsoft Graph retourne une @odata.nextLink URL, il y a plus de pages de données à récupérer dans la session, même si la réponse actuelle contient un résultat vide. L’application utilise l’URL @odata.nextLink pour continuer à effectuer des demandes de récupération de toutes les pages de données jusqu’à ce que Microsoft Graph retourne une @odata.deltaLink URL dans la réponse.

    b. Si Microsoft Graph retourne une @odata.deltaLink URL, il n’y a plus de données sur l’état existant de la ressource à retourner dans la session active. Pour les prochaines requêtes, l’application utilise l’URL @odata.deltaLink pour connaître les modifications apportées à la ressource.

    Remarque

    La réponse Microsoft Graph de l’étape 2 inclut les ressources qui existent actuellement dans la collection. Les ressources qui ont été supprimées avant la requête delta initiale ne sont pas retournées. Les mises à jour effectuées avant la requête initiale sont résumées sur la ressource renvoyée comme état le plus récent.

  3. Lorsque l’application doit en savoir plus sur les modifications apportées à la ressource, elle utilise l’URL @odata.deltaLink qu’elle a reçue à l’étape 2 pour effectuer des demandes. L’application peut effectuer cette demande immédiatement après avoir terminé l’étape 2 ou quand elle recherche des modifications.

  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 @odata.nextLink ou @odata.deltaLink.

Remarque

  • Les ressources stockées dans Microsoft Entra ID (comme les utilisateurs et les groupes) prennent en charge les scénarios de « synchronisation à partir de maintenant ». Vous pouvez ainsi ignorer les étapes 1 et 2 (si vous ne souhaitez pas récupérer l’état complet de la ressource) et demander à la place la dernière URL @odata.deltaLink. Ajoutez $deltatoken=latest à la fonction delta et la réponse contiendra une URL @odata.deltaLink, mais aucune donnée de ressources. Les ressources dans OneDrive et SharePoint prennent également en charge cette fonctionnalité, mais nécessitent token=latest à la place.
  • $selectles paramètres de requête et $deltaLink sont pris en charge pour certaines ressources Microsoft Entra afin que les clients puissent modifier les propriétés qu’ils souhaitent suivre pour un existant@odata.deltaLink. Les requêtes Delta avec $select et $skiptoken ne sont pas prises en charge.

Jetons d’état

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 @odata.nextLink ou @odata.deltaLink. L’URL @odata.nextLink inclut un $skiptoken, et une @odata.deltaLink URL inclut un $deltatoken.

Ces jetons sont opaques pour l’application cliente, mais ils sont importants comme suit :

  • Chaque jeton reflète l’état et offre une capture instantanée de la ressource dans cette série de suivi des modifications.
  • Les jetons d’état encodent et incluent des paramètres de requête (tels que $select) spécifiés dans la requête delta initiale. Par conséquent, ne modifiez pas les requêtes delta suivantes pour répéter ces paramètres de requête.
  • Lorsque vous effectuez une requête delta, vous pouvez copier et appliquer l’URL @odata.nextLink ou @odata.deltaLink dans le prochain appel de la fonction delta, sans inspecter le contenu de l’URL ni son jeton d’état.

Paramètres facultatifs de la requête

Si un client utilise un paramètre de requête, il doit être spécifié dans la demande initiale. Microsoft Graph encode automatiquement le paramètre de requête spécifié dans ou @odata.nextLink@odata.deltaLink dans la réponse et dans toutes les URL ou @odata.deltaLink suivantes@odata.nextLink.

Veuillez noter la prise en charge limitée générale des paramètres de requête facultatifs suivants :

  • $orderby

    Ne supposez pas une séquence spécifique des réponses retournées à partir d’une requête delta. Partez du principe que le même élément peut apparaître n’importe où dans la séquence @odata.nextLink et traitez les éléments de votre logique de fusion.

  • $top

    Le nombre d’objets de chaque page peut varier en fonction du type de ressource et du type de modifications apportées à la ressource.

Pour la ressource demessage, voir les détails relatifs à la requête Delta dans une prise en charge des paramètres de requête.

L’utilisation de certains paramètres de requête est restreinte pour les ressources utilisateurs et groupes :

  • $expand n’est pas pris en charge.

  • $top n’est pas pris en charge.

  • $orderby n’est pas pris en charge.

  • Si un $select paramètre de requête est utilisé, le paramètre indique que le client préfère suivre uniquement les modifications apportées aux propriétés ou relations spécifiées dans l’instruction $select . Si une modification se produit sur une propriété qui n’est pas sélectionnée, la ressource pour laquelle cette propriété a été modifiée n’apparaît pas dans la réponse delta après une requête ultérieure.

  • $select prend également en charge les propriétés de navigation du responsable et des membres pour les utilisateurs et les groupes, respectivement. Sélectionner ces propriétés permet de suivre les modifications apportées aux appartenances aux groupes et gestionnaire d’utilisateur.

  • Les filtres d’étendue vous permettent de suivre les modifications apportées à un ou plusieurs utilisateurs ou groupes spécifiques, en filtrant uniquement par ID d’objet. Par exemple, la requête suivante renvoie les modifications apportées aux groupes correspondant aux ID spécifiés dans le filtre de requête.

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

Représentation des ressources dans la réponse à la requête delta

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

  • Les instances mises à jour sont représentées par leur ID avec au moins les propriétés mises à jour, mais d’autres propriétés peuvent être incluses.

  • Les relations sur les utilisateurs et les groupes sont représentées sous forme d’annotations sur la représentation de ressource standard. Ces annotations utilisent le format propertyName@delta. Les annotations sont incluses dans la réponse de la requête delta initiale.

  • Les instances supprimées sont représentées par leur ID et un objet @removed . L’objet @removed peut inclure des informations supplémentaires sur la raison pour laquelle le instance a été supprimé. Par exemple : "@removed": {"reason": "changed"}. Les raisons possibles de @supprimé peuvent être modifié changed ou deleted.

    • changed indique que l’élément a été supprimé et peut être restauré à partir de deletedItems.

    • deleted indique que l’élément est supprimé et ne peut pas être restauré.

      L’objet @removed peut être retourné dans la réponse de requête delta initiale et dans les réponses suivies (@odata.nextLink). Par exemple, un objet répertoire supprimé qui peut toujours être restauré à partir d’éléments supprimés s’affiche sous la forme "@removed": {"reason": "changed"}. Les clients qui utilisent des requêtes delta doivent être conçus pour gérer ces objets dans les réponses.

  • Les instances restaurées à partir deletedItems s’affichent en tant qu’instances nouvellement créées dans la réponse à la requête delta.

Remarque

Une seule entité peut être contenue plusieurs fois dans la réponse, si cette entité a été modifiée plusieurs fois et sous certaines conditions. Les requêtes Delta permettent à votre application de répertorier toutes les modifications, mais ne garantissent pas l’unification des entités au sein d’une réponse unique.

Ressources prises en charge

La requête delta est actuellement prise en charge pour les ressources suivantes : Certaines ressources disponibles dans la version 1.0 ont leurs fonctions delta correspondantes toujours en préversion status, comme indiqué.

Remarque : La fonction delta pour les ressources marquées d’un astérisque (*) est disponible uniquement sur le point de /beta terminaison.

Collection de ressources API
application application : fonction delta
administrativeUnit administrativeUnit : fonction delta
callRecording * callRecording : fonction delta
callTranscript * callTranscript : fonction delta
chatMessage chatMessage : fonction delta
appareil device : delta , fonction
directoryRole directoryRole : fonction delta
directoryObject directoryObject : fonction delta
driveItem1 driveItem : fonction delta
educationAssignment educationAssignment : fonction delta
educationCategory educationCategory : fonction delta
educationClass educationClass : fonction delta
educationSchool educationSchool : fonction delta
educationUser educationUser : fonction delta
event event : delta , fonction
groupe group : delta, fonction
listItem1 listItem : fonction delta
mailFolder mailFolder : fonction delta
message message : fonction delta
orgContact orgContact : fonction delta
oAuth2PermissionGrant oAuth2PermissionGrant : fonction delta
contactFolder contactFolder : fonction delta
ressource contact contact : fonction delta
plannerBucket * plannerBucket : fonction delta
plannerUser2 plannerUser : fonction delta
sites fonction delta de la ressource de site
servicePrincipal servicePrincipal : fonction delta
todoTask todoTask : fonction delta
todoTaskList todoTaskList : fonction delta
utilisateur user : delta , fonction

Remarque

1 Le modèle d’utilisation des ressources OneDrive et SharePoint est similaire aux autres ressources prises en charge avec quelques différences de syntaxe mineures. Pour plus d’informations sur la syntaxe actuelle, consultez driveItem : delta et listItem : delta.

2 Le modèle d’utilisation des ressources Planificateur est similaire aux autres ressources prises en charge, avec quelques différences. Pour plus d’informations, consultez planificateur : delta.

Clouds nationaux

Les requêtes Delta pour les ressources prises en charge sont disponibles pour les clients hébergés sur le cloud public, Microsoft Cloud for US Government et Microsoft Cloud China gérés par 21Vianet.

Limitations

Les modifications apportées aux propriétés stockées en dehors du magasin de données main ne font pas l’objet d’un suivi

Certaines ressources contiennent des propriétés stockées en dehors du magasin de données main pour la ressource. Par exemple, les données des ressources utilisateur sont principalement stockées dans Microsoft Entra ID, mais certaines de ses propriétés, telles que les compétences, sont stockées dans SharePoint Online. Actuellement, seules les propriétés stockées dans le magasin de données main déclenchent des modifications dans la requête delta ; les propriétés stockées en dehors du magasin de données main ne sont pas prises en charge dans le cadre du suivi des modifications. Par conséquent, une modification de l’une de ces propriétés n’entraîne pas l’affichage d’un objet dans la réponse à la requête delta.

Pour plus d’informations sur les propriétés stockées en dehors du magasin de données main, consultez la documentation sur les utilisateurs et lesgroupes.

Retards de traitement

Attendez-vous à des délais variables entre le moment où une ressource instance change et le moment où la modification suivie est reflétée dans une réponse de requête delta.

Parfois, en raison de retards de réplication, les modifications apportées à l’objet peuvent ne pas apparaître immédiatement lorsque vous sélectionnez ou @odata.nextLink .@odata.deltaLink Réessayez le @odata.nextLink ou @odata.deltaLink après un certain temps pour récupérer les dernières modifications.

Répétitions

Votre demande doit être préparée pour les répétitions, qui se produisent lorsque le même changement apparaît dans les réponses ultérieures. Bien que la requête delta fasse le meilleur effort pour réduire les relectures, elles sont toujours possibles.

Réinitialisation de la synchronisation

La requête Delta peut retourner un code de réponse de 410 Gone et un en-tête Location contenant une URL de requête avec un $deltatoken vide (identique à la requête initiale). Cette status se produit généralement pour empêcher l’incohérence des données en raison de la maintenance interne ou de la migration du locataire cible, et indique que l’application doit redémarrer avec une synchronisation complète du locataire cible.

Durée du jeton

Les jetons Delta ne sont valides que pour une période spécifique avant que l’application cliente ait besoin d’exécuter une nouvelle synchronisation complète.

  • Pour les objets de répertoire, la limite est de sept jours.
  • Pour les objets éducation (educationSchool, educationUseret educationClass), la limite est de 7 jours.
  • Pour les entités Outlook (message, mailFolder, event, contact, contactFolder, todoTask et todoTaskList), la limite supérieure n’est pas fixe . elle dépend de la taille du cache de jeton delta interne. Bien que les nouveaux jetons delta soient ajoutés de façon continue dans le cache, une fois la capacité de cache dépassée, les anciens jetons delta sont supprimés.

Si le jeton expire, le service doit répondre avec une erreur de série 40X avec des codes d’erreur tels que syncStateNotFound. Pour plus d’informations, consultez Codes d’erreur dans Microsoft Graph.

Combiner les notifications de requête delta et de modification

Une application peut utiliser les notifications de modification Microsoft Graph pour s’abonner et recevoir une notification en cas de modification d’une ressource spécifique. L’application peut ensuite utiliser la requête Delta pour demander toutes les modifications apportées depuis la dernière demande.

Les applications peuvent utiliser cette stratégie pour éliminer presque (uniquement pour les ressources prises en charge) la nécessité d’interroger fréquemment Microsoft Graph et de traiter ces modifications pour maintenir une banque de données locale synchronisée, ce qui réduit considérablement les risques de limitation de leurs demandes.

Contenu connexe

Pour en savoir plus sur la requête delta, consultez les didacticiels suivants :