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 des 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 : suivre les modifications apportées aux groupes
L’exemple suivant montre une série de demandes pour suivre les modifications apportées aux groupes :
- Une Première requête et réponse
- Une Requête nextLink et réponse
- Une dernière requête nextLink et réponse
- 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 (groupe de sécurité ou suppression définitive d’un groupe Microsoft 365), l’élément contient une annotation :
@removed
avec la valeur ."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 ( Toute l’entreprise ) et contient les deux membres actuels du groupe. sg-HR ne contient pas cette propriété, car le groupe n’a aucun membre.
Requête nextLink
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
Réponse nextLink
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"
}
]
}
]
}
Requête nextLink finale
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
Réponse nextLink finale
Lorsqu’une URL @odata.deltaLink
est retournée, il n’y a plus de données sur l’état existant des objets de 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
et 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"
}
]
}
Requête deltaLink
À 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 modifications sont les suivantes :
- 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
Réponse deltaLink
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"
}
]
}
]
}
Quelques éléments à noter concernant l'exemple de réponse précédent :
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 inchangées sont incluses. Dans l’exemple ci-dessus, la propriété
description
a une nouvelle valeur, alors que la propriétédisplayName
n’a pas changé.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 les 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
- 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...>
]
}
- 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...>
]
}
- 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 les éléments de votre logique de fusion.
Voir aussi
Présentation de la requête delta de Microsoft Graph.