Obtenir des modifications incrémentielles de groupesGet incremental changes for groups

La requête delta vous permet d’effectuer une requête pour des ajouts, suppressions ou mises à jour de groupes, au moyen d’une série d’appels de fonction delta. La requête delta vous permet de découvrir les modifications apportées à des groupes sans avoir à récupérer l’ensemble de groupes entier de Microsoft Graph et de comparer les modifications.Delta query lets you query for additions, deletions, or updates to groups, by way of a series of delta function calls. Delta query enables you discover changes to groups without having to fetch the entire set of groups from Microsoft Graph and compare changes.

Les clients utilisant des groupes de synchronisation avec une collection locale de profils peuvent utiliser la requête delta pour leur synchronisation initiale complète, ainsi que pour les synchronisations incrémentielles futures. En règle générale, un client effectue une première synchronisation complète de tous les groupes dans un client, puis apporte régulièrement des modifications incrémentielles aux groupes.Clients using synchronizing groups with a local profile store can use Delta Query for both their initial full synchronization along with incremental synchronizations in the future. Typically, a client would do an initial full synchronization of all the groups in a tenant, and subsequently, get incremental changes to groups periodically.

Suivi des modifications de groupeTracking group changes

Le suivi des modifications apportées aux groupes correspond généralement à une série de requêtes GET envoyées avec la fonction delta. Vous effectuez une requête GET de façon très semblable à la façon dont vous répertoriez des groupes, sauf que vous incluez les éléments suivants :Tracking group changes is a round of one or more GET requests with the delta function. You make a GET request much like the way you list groups, except that you include the following:

  • La fonction delta.The delta function.
  • Un jeton d’état (deltaToken ou skipToken) issu de l’appel de fonction delta GET précédent.A state token (deltaToken or skipToken) from the previous GET delta function call.

ExempleExample

L’exemple suivant illustre une série de requêtes permettant d’effectuer le suivi des modifications apportées aux groupes :The following example shows a series requests to track changes to groups:

  1. Première requête et réponseInitial request and response
  2. Requête nextLink et réponsenextLink request and response
  3. Requête nextLink finale et réponseFinal nextLink request and response
  4. Requête deltaLink et réponse deltaLinkdeltaLink request and deltaLink response

Première requêteInitial request

Pour commencer le suivi des modifications dans la ressource group, vous effectuez une requête incluant la fonction delta sur la ressource group.To begin tracking changes in the group resource, you make a request including the delta function on the group resource.

Remarques :Note the following:

  • 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.The optional $select query parameter is included in the request to demonstrate how query parameters are automatically included in future requests.
  • 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.The optional $select query parameter is also used to show how group members can be retrieved together with group objects. Cela permet de suivre des modifications d’appartenance, comme lorsque les utilisateurs sont ajoutés à des groupes ou supprimer de ceux-ci.This allows tracking of membership changes, such as when users are added or removed from groups.
  • La première requête n’inclut pas de jeton d’état. Les jetons d’état seront utilisés dans les requêtes suivantes.The initial request does not include a state token. State tokens will be used in subsequent requests.
GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,members

Première réponseInitial response

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.If successful, this method returns 200 OK response code and group collection object in the response body. Si l’ensemble du jeu de groupes est trop volumineux pour tenir dans une réponse, un élément nextLink contenant un jeton état sera également inclus.If the entire set of groups is too large to fit in one response, a nextLink containing a state token will also be included.

Dans cet exemple, un élément nextLink était inclus, et le paramètre de requête $select d’origine est codé dans le jeton d’état.In this example, a nextLink was included; the original $select query parameter is encoded in the state token.

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":"TestGroup1",
      "description":"Employees in test group 1",
      "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":"TestGroup2",
      "description":"Employees in test group 2",
      "id":"ec22655c-8eb2-432a-b4ea-8b8a254bffff"
    }
  ]
}

Remarque : la propriété members@delta est incluse dans le premier objet de groupe (TestGroup1) et contient les deux membres actuels du groupe.Note: The members@delta property is included in the first group object - TestGroup1 - and contains the two current members of the group. TestGroup2 ne contient pas cette propriété, car le groupe ne dispose pas de tous les membres.TestGroup2 does not contain that property because the group does not have any members.

La deuxième demande utilise l’élément nextLink de la réponse précédente, qui contient la valeur skipToken.The second request uses the nextLink from the previous response, which contains the skipToken. Le paramètre $select n’est pas explicitement présent, car il est codé dans le jeton.Notice the $select parameter is not explicitly present as it is encoded in the token.

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

La réponse contient un autre nextLink avec une nouvelle valeur skipToken, ce qui indique que des groupes supplémentaires sont disponibles.The response contains another nextLink with a new skipToken value, which indicates that more groups are available. Vous devez continuer à effectuer des demandes à l’aide de l’URL nextLink jusqu’à ce qu’une URL deltaLink soit renvoyée dans la réponse finale, même si la valeur est une matrice vide (cela peut se produire dans certains cas).You should continue making requests using the nextLink URL until a deltaLink URL is returned in the final response, even if the value is an empty array (this can happen under certain circumstances).

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":"TestGroup3",
      "description":"Employees in test group 3",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "632f6bb2-3ec8-4c1f-9073-0027a8c68593"
               }
      ]
    },
    {
      "displayName":"TestGroup4",
      "description":"Employees in test group 4",
      "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 demande utilise de nouveau la dernière version de nextLink.The third request again uses the latest nextLink.

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

Enfin, l’URL deltaLink est renvoyée, ce qui signifie qu’il n’existe plus aucune donnée pour l’état existant de groupes.Finally, the deltaLink URL is returned, which means there is no more data for the existing state of groups. Pour les demandes futures, l’application utilise les valeurs deltaLink et deltaToken qu’elle contient pour en savoir plus sur les nouvelles modifications apportées à des groupes.For future requests, the application uses the deltaLink and the deltaToken value it contains to learn about new changes to groups.

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":"TestGroup5",
      "description":"Employees in test group 5",
      "id":"bed7f0d4-750e-4e7e-ffff-169002d06fc9"
    },
    {
      "displayName":"TestGroup6",
      "description":"Employees in test group 6",
      "id":"421e797f-9406-ffff-b778-4908421e3505"
    }
  ]
}

