Table of contents

Requête différentielle | Concepts de l’API GraphDifferential query | Graph API concepts

Jimaco Brannian|Dernière mise à jour: 19/06/2018
|
2 Collaborateurs

S’applique à : API Graph | Azure Active DirectoryApplies to: Graph API | Azure Active Directory

Cette rubrique traite de la fonctionnalité de requête différentielle de l’API Azure AD Graph.This topic discusses the differential query feature of Azure AD Graph API.Une demande de requête différentielle retourne toutes les modifications apportées aux entités spécifiées pendant l’intervalle entre deux demandes consécutives.A differential query request returns all changes made to specified entities during the time between two consecutive requests.Par exemple, si vous effectuez une demande de requête différentielle une heure après la précédente demande, seules les modifications apportées pendant cette heure sont retournées.For example, if you make a differential query request an hour after the previous differential query request, only the changes made during that hour will be returned.Cette fonctionnalité est particulièrement utile lors de la synchronisation des données d’annuaire du locataire avec le magasin de données d’une application.This functionality is especially useful when synchronizing tenant directory data with an application’s data store.

Pour effectuer une demande de requête différentielle dans l’annuaire d’un locataire, votre application doit y être autorisée par le locataire.To make a differential query request to a tenant’s directory, your application must be authorized by the tenant.Pour plus d’informations, consultez Intégration d’applications à Azure Active Directory.For more information, see Integrating Applications with Azure Active Directory.

Important

Nous vous recommandons fortement d’utiliser Microsoft Graph plutôt que l’API Graph Azure AD pour accéder aux ressources Azure Active Directory.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.Nos efforts de développement sont désormais axés sur Microsoft Graph et aucune autre amélioration n’est prévue pour l’API Graph Azure AD.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.Il existe un nombre très limité de scénarios pour lesquels l’API Graph Azure AD peut être encore appropriée ; pour plus d’informations, consultez le billet de blog Microsoft Graph ou l’API Azure AD dans le Centre de développement Office.There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

Demandes de requêtes différentielles Differential query requests

Cette section décrit les demandes de requêtes différentielles.This section describes differential query requests.Toutes les demandes nécessitent les composants suivants :All requests require the following components:

  • une URL de demande valide, y compris le point de terminaison Graph pour le locataire et les paramètres de chaîne de requête applicables ;A valid request URL, including the Graph endpoint for the tenant and applicable query string parameters.

  • un en-tête d’autorisation incluant un jeton d’accès valide émis par Azure Active Directory.An authorization header, including a valid access token issued by Azure Active Directory.Pour plus d’informations sur l’authentification auprès de l’API Graph, consultez Scénarios d’authentification pour Azure AD.For more information on authenticating to the Graph API, see Authentication Scenarios for Azure AD.

URL de demande de requête différentielleDifferential query request URL

Le code suivant illustre le format de l’URL pour la demande de requête différentielle ; des crochets [] indiquent des éléments facultatifs.The following shows the format of the URL for differential query request; square brackets [] indicate optional elements.

https://graph.windows.net/<tenantId>/<resourceSet>?api-version=<SupportedApiVersion>&deltaLink=<token>&[$filter=isof(<entityType>)]&[$select=<PropertyList>]

L’URL est constituée de segments hiérarchiques suivis par une série de paramètres de chaîne de requête exprimés sous la forme de paires clé-valeur.The URL is made up of a hierarchical segments followed by a series of query string parameters expressed as key-value pairs.

URL : segments hiérarchiquesURL: Hierarchical segments

SegmentSegmentDescriptionDescription
ID_locatairetenantIdIdentificateur unique du locataire sur lequel la requête doit être exécutée.The unique identifier of the tenant that the query should be executed against.Il s’agit généralement de l’un des domaines vérifiés (propriété verifiedDomains) du locataire, mais il peut également s’agir de l’ID d’objet du locataire (propriété objectId).This is typically one of the verified domains (verifiedDomains property) of the tenant, but it can also be the tenant’s object ID (objectId property).Ne respecte pas la casse.Not case-sensitive.
Ensemble_ressourcesresourceSetEnsemble spécifique de ressources des locataires sur lequel cette requête doit être exécutée.The specific set of tenant resources this query should be executed against.Détermine les ressources qui sont retournées dans la réponse de la requête.Determines what resources are returned in the query response.Les valeurs prises en charge sont : « directoryObjects », « users », « contacts » ou « groups ».Supported values are: “directoryObjects”, “users”, “contacts” or “groups”.Les valeurs respectent la casse.Values are case-sensitive.

