Obtenir des modifications incrémentielles de groupes

La requête delta dans Microsoft Graph vous permet d’interroger les ajouts, suppressions ou mises à jour des ressources prises en charge. Il est activé par le biais d’une série de demandes delta. Pour les groupes, la requête delta vous permet de découvrir les modifications sans extraire l’ensemble des groupes pour comparer les modifications.

Les clients qui synchronisent des groupes avec un magasin de profils local peuvent utiliser la requête delta pour leur synchronisation complète initiale, ainsi que pour les synchronisations incrémentielles suivantes. En règle générale, un client effectue une synchronisation complète initiale de tous les groupes d’un locataire, puis obtient régulièrement des modifications incrémentielles pour les groupes.

Suivre les modifications apportées aux groupes

Suivez les modifications apportées aux groupes via une ou plusieurs requêtes GET avec la fonction delta. La requête GET est semblable à une requêtegroupes de listes, à l’exception des objets supplémentaires suivants dans l’URL :

  • La fonction delta.
  • Un jeton d’état (deltaToken ou skipToken) issu de l’appel de fonction delta GET précédent.

Exemple de suivi des modifications apportées aux groupes

L’exemple suivant illustre une série de requêtes permettant d’effectuer le suivi des modifications apportées aux groupes :

  1. Première requête et réponse
  2. Requête nextLink et réponse
  3. Requête nextLink finale et réponse
  4. Requête deltaLink et réponse deltaLink

L’exemple suivant montre une série de demandes pour suivre les modifications apportées aux groupes :

  1. Une Première requête et réponse
  2. Une Requête nextLink et réponse
  3. Une dernière requête nextLink et réponse
  4. Une demande deltaLink et réponse deltaLink

Prenez note des éléments suivants dans les réponses :

  • Lorsqu’un groupe est supprimé (groupes Microsoft 365), l’élément contient une annotation : @removed avec la valeur de "reason": "changed".
  • Lorsque le groupe est supprimé définitivement (un groupe de sécurité ou supprimer définitivement un groupe Microsoft 365), l’élément contient une annotation : @removed avec la valeur de "reason": "deleted".
  • Lorsque le groupe est créé ou restauré, il n’y a pas d’annotation.

Première requête

Pour suivre les modifications apportées à la ressource de groupe, effectuez une requête et incluez la fonction delta en tant que segment d’URL.

Prenez note des éléments suivants :

  • Le paramètre de requête $select facultatif est inclus dans la requête pour montrer comment les paramètres de requête sont inclus automatiquement dans les futures requêtes.
  • Le paramètre de requête $select facultatif permet également d’indiquer la manière dont les membres du groupe peuvent être récupérés avec les objets de groupe. Cela permet de suivre des modifications d’appartenance, comme lorsque les utilisateurs sont ajoutés à des groupes ou supprimer de ceux-ci.
  • La demande initiale n’inclut pas de jeton d’état. Les jetons d’état seront utilisés dans les requêtes suivantes.
GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,members

Première réponse

Si elle réussit, cette méthode renvoie un code de réponse 200 OK et un objet de collection group dans le corps de la réponse. Si l’ensemble du jeu de groupes est trop volumineux pour tenir dans une réponse, un élément @odata.nextLink contenant un jeton état sera également inclus.

Dans cet exemple, un élément @odata.nextLink était inclus, et le paramètre de requête $select d’origine est codé dans le jeton d’état.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups(displayName,description)",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ",
  "value": [
    {
      "displayName":"All Company",
      "description":"This is the default group for everyone in the network",
      "id":"c2f798fd-f95d-4623-8824-63aec21fffff",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "693acd06-2877-4339-8ade-b704261fe7a0"
               },
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "49320844-be99-4164-8167-87ff5d047ace"
               }
      ]
    },
    {
      "displayName":"sg-HR",
      "description":"All HR personnel",
      "id":"ec22655c-8eb2-432a-b4ea-8b8a254bffff"
    }
  ]
}