À l’aide de l’élément deltaLink de la dernière réponse, vous pourrez obtenir de nouvelles modifications nettes pour des groupes depuis la dernière demande.Using the deltaLink from the last response, you will be able to get net new changes to groups since the last request. Les modifications sont les suivantes :Changes include:

  • Objets de groupe récemment créés.Newly created group objects.
  • Objets de groupe supprimés.Deleted group objects.
  • Objets de groupe pour lesquels une propriété a été modifiée (par exemple, l’élément displayName a été modifié).Group objects for which a property has changed (e.g. displayName has been modified).
  • Objets de groupe pour lesquels les objets de membre ont été ajoutés ou supprimés.Group objects for which member objects have been added or removed.
GET https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw

Si aucune modification n’a eu lieu, un élément deltaLink est renvoyé avec aucun résultat : la propriété value est vide.If no changes have occurred, a deltaLink is returned with no results - the value property is empty. Veillez à remplacer le lien précédent dans l’application par le nouveau à utiliser dans les prochains appels.Make sure to replace the previous link in the application with the new one for use in future calls.

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.If changes have occurred, a collection of changed groups is included. La réponse contient également un élément nextLink (s’il existe plusieurs pages de modifications à récupérer) ou un élément deltaLink.The response also contains either a nextLink - in case there are multiple pages of changes to retrieve - or a deltaLink. Vous devez implémenter le même modèle pour les éléments suivants nextLinks comme avant et conserver le dernier élément deltaLink pour les appels à venir.You should implement the same pattern of following the nextLinks as before and persist the final deltaLink for future calls.

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 :Some things to note about the example response above:

  • 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.The objects are returned with the same set of properties originally specified via the $select query parameter.

  • Les propriétés modifiées et inchangées sont incluses.Both changed and unchanged properties are included. 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.In the example above, the description property has a new value, while the displayName property has not changed.

  • members@delta contient les modifications apportées à l’appartenance.members@delta contains any changes to membership.

    • 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.The first user in the list has been removed from the group - either by removing the membership or by deleting the user object itself. La propriété @removed décrit la situation.The @removed property describes that. Seuls les utilisateurs qui ont été supprimés de manière définitive sont supprimés des groupes.Only users that have been permanently deleted are removed from groups. Les utilisateurs supprimés de manière temporaire conservent leur appartenance au groupe et n’apparaissent pas dans le résultat delta tant qu’ils ne sont pas supprimés définitivement.Users that have been temporary deleted keep their group memberships and will not appear in the delta result until they are permanently deleted. Pour plus d’informations, voir répertoire (éléments supprimés).For details, see directory (deleted items).

    • Le deuxième utilisateur a été ajouté au groupe.The second user has been added to the group.

Parcourir les membres d’un grand groupePaging through members in a large group

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é.The members@delta property is included in group objects by default, when the $select query parameter has not been specified, or when the $select=members parameter is explicitly specified. Pour les groupes avec de nombreux membres, il est possible que tous les membres ne puissent pas rentrer dans une réponse unique. Dans cette section, nous décrivons le modèle que vous devez implémenter pour gérer ces cas.For groups with many members it is possible that all members cannot fit into a single response; in this section we describe the pattern you should implement to handle such cases.

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.Note: This pattern applies to both the initial retrieval of group state as well as to subsequent calls to get delta changes.

Supposons que vous exécutiez la requête delta suivante afin de capturer l’état initial complet des groupes ou pour obtenir par la suite des modifications delta :Let's assume you are executing the following delta query - either to capture the initial full state of groups, or later on to get delta changes:

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 :Microsoft Graph may return a response that contains just one group object, with a large list of members in the members@delta property:

Première pageFirst 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 l’élément nextLink, vous risquez de recevoir à nouveau une réponse contenant le même objet de groupe.When you follow the nextLink you may receive a response again containing the same group object. Les mêmes valeurs de propriété seront renvoyées, mais la propriété members@delta contient désormais une autre liste d’utilisateurs.The same property values will be returned but the members@delta property now contains a different list of users.

Deuxième pageSecond 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.Eventually, the entire member list will be returned in this fashion, and other groups will start showing up in the response.

Nous vous recommandons les meilleures pratiques suivantes pour gérer correctement ce modèle :We recommend the following best practices to correctly handle this pattern:

  • Suivez toujours 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.Always follow nextLink and locally merge each group's state: as you receive responses related to the same group, use them to build the full membership list in your application.
  • Il est préférable de ne pas supposer une séquence de réponses spécifiques.It is best not to assume a specific sequence of the responses. Partez du principe que le même groupe 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.

Voir aussiSee also

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