URL : paramètres de chaîne de requêteURL: Query string parameters

ParamètreParameterDescriptionDescription
api-versionapi-versionIndique la version de l’API Graph pour laquelle la demande est émise.Specifies the version of the Graph API against which the request is issued.Obligatoire.Required.Depuis la version 1.5, la valeur est exprimée sous la forme d’un numéro de version numérique ; par exemple, api-version = 1.5.Beginning with version 1.5, the value is expressed as a numeric version number; for example, api-version=1.5.Pour les versions précédentes, la valeur est une chaîne sous la forme AAAA-MM-JJ, par exemple, api-version = 2013-04-05.For previous versions, the value is a string of the form YYYY-MM-DD; for example, api-version=2013-04-05.

(Remplace l’utilisation de l’en-tête x-ms-dirapi-data-contract-version dans la version d’évaluation de l’API Graph.)(Replaces the use of x-ms-dirapi-data-contract-version header in the preview version of Graph API.)
deltaLinkdeltaLinkJeton retourné dans la propriété deltaLink ou nextLink dans la dernière réponse.The token returned in either the deltaLink property or the nextLink property in the last response.Obligatoire, mais vide pour la première demande.Required, but will be empty on the first request.

(Remplace le paramètre de chaîne de requête skipToken dans la version d’évaluation de l’API Graph.)(Replaces the skipToken query string parameter in the preview version of Graph API.)
$filter$filterIndique les types d’entités à inclure dans la réponse.Indicates which entity types should be included in the response.Facultatif.Optional.Les types d’entités pris en charge sont Utilisateur, Groupe et Contact.The supported entity types are: User, Group and Contact.Valide uniquement quand <Ensemble_ressources> a la valeur « directoryObjects » ; sinon, <Ensemble_ressources> remplace le filtre.Only valid when &ltresourceSet&gt is “directoryObjects”; otherwise, &ltresourceSet&gt overrides the filter.Par exemple, si <Ensemble_ressources> a la valeur « users » et que le paramètre $filter est également spécifié, seules les modifications pour les utilisateurs sont retournées quelle que soit la valeur de filtre.For example, if &ltresourceSet&gt is “users”, and the $filter parameter is also specified, only changes for users will be returned regardless of what is specified in the filter value.Si <Ensemble_ressources> a la valeur « directoryObjects » et que le paramètre $filter n’est pas spécifié, les modifications pour tous les types d’entités pris en charge (Utilisateur, Groupe et Contact) sont retournées.If &ltresourceSet&gt is “directoryObjects” and $filter is not specified, changes for all of the supported entity types (User, Group, and Contact) are returned.

Pour spécifier un seul type d’entité, utilisez l’une des chaînes suivantes :To specify a single entity type, use one of the following:
  • $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')
  • $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')
  • $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Group')
Pour spécifier plusieurs types d’entités, utilisez l’opérateur or ; par exemple, $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group').To specify multiple entity types, use the or operator; for example, $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group').

(Remplace le paramètre de chaîne de requête objectScope dans la version d’évaluation de l’API Graph.)(Replaces the objectScope query string parameter in the preview version of Graph API.)

Important À partir de la version 1.5, l’espace de noms API Graph Microsoft.WindowsAzure.ActiveDirectory devient Microsoft.DirectoryServices.Important Beginning with version 1.5, the Graph API namespace is changed from Microsoft.WindowsAzure.ActiveDirectory to Microsoft.DirectoryServices.Les versions antérieures de l’API Graph continuent à utiliser l’ancien espace de noms ; par exemple, $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact').Earlier versions of the Graph API continue to use the previous namespace; for example, $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact').
$select$selectIndique les propriétés qui doivent être incluses dans la réponse.Specifies which properties should be included in the response.Si *$select^ n’est pas spécifié, toutes les propriétés sont incluses.If *$select^ is not specified, all properties are included.

