Requête différentielle | Concepts de l’API Graph
S’applique à : API Graph | Azure Active Directory
Cette rubrique traite de la fonctionnalité de requête différentielle de l’API Azure AD Graph. 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. 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. 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.
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. Pour plus d’informations, consultez Intégration d’applications à 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. 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. 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.
Demandes de requêtes différentielles
Cette section décrit les demandes de requêtes différentielles. Toutes les demandes nécessitent les composants suivants :
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 ;
un en-tête d’autorisation incluant un jeton d’accès valide émis par Azure Active Directory. Pour plus d’informations sur l’authentification auprès de l’API Graph, consultez Scénarios d’authentification pour Azure AD.
URL de demande de requête différentielle
Le code suivant illustre le format de l’URL pour la demande de requête différentielle ; des crochets [] indiquent des éléments facultatifs.
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.
URL : segments hiérarchiques
| Segment | Description |
|---|---|
| ID_locataire | Identificateur unique du locataire sur lequel la requête doit être exécutée. 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). Ne respecte pas la casse. |
| Ensemble_ressources | Ensemble spécifique de ressources des locataires sur lequel cette requête doit être exécutée. Détermine les ressources qui sont retournées dans la réponse de la requête. Les valeurs prises en charge sont : « directoryObjects », « users », « contacts » ou « groups ». Les valeurs respectent la casse. |
URL : paramètres de chaîne de requête
| Paramètre | Description |
|---|---|
| api-version | Indique la version de l’API Graph pour laquelle la demande est émise. Obligatoire. 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. 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. (Remplace l’utilisation de l’en-tête x-ms-dirapi-data-contract-version dans la version d’évaluation de l’API Graph.) |
| deltaLink | Jeton retourné dans la propriété deltaLink ou nextLink dans la dernière réponse. Obligatoire, mais vide pour la première demande. (Remplace le paramètre de chaîne de requête skipToken dans la version d’évaluation de l’API Graph.) |
| $filter | Indique les types d’entités à inclure dans la réponse. Facultatif. Les types d’entités pris en charge sont Utilisateur, Groupe et Contact. Valide uniquement quand <Ensemble_ressources> a la valeur « directoryObjects » ; sinon, <Ensemble_ressources> remplace le filtre. 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. 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. Pour spécifier un seul type d’entité, utilisez l’une des chaînes suivantes :
$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.) Important À partir de la version 1.5, l’espace de noms API Graph Microsoft.WindowsAzure.ActiveDirectory devient 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'). |
| $select | Indique les propriétés qui doivent être incluses dans la réponse. Si *$select^ n’est pas spécifié, toutes les propriétés sont incluses. Les propriétés peuvent être indiquées comme entièrement qualifiées ou non qualifiées. Plusieurs propriétés sont délimitées par des virgules.
|
Remarque : les paires clé-valeur dans la chaîne de requête respectent la casse, mais leur ordre n’est pas important.
Voici un exemple de requête différentielle simple. Elle est utilisée pendant la synchronisation initiale.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=
Voici un exemple de demande ultérieure.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U`
Réponses de requêtes différentielles
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. La liste suivante décrit le contenu d’une réponse :
Zéro à 200 entités [DirectoryObject], chacune contenant des modifications pour un objet [User], [Group] ou contactspécifique.
Zéro à 3000 entités [DirectoryLinkChange], chacune contenant des modifications pour un lien membre ou gestionnaire spécifique.
PropriétédeltaLink ou nextLink. 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. 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.
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. 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.
Si la propriété nextLink est retournée, il reste des modifications d’annuaire pour l’application à synchroniser après cette réponse. L’application doit émettre la demande de requête différentielle suivante dès que possible.
Les réponses sont toujours retournées au format JSON.
Éléments à prendre en compte en cas d’utilisation d’une requête différentielle
La liste suivante présente des éléments importants à prendre en compte pour les applications qui utilisent une requête différentielle :
Les modifications retournées par une requête différentielle représentent l’état des objets d’annuaire au moment de la réponse. Votre application ne doit pas traiter ces modifications comme des journaux des transactions pour une relecture.
Les modifications s’affichent dans l’ordre dans lequel elles se sont produites. Les objets modifiés le plus récemment s’affichent en dernier même si l’objet a été mis à jour plusieurs fois. Leur ordre n’est pas non plus affecté par le moment où le client a reçu les modifications. 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.
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. Même si une requête différentielle essaie au maximum de réduire les relectures, elles sont toujours possibles.
Votre application doit être prête à gérer un changement de suppression d’objet dont elle n’était pas informée.
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.
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.
Exemples de demandes et de réponses
Voici un exemple de demande de requête différentielle initiale :
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 :
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. 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.
L’exemple de réponse suivant illustre l’objet JSON retourné :
{
"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
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. 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.
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é. L’objet retourné ressemble alors à ceci :
{
"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 ». Voici l’exemple d’appel :
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 :
{ … "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é. 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.
Ressources supplémentaires
contact [Contract]: ../api/entity-and-complex-type-reference.md#contract-entity [Device]: ../api/entity-and-complex-type-reference.md#device-entity [DirectoryLinkChange]: ../api/entity-and-complex-type-reference.md#directorylinkchange-entity [DirectoryObject]: ../api/entity-and-complex-type-reference.md#directoryobject-entity [DirectoryRole]: ../api/entity-and-complex-type-reference.md#directoryrole-entity [DirectoryRoleTemplate]: ../api/entity-and-complex-type-reference.md#directoryroletemplate-entity [ExtensionProperty]: ../api/entity-and-complex-type-reference.md#extensionproperty-entity [Group]: ../api/entity-and-complex-type-reference.md#group-entity [OAuth2PermissionGrant]: ../api/entity-and-complex-type-reference.md#oauth2permissiongrant-entity [ServicePrincipal]: ../api/entity-and-complex-type-reference.md#serviceprincipal-entity [SubscribedSku]: ../api/entity-and-complex-type-reference.md#subscribedsku-entity [TenantDetail]: ../api/entity-and-complex-type-reference.md#tenantdetail-entity [User]: ../api/entity-and-complex-type-reference.md#user-entity