Cette page vous a-t-elle été utile ?
Votre avis sur ce contenu est important. N'hésitez pas à nous faire part de vos commentaires.
Vous avez d'autres commentaires ?
1500 caractères restants
Exporter (0) Imprimer
Développer tout

Requête différentielle de l'API Azure AD Graph

Mis à jour: mai 2015

Cette rubrique aborde les requêtes différentielles qui peuvent être effectuées dans Azure Active Directory 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 pendant 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 Ajout, mise à jour et suppression d'une application.

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 Graph, consultez Authentication Scenarios for Azure AD.

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

Spécifie la version de l'API graphique sur laquelle porte la demande. 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.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').

(Remplace le paramètre de chaîne de requête objectScope dans la version d'évaluation de l'API Graph.)

ImportantImportant
Depuis la version 1.5, l'espace de noms de l'API graphique a été modifié de Microsoft.WindowsAzure.ActiveDirectory en Microsoft.DirectoryServices. Les versions antérieures de l'API graphique continuent à utiliser l'espace de noms précédent, 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.

  • Le type d'entité est spécifié pour les propriétés entièrement qualifiées, par exemple User/displayName. Des propriétés entièrement qualifiées DOIVENT être utilisées si <Ensemble_ressources> a la valeur « directoryObjects », par exemple 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. Elles ne peuvent être utilisées que quand <Ensemble_ressources> a une valeur autre que « directoryObjects », par exemple https://graph.windows.net/contoso.com/users?api-version=2013-04-05&deltaLink=&$select=displayName,jobTitle.

noteRemarque
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

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 Utilisateur, Groupe ou Coordonnées spécifique.

  • Zéro à 3 000 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.

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.

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
noteRemarque
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"
    }
  ]
}

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é ressemblerait à 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 retourneront 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.

Voir aussi

Microsoft réalise une enquête en ligne pour recueillir votre opinion sur le site Web de MSDN. Si vous choisissez d’y participer, cette enquête en ligne vous sera présentée lorsque vous quitterez le site Web de MSDN.

Si vous souhaitez y participer,
Afficher:
© 2015 Microsoft