user: deltauser: delta

Récupérez les utilisateurs nouvellement créés, mis à jour ou supprimés sans avoir à effectuer une lecture totale de la collection d’utilisateurs complète.Get newly created, updated, or deleted users without having to perform a full read of the entire user collection. Voir l’article relatif au Suivi des modifications pour plus de détails.See Track changes for details.

AutorisationsPermissions

L’une des autorisations suivantes est nécessaire pour appeler cette API. Pour plus d’informations, notamment sur la façon de choisir les autorisations, voir Autorisations.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Type d’autorisationPermission type Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)Permissions (from least to most privileged)
Déléguée (compte professionnel ou scolaire)Delegated (work or school account) User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Directory.AccessAsUser.AllUser.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Déléguée (compte Microsoft personnel)Delegated (personal Microsoft account) User.Read, User.ReadWriteUser.Read, User.ReadWrite
ApplicationApplication User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.AllUser.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

Requête HTTPHTTP request

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

GET /users/delta

Paramètres de requêteQuery parameters

Le suivi des modifications dans la ressource user entraîne une série d’appels de fonction delta.Tracking changes in users incurs a round of one or more delta function calls. Si vous utilisez un paramètre de requête (autre que $deltatoken et $skiptoken), vous devez le spécifier dans la requête delta initiale.If you use any query parameter (other than $deltatoken and $skiptoken), you must specify it in the initial delta request. Microsoft Graph code automatiquement les paramètres spécifiés dans la partie jeton du nextLink ou de l’URL deltaLink fournie dans la réponse.Microsoft Graph automatically encodes any specified parameters into the token portion of the nextLink or deltaLink URL provided in the response.

Il vous suffit de spécifier les paramètres de requête de votre choix la première fois.You only need to specify any desired query parameters once upfront.

Dans les requêtes suivantes, copiez et appliquez le nextLink ou l’URL deltaLink à partir de la réponse précédente, car cette URL inclut déjà les paramètres codés souhaités.In subsequent requests, copy and apply the nextLink or deltaLink URL from the previous response, as that URL already includes the encoded, desired parameters.

Paramètre de requêteQuery parameter TypeType DescriptionDescription
$deltatoken$deltatoken stringstring Jeton d’état renvoyé dans l’URLdeltaLink de l’appel de fonction delta précédent pour la même collection d’utilisateurs, indiquant la fin de cette série de suivi des modifications. Enregistrez et appliquez l’ensemble de l’URL deltaLink, y compris ce jeton dans la première requête de la série suivante de suivi des modifications pour cette collection.A state token returned in the deltaLink URL of the previous delta function call for the same user collection, indicating the completion of that round of change tracking. Save and apply the entire deltaLink URL including this token in the first request of the next round of change tracking for that collection.
$skiptoken$skiptoken stringstring Jeton d’état renvoyé dans l’URL nextLink de l’appel de fonction delta précédent, indiquant que des modifications supplémentaires doivent être suivies dans la même collection d’utilisateurs.A state token returned in the nextLink URL of the previous delta function call, indicating there are further changes to be tracked in the same user collection.

Paramètres de requête ODataOData query parameters

Cette méthode prend en charge les paramètres de requête OData pour vous aider à personnaliser la réponse.This method supports optional OData Query Parameters to help customize the response.

  • Vous pouvez utiliser un paramètre de requête $select comme dans toute requête GET pour spécifier uniquement les propriétés dont vous avez besoin pour de meilleures performances. La propriété id est toujours renvoyée.You can use a $select query parameter as in any GET request to specify only the properties your need for best performance. The id property is always returned.
  • Pour $filter, la prise en charge est limitée :There is limited support for $filter:
    • La seule expression $filter prise en charge concerne le suivi des modifications sur un objet spécifique : $filter=id+eq+{value}.The only supported $filter expression is for tracking changes on a specific object: $filter=id+eq+{value}. Vous pouvez filtrer plusieurs objets.You can filter multiple objects. Par exemple, https://graph.microsoft.com/v1.0/users/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'.For example, https://graph.microsoft.com/v1.0/users/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'. Une limite est fixée à 50 objets filtrés.There is a limit of 50 filtered objects.