Les propriétés peuvent être indiquées comme entièrement qualifiées ou non qualifiées.Properties can be specified either fully qualified or non-qualified.Plusieurs propriétés sont délimitées par des virgules.Multiple properties are delimited by commas.
  • Le type d’entité est spécifié pour les propriétés complètes, par exemple User/displayName.Fully qualified properties have the entity type specified; for example, User/displayName.Les propriétés complètes doivent être utilisées si &ltresourceSet&gt est égal à « directoryObjects » ; par exemple, https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=&$select=User/displayName,Group/description.Fully qualified properties MUST be used if &ltresourceSet&gt is specified as “directoryObjects”; for example, https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=&$select=User/displayName,Group/description.
  • Le type d’entité n’est pas spécifié pour les propriétés non qualifiées, par exemple displayName.Non-qualified properties do not have the entity type specified; for example, displayName.Elles peuvent être utilisées uniquement lorsque &ltresourceSet&gt est différent de « directoryObjects » ; par exemple, https://graph.windows.net/contoso.com/users?api-version=2013-04-05&deltaLink=&$select=displayName,jobTitle.They can only be used when &ltresourceSet&gt is specified as a value other than “directoryObjects”; for example, https://graph.windows.net/contoso.com/users?api-version=2013-04-05&deltaLink=&$select=displayName,jobTitle.

Remarque : les paires clé-valeur dans la chaîne de requête respectent la casse, mais leur ordre n’est pas important.Note: The key-value pairs in the query string are case-sensitive, but their order is not significant.

Voici un exemple de requête différentielle simple.The following is an example of the simplest differential query.Elle est utilisée pendant la synchronisation initiale.This is used during initial sync.

https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=

Voici un exemple de demande ultérieure.The following is an example of a subsequent request.

https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U`

Réponses de requêtes différentielles Differential query responses

Cette section décrit le contenu d’une réponse de requête différentielle qui est retournée quand une demande de requête différentielle est effectuée.This section describes the contents of a differential query response that is returned when a differential query request is made.La liste suivante décrit le contenu d’une réponse :The following list describes the contents of a response:

  • Zéro à 200 entités DirectoryObject, chacune contenant des modifications pour un objet User, Group ou Contactspécifique.Zero to 200 DirectoryObject entities, each of which contains changes for a specific User, Group, or Contact object.

  • Zéro à 3000 entités DirectoryLinkChange, chacune contenant des modifications pour un lien membre ou gestionnaire spécifique.Zero to 3000 DirectoryLinkChange entities, each of which contains changes for a specific member or manager link.

  • PropriétédeltaLink ou nextLink.Either a deltaLink or a nextLink property.Dans les deux cas, sa valeur est une chaîne encodée dans une URL qui respecte la casse et incorpore des informations d’état sur l’ensemble des modifications d’annuaire qui ont été retournées au client, en ce qui concerne les modifications restantes qui se sont produites dans l’annuaire.In either case, its value is a case-sensitive, URL-encoded string that embeds state information about the set of directory changes that have been returned to the client, with respect to remaining changes that have occurred in the directory.Cette chaîne (ou ce jeton) doit figurer dans le paramètre de chaîne de requête deltaLink de la demande de requête différentielle suivante.This string (or token) should be included in the deltaLink query string parameter in the next differential query request.

    • Si la propriété deltaLink est retournée, il ne reste plus de modifications d’annuaire pour l’application à synchroniser après cette réponse.If the deltaLink property is returned, there are no more directory changes left for the application to synchronize after this response.L’application peut attendre pendant une période prédéterminée en fonction de ses propres exigences avant d’émettre la demande de requête différentielle suivante.The application can wait for some predetermined time according to its own requirements to issue the next differential query request.

    • Si la propriété nextLink est retournée, il reste des modifications d’annuaire pour l’application à synchroniser après cette réponse.If the nextLink property is returned, there are directory changes remaining for the application to synchronize after this response.L’application doit émettre la demande de requête différentielle suivante dès que possible.The application should issue the next differential query request at its earliest convenience.

Les réponses sont toujours retournées au format JSON.Responses are always returned in JSON format.

Éléments à prendre en compte en cas d’utilisation d’une requête différentielle Considerations when using differential query

La liste suivante présente des éléments importants à prendre en compte pour les applications qui utilisent une requête différentielle :The following list highlights important considerations for applications that use differential query:

  • Les modifications retournées par une requête différentielle représentent l’état des objets d’annuaire au moment de la réponse.Changes returned by differential query represent the state of the directory objects at the time of the response.Votre application ne doit pas traiter ces modifications comme des journaux des transactions pour une relecture.Your application must not treat these changes as transaction logs for replay.

  • Les modifications s’affichent dans l’ordre dans lequel elles se sont produites.Changes appear in the order in which they occurred.Les objets modifiés le plus récemment s’affichent en dernier même si l’objet a été mis à jour plusieurs fois.The most-recently changed objects appear last even if the object was updated multiple times.Leur ordre n’est pas non plus affecté par le moment où le client a reçu les modifications.Their order is also not affected by when the client received the changes.Par conséquent, il est possible que les modifications se présentent en désordre par rapport à la façon dont elles se sont initialement produites dans l’annuaire.As a result, it is possible for changes to be presented out of order compared to how they initially occurred in the directory.

  • Votre application doit être préparée pour les relectures, qui ont lieu quand la même modification apparaît dans les réponses suivantes.Your application must be prepared for replays, which occur when the same change appears in subsequent responses.Même si une requête différentielle essaie au maximum de réduire les relectures, elles sont toujours possibles.While differential query makes a best effort to reduce replays, they are still possible.

  • Votre application doit être prête à gérer un changement de suppression d’objet dont elle n’était pas informée.Your application must be prepared to handle a deletion change for an object it was not aware of.

  • Une requête différentielle peut retourner un lien vers un objet source ou cible qui n’a pas encore été retourné par d’autres réponses.Differential query can return a link to a source or target object that has not yet been returned by other responses.

  • Pour plus d’informations sur l’utilisation d’en-têtes de requête pour limiter vos requêtes afin d’améliorer les performances, consultez la section Autres fonctionnalités de requête différentielle ci-dessous.See the Additional differential query features section below for more information on using request headers to constrain your queries to improve performance.

Exemples de demandes et de réponses Request and response examples

Voici un exemple de demande de requête différentielle initiale :The following is an example of an initial differential query request:

GET https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')&deltaLink= HTTP /1.1
Authorization: Bearer eyJ0eXAiOiJKV . . . KUAe1EQ
Host: graph.windows.net

Voici un exemple de demande de requête différentielle incrémentielle :The following is an example of an incremental differential query request:

https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U
 HTTP /1.1
Authorization: Bearer eyJ0eXAiOiJKV . . . KUAe1EQ
Host: graph.windows.net

Remarque : dans ces deux exemples de demandes, le paramètre de requête $filter est illustré à des fins de démonstration uniquement.Note: In both of these sample requests, the $filter query parameter is shown for demonstration purposes only.Comme le filtre spécifie tous les types de cibles possibles pour la requête différentielle (Utilisateur, Groupe et Contact), il peut être omis et la requête retourne alors des modifications pour tous ces types d’entités par défaut.Because the filter specifies all of the possible target types for the differential query (User, Group, and Contact), it could be omitted and the query would return changes for all of these entity types by default.

L’exemple de réponse suivant illustre l’objet JSON retourné :The following example response demonstrates the returned JSON:

{
  "odata.metadata": "https://graph.windows.net/contoso.com/$metadata#directoryObjects",


  # This is the deltaLink to be used for the next query
  "aad.deltaLink": "https://graph.windows.net/contoso.com/directoryObjects?deltaLink=XARBN7ivjcS6QIhSZDQR3OkT15SO1eeY-01BZSS0sOct6sh5oEyqOLLKRVhRmBMLHhePUF... [Truncated]",
  "value": [

    # User object for John Smith
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.User",
      "objectType": "User",
      "objectId": "dca803ab-bf26-4753-bf20-e1c56a9c34e2",
      "accountEnabled": true,
      "displayName": "John Smith",
      "givenName": "John",
      "mailNickname": "johnsmith",
      "passwordPolicies": "None",
      "surname": "Smith",
      "usageLocation": "US",
      "userPrincipalName": "johnsmith@contoso.com"
    },

    # Group object for IT Administrators
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.Group",
      "objectType": "Group",
      "objectId": "7373b0af-d462-406e-ad26-f2bc96d823d8",
      "description": "IT Administrators",
      "displayName": "Administrators",
      "mailNickname": "Administrators",
      "mailEnabled": false,
      "securityEnabled": true
    },

    # Contact object for Jane Smith
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.Contact",
      "objectType": "Contact",
      "objectId": "d711a1f8-21cf-4dc0-834a-5583e5324c44",
      "displayName": "Jane Smith",
      "givenName": "Jane",
      "mail": "johnsmith@contoso.com",
      "mailNickname": "johnsmith",
      "proxyAddresses": [
        "SMTP:janesmith@fabrikam.com"
      ],
      "surname": "Smith"
    },

    # Member link indicating John Smith is a member of IT Admin Group
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.DirectoryLinkChange",
      "objectType": "DirectoryLinkChange",
      "objectId": "00000000-0000-0000-0000-000000000000",
      "associationType": "Member",
      "sourceObjectId": "7373b0af-d462-406e-ad26-f2bc96d823d8",
      "sourceObjectType": "Group",
      "sourceObjectUri": "https://graph.windows.net/contoso.com/groups/7373b0af-d462-406e-ad26-f2bc96d823d8",
      "targetObjectId": "dca803ab-bf26-4753-bf20-e1c56a9c34e2",
      "targetObjectType": "User",
      "targetObjectUri": "https://graph.windows.net/contoso.com/users/dca803ab-bf26-4753-bf20-e1c56a9c34e2"
    }
  ]
}

Autres fonctionnalités des requêtes différentielles Additional differential query features

Les requêtes différentielles peuvent maintenant retourner uniquement les propriétés et les liens mis à jour, ce qui permet un traitement plus rapide et une réduction des charges pour les appels de requête différentielle.Differential Queries can now return only updated properties and links – this allows faster processing and reduced payloads for Differential Query calls.Cette option est activée en définissant l’en-tête ocp-aad-dq-include-only-changed-properties sur « true » comme indiqué dans cet exemple.This option is enabled by setting the header ocp-aad-dq-include-only-changed-properties to true as shown in this example.

GET https://graph.windows.net/contoso.com/users?api-version=2013-11-08&deltaLink= furK18V1T….
HTTP /1.1
ocp-aad-dq-include-only-changed-properties : true
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5nl0aEV1T….
Response: 200 OK

Par exemple, si seule la propriété « displayName » de l’utilisateur a changé.For example if only the “displayName” property of user has changed.L’objet retourné ressemble alors à ceci :The returned object would be similar to this:

{     
          "displayName" : "AnUpdatedDisplayName",
         "objectId" :  "c1bf5c59-7974-4aff-a59a-f8dfe9809b18",
         "objectType" :  "User",
          "odata.type" :  "Microsoft.WindowsAzure.ActiveDirectory.User"
},

Prise en charge de la synchronisation différentielle pour synchroniser à partir de « maintenant »  : un en-tête spécial peut être spécifié, demandant à obtenir uniquement un jeton deltaToken à jour ; ce jeton peut être utilisé dans les requêtes suivantes, qui retournent uniquement les modifications à partir de « maintenant ».Differential Sync support to sync from “now” - a special header can be specified, requesting to only get an up-to-date deltaToken, this token can be used in subsequent queries, which will return only changes from “now”.Voici l’exemple d’appel :Here’s the example call:

GET https://graph.windows.net/contoso.com/users?api-version=2013-11-08&deltaLink= smLYT8V1T…
HTTP /1.1
ocp-aad-dq-include-only-delta-token: true
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5nl0aEV1T….
Response: 200 OK

La réponse, illustrée ci-après, contient le paramètre deltaLink, mais pas les objets modifiés :The response will contain the deltaLink, but will not have the changed object(s), similar to this:

{   …  "aad.deltaLink":https://graph.windows.net/contoso.com/users?deltaLink=MRa43......   }

Détection d’un élément supprimé : la réponse peut également être utilisée pour détecter un élément supprimé.Detecting a deleted item – the response can also be used to detect a deleted item.Les objets et liens supprimés sont indiqués par la propriété « aad.isDeleted » définie sur true. Ainsi, les applications peuvent obtenir des informations sur la suppression d’objets et de liens créés précédemment.Deleted objects and deleted links are indicated by the "aad.isDeleted" property with a value set to true; this is necessary to make sure applications can learn about the deletion of previously created objects and links.

Ressources supplémentaires Additional resources

© 2018 Microsoft