Remarque : la propriété members@delta est incluse dans le premier objet de groupe ( Toutes les entreprises) et contient les deux membres actuels du groupe. sg-HR ne contient pas cette propriété, car le groupe n’a aucun membre.

La deuxième demande utilise l’élément @odata.nextLink de la réponse précédente, qui contient la valeur skipToken. Notez que le paramètre $select n’est pas visiblement présent, car il est encodé et inclus dans le jeton.

GET https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ

La réponse contient un autre @odata.nextLink avec une nouvelle valeur de skipToken , ce qui indique que d’autres modifications suivies pour les groupes sont disponibles. Utilisez l’URL @odata.nextLink dans d’autres requêtes jusqu’à ce qu’une URL de @odata.deltaLink (dans un paramètre @odata.deltaLink ) soit retournée dans la réponse finale, même si la valeur est un tableau vide.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7",
  "value": [
    {
      "displayName":"Mark 8 Project Team",
      "description":"Mark 8 Project Team",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "632f6bb2-3ec8-4c1f-9073-0027a8c68593"
               }
      ]
    },
    {
      "displayName":"Sales and Marketing",
      "description":"Sales and Marketing",
      "id":"421e797f-9406-4934-b778-4908421e3505",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "3c8ac7c4-d365-4df9-abfa-356a9dd7763c"
               },
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "49320844-be99-4164-8167-87ff5d047ace"
               }
      ]
    }
  ]
}

La troisième requête utilise la dernière @odata.nextLink retournée par la dernière demande de synchronisation.

GET https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7

Lorsqu’une URL @odata.deltaLink est retournée, il n’y a plus de données sur l’état existant des objets groupe. Pour les demandes ultérieures, l’application utilise l’URL @odata.deltaLink pour en savoir plus sur les autres modifications apportées aux groupes. Enregistrez le deltaToken, puis utilisez-le dans l’URL de requête suivante pour découvrir d’autres modifications apportées aux groupes.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": [
    {
      "displayName":"All Employees",
      "id":"bed7f0d4-750e-4e7e-ffff-169002d06fc9"
    },
    {
      "displayName":"Remote living",
      "description":"Remote living",
      "id":"421e797f-9406-ffff-b778-4908421e3505"
    }
  ]
}

À l’aide du @odata.deltaLink de la dernière réponse, vous obtiendrez des modifications (ajouts, suppressions ou mises à jour) des groupes depuis la dernière requête. Les changements incluent ce qui suit :

  • Objets de groupe récemment créés.
  • Objets de groupe supprimés.
  • Objets de groupe pour lesquels une propriété a changé (par exemple, displayName a été modifié).
  • Objets de groupe pour lesquels les objets de membre ont été ajoutés ou supprimés.
GET https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw

Si aucune modification n’a eu lieu, un @odata.deltaLink est retourné sans résultat : la propriété valeur est un tableau vide. Veillez à remplacer le lien précédent dans l’application par le nouveau à utiliser dans les prochains appels.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": []
}

Si des modifications ont eu lieu, une collection de groupes modifiés est incluse. La réponse contient également un élément @odata.nextLink (s’il existe plusieurs pages de modifications à récupérer) ou un élément @odata.deltaLink. Implémentez le même modèle de suivi du @odata.nextLink et conservez le @odata.deltaLink final pour les appels futurs.

Remarque : Cette demande peut avoir des retards de réplication pour les groupes qui ont été récemment créés, mis à jour ou supprimés. Réessayez le @odata.nextLink ou @odata.deltaLink après un certain temps pour récupérer les dernières modifications.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": [
          {
              "displayName": "TestGroup3",
              "description": "A test group for change tracking",
              "id": "2e5807ce-58f3-4a94-9b37-ffff2e085957",
              "members@delta": [
                  {
                      "@odata.type": "#microsoft.graph.user",
                      "id": "632f6bb2-3ec8-4c1f-9073-0027a8c6859",
                      "@removed": {
                          "reason": "deleted"
                      }
                  },
                  {
                      "@odata.type": "#microsoft.graph.user",
                      "id": "37de1ae3-408f-4702-8636-20824abda004"
                  }
              ]
          }
      ]
}

Éléments à prendre en compte concernant l’exemple de réponse ci-dessus :

  • Les objets sont renvoyés avec le même jeu de propriétés spécifié à l’origine via le paramètre de requête $select.

  • Les propriétés modifiées et non modifiées sont incluses. Dans l’exemple ci-dessus, la propriété description a une nouvelle valeur, tandis que la propriété displayName n’a pas été modifiée.

  • members@delta contient les modifications suivantes apportées à l’appartenance au groupe.

    • Le premier utilisateur de la liste a été supprimé du groupe via la suppression de l’appartenance ou la suppression de l’objet utilisateur lui-même. La propriété @removed décrit la situation. Seuls les utilisateurs qui ont été supprimés de manière définitive sont supprimés des groupes. Les utilisateurs qui ont été supprimés temporairement conservent leurs appartenances aux groupes et n’apparaissent pas dans le résultat delta tant qu’ils ne sont pas définitivement supprimés. Pour plus d’informations, voir répertoire (éléments supprimés).

    • Le deuxième utilisateur a été ajouté au groupe.

Parcourir les membres d’un grand groupe

La propriété members@delta est incluse dans les objets de groupe par défaut, lorsque le paramètre de requête $select n’a pas été spécifié ou lorsque le paramètre $select=members est explicitement spécifié. Pour les groupes comportant de nombreux membres, il est possible que tous les membres ne puissent pas tenir dans une réponse unique. Implémentez le modèle suivant pour gérer de tels cas.

Remarque : ce modèle s’applique à la récupération initiale de l’état du groupe ainsi qu’aux appels suivants pour obtenir des modifications delta.

Supposons que vous exécutez la requête delta suivante , soit pour capturer l’état complet initial des groupes, soit ultérieurement pour obtenir les modifications delta :

GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,members
  1. Microsoft Graph peut retourner une réponse qui contient un objet de groupe uniquement, avec une liste importante de membres dans la propriété members@delta :

Première page

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=<...>",
  "value": [
    {
      "displayName":"LargeGroup",
      "description":"A group containing thousands of users",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "632f6bb2-3ec8-4c1f-9073-0027a8c6859",
              "@removed": {
                  "reason": "deleted"
              }
          },
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "37de1ae3-408f-4702-8636-20824abda004"
          },
          <...more users here...>
      ]
    }
    <...no more groups included - this group filled out the entire response...>
  ]
}
  1. Lorsque vous suivez la @odata.nextLink, vous pouvez recevoir une réponse contenant le même objet de groupe. Les mêmes valeurs de propriété seront renvoyées, mais la propriété members@delta contient désormais une autre liste d’utilisateurs.

Deuxième page

HTTP/1.1 200 OK
Content-type: application/json
{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=<...>",
  "value": [
    {
      "displayName":"LargeGroup",
      "description":"A group containing thousands of users",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "c08a463b-7b8a-40a4-aa31-f9bf690b9551",
              "@removed": {
                  "reason": "deleted"
              }
          },
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "23423fa6-821e-44b2-aae4-d039d33884c2"
          },
          <...more users here...>
      ]
    }
    <...no more groups included - this group filled out the entire response...>
  ]
}
  1. Finalement, la liste entière des membres sera renvoyée de cette façon, et d’autres groupes commenceront à s’afficher dans la réponse.

Nous vous recommandons les meilleures pratiques suivantes pour gérer correctement ce modèle :

  • Suivez toujours @odata.nextLink et fusionnez localement chaque état de groupe : lorsque vous recevez des réponses liées au même groupe, utilisez-les pour créer la liste complète d’appartenance dans votre application.
  • Ne supposez pas une séquence spécifique des réponses. Partez du principe que le même groupe peut apparaître n’importe où dans la séquence @odata.nextLink et traiter cela dans votre logique de fusion.

Voir aussi

Présentation de la requête delta de Microsoft Graph.