En-têtes de demandeRequest headers

NomName DescriptionDescription
AutorisationAuthorization Jeton <du porteur>Bearer <token>
Content-TypeContent-Type application/jsonapplication/json
PréférencePrefer return=minimal.return=minimal

Spécifiant cet en-tête avec une demande utilisant un deltaLink retourne uniquement les propriétés d’objet qui ont été modifiées depuis la dernière passe.Specifying this header with a request that uses a deltaLink would return only the object properties that have changed since the last round. Facultatif.Optional.

Corps de la demandeRequest body

N’indiquez pas le corps de la demande pour cette méthode.Do not supply a request body for this method.

RéponseResponse

Si elle réussit, cette méthode renvoie un code de réponse 200 OK et un objet de collection user dans le corps de la réponse.If successful, this method returns 200 OK response code and user collection object in the response body. La réponse inclut également une URL nextLink ou une URL deltaLink.The response also includes a nextLink URL or a deltaLink URL.

  • Si une URL nextLink est renvoyée :If a nextLink URL is returned:

    • Cela signifie que d’autres pages de données peuvent être récupérées dans la session.This indicates there are additional pages of data to be retrieved in the session. L’application continue d’effectuer des requêtes à l’aide de l’URL nextLink jusqu’à ce que la réponse contienne une URL deltaLink.The application continues making requests using the nextLink URL until a deltaLink URL is included in the response.
    • La réponse inclut le même ensemble de propriétés que dans la demande de requête delta initiale.The response includes the same set of properties as in the initial delta query request. Cela vous permet de capturer l’état actuel complet des objets lors du lancement de l’exécution du cycle delta.This allows you to capture the full current state of the objects when initiating the delta cycle.
  • Si une URL deltaLink est renvoyée :If a deltaLink URL is returned:

    • Cela signifie qu’il n’existe aucune autre donnée sur l’état de la ressource à renvoyer.This indicates there is no more data about the existing state of the resource to be returned. Enregistrez et utilisez l’URL deltaLink pour étudier comment changer la ressource dans la passe suivante.Save and use the deltaLink URL to learn about changes to the resource in the next round.
    • Pour avez le choix de pouvoir spécifier l’en-tête Prefer:return=minimal à inclure dans les valeurs de réponse uniquement pour les propriétés qui ont été modifiées depuis que le deltaLink a été émis.You have a choice to specify the Prefer:return=minimal header, to include in the response values for only the properties that have changed since the time the deltaLink was issued.

Par défaut : retourne les mêmes propriétés que la requête delta initialeDefault: return the same properties as initial delta request

Par défaut, les requêtes utilisant un deltaLink ou nextLink renvoient les mêmes propriétés sélectionnées dans la requête delta initiale comme suit :By default, requests using a deltaLink or nextLink return the same properties as selected in the initial delta query in the following ways:

  • Si la propriété a changé, la nouvelle valeur est incluse dans la réponse.If the property has changed, the new value is included in the response. Cela inclut les propriétés définies pour la valeur null.This includes properties being set to null value.
  • Si la propriété n’a pas changé, la valeur précédente est incluse dans la réponse.If the property has not changed, the old value is included in the response.
  • Si la propriété n’a jamais été configurée auparavant, elle ne sera pas du tout incluse dans la réponse.If the property has never been set before it will not be included in the response at all.

Remarque : avec ce comportement, en examinant la réponse il n’est pas possible d’indiquer si une propriété change ou non.Note: With this behavior, by looking at the response it is not possible to tell whether a property is changing or not. Par ailleurs, les réponses delta sont généralement de grande taille, car elles contiennent toutes les valeurs de propriété, comme illustré dans l’exemple 2.Also, the delta responses tend to be large because they contain all property values - as shown in the second example below.

En alternative : retourner uniquement les propriétés modifiéesAlternative: return only the changed properties

Ajout d’un en-tête de la demande facultatif ( prefer:return=minimal ) engendre le comportement suivant :Adding an optional request header - prefer:return=minimal - results in the following behavior:

  • Si la propriété a changé, la nouvelle valeur est incluse dans la réponse.If the property has changed, the new value is included in the response. Cela inclut les propriétés définies pour la valeur null.This includes properties being set to null value.
  • Si la propriété n’a pas changé, la propriété n’est pas du tout incluse dans la réponse.If the property has not changed, the property is not included in the response at all. (Différent du comportement par défaut).(Different from the default behavior.)

Remarque : l’en-tête peut être ajouté à une deltaLink requête à tout moment lors du cycle delta.Note: The header can be added to a deltaLink request at any point in time in the delta cycle. L’en-tête n’affecte que l’ensemble des propriétés incluses dans la réponse et n’affecte pas comment la requête delta est exécutée.The header only affects the set of properties included in the response and it does not affect how the delta query is executed. Voir l’exemple 3.See Example 3.

ExemplesExamples

Exemple 1 : propriétés par défautExample 1: Default properties

DemandeRequest

Voici un exemple de demande.The following is an example of the request. Il n’y a pas de paramètre $select, donc un ensemble de propriétés par défaut est suivi et renvoyé.There is no $select parameter, so a default set of properties is tracked and returned.

GET https://graph.microsoft.com/v1.0/users/delta

RéponseResponse

Voici un exemple de la réponse lors de l’utilisation de deltaLink obtenu à partir de l’initialisation de la requête.The following is an example of the response when using deltaLink obtained from the query initialization.

Remarque : il se peut que l’objet de réponse illustré ici soit raccourci pour plus de lisibilité. Toutes les propriétés sont renvoyées à partir d’un appel réel.Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "businessPhones": [
          "businessPhones-value"
      ],
      "displayName": "displayName-value",
      "givenName": "givenName-value",
      "jobTitle": "jobTitle-value",
      "mail": "mail-value",
      "mobilePhone": "mobilePhone-value",
      "officeLocation": "officeLocation-value",
      "preferredLanguage": "preferredLanguage-value",
      "surname": "surname-value",
      "userPrincipalName": "userPrincipalName-value",
      "id": "id-value"
    }
  ]
}

Exemple 2 : sélection de trois propriétésExample 2: Selecting three properties

DemandeRequest

L’exemple suivant montre la requête initiale sélectionnant trois propriétés pour le suivi des modifications, avec le comportement de réponse par défaut.The next example shows the initial request selecting 3 properties for change tracking, with default response behavior:

GET https://graph.microsoft.com/v1.0/users/delta?$select=displayName,jobTitle,mobilePhone

RéponseResponse

Voici un exemple de la réponse lors de l’utilisation de deltaLink obtenu à partir de l’initialisation de la requête.The following is an example of the response when using deltaLink obtained from the query initialization. Notez que les trois propriétés sont incluses dans la réponse et on ne sait pas celles qui ont été modifiées depuis que le deltaLink a été obtenu.Note that all 3 properties are included in the response and it is not known which ones have changed since the deltaLink was obtained.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "displayName-value",
      "jobTitle": "jobTitle-value",
      "mobilePhone": null
    }
  ]
}

Exemple 3 : comportement de réponse minimal alternatifExample 3: Alternative minimal response behavior

DemandeRequest

L’exemple suivant montre la requête initiale sélectionnant trois propriétés pour le suivi des modifications, avec le comportement de réponse minimal alternatif.The next example shows the initial request selecting 3 properties for change tracking, with alternative minimal response behavior:

GET https://graph.microsoft.com/v1.0/users/delta?$select=displayName,jobTitle,mobilePhone
Prefer: return=minimal

RéponseResponse

Voici un exemple de la réponse lors de l’utilisation de deltaLink obtenu à partir de l’initialisation de la requête.The following is an example of the response when using deltaLink obtained from the query initialization. Notez que la propriété mobilePhone n’est pas incluse, ce qui signifie qu’elle n’a pas changé depuis la dernière requête delta ; displayName et jobTitle sont incluses ce qui signifie que leur valeur ont changé.Note that the mobilePhone property is not included, which means it has not changed since the last delta query; displayName and jobTitle are included which means their values have changed.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "displayName-value",
      "jobTitle": null
    }
  ]
}

Voir aussiSee also