Demander des différences entre Azure AD Graph et Microsoft Graph

  • Article
  • 4 minutes de lecture

Cet article fait partie de l’étape 1 : passer en revue les différences d’API du processus de migration des applications.

Microsoft Graph et les API Graph Azure Active Directory (Azure AD) sont des API REST et prennent en charge les conventions OData pour les paramètres de requête. Toutefois, la syntaxe varie entre ces deux API.

Utilisez Graph Explorer pour essayer ces modèles de requête sur vos propres données, car il s’agit d’un excellent moyen d’en savoir plus sur les différences de demande et de réponse.

Requêtes de base

Le tableau suivant met en évidence les différences de demande main entre les deux API :

Détails de la demande Azure AD Graph Microsoft Graph
Syntaxe de la requête https://graph.windows.net/{tenant_id}/
{resource}?{version}&query-parameters		 https://graph.microsoft.com/
{version}/{resource}?query-parameters
Points de terminaison de service :
-Mondiale https://graph.windows.net https://graph.microsoft.com
- US Gov L4 https://graph.microsoftazure.us https://graph.microsoft.us
- US Gov L5 (DOD) https://graph.microsoftazure.us https://dod-graph.microsoft.us
-Allemagne https://graph.cloudapi.de https://graph.microsoft.de
- Chine (21Vianet) https://graph.chinacloudapi.cn https://microsoftgraph.chinacloudapi.cn
{tenant_id} Spécifiez l’ID du locataire dans la demande. Il est facultatif de spécifier un ID de locataire dans la requête, car il est déduit du jeton d’accès.

Si vous spécifiez l’ID de locataire, il se trouve entre et {version} dans {resource} l’URL de la requête.
{version} Spécifiez la version release d’Azure AD Graph dans la requête à l’aide d’un paramètre de requête requis. Spécifiez la version de mise en production de Microsoft Graph dans la requête dans le cadre du chemin d’URL juste après le point de terminaison de service.

Vous pouvez continuer à utiliser les mêmes paramètres de requête dans Microsoft Graph qu’Azure AD Graph.

Exemple de comparaison de requêtes

Supposons que vous souhaitiez une liste de tous les utilisateurs dont le nom commence par « Dan ».

Dans Azure AD Graph, vous pouvez utiliser cette requête :

GET https://graph.windows.net/contoso.com/users?$filter=startswith(givenName,'Dan')&api-version=1.6 Ou

GET https://graph.windows.net/myOrganization/users?$filter=startswith(givenName,'Dan')&api-version=1.6

Cette requête :

  • Cible la version 1.6 d’Azure AD Graph.
  • Spécifie contoso.com comme ID de locataire. L’alternative montre l’utilisation d’un alias myOrganization basé sur l’ID de locataire dans le jeton d’accès.
  • Appelle la ressource users.
  • Utilise le $filter paramètre de requête pour limiter la réponse aux noms donnés qui commencent par Dan.

Les résultats incluent des utilisateurs portant des noms tels que Daniel, Danforth, Danielle, Danerys, etc.

Une requête similaire pour Microsoft Graph serait la suivante :

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName,'Dan')

Ici:

  • La version est v1.0.
  • L’ID de locataire est déduit du jeton d’accès (non affiché).
  • La ressource et $filter le paramètre de requête sont identiques à la requête Azure AD.

REMARQUE : Si vous utilisez la bibliothèque cliente .NET Azure AD Graph, consultez Bibliothèques clientes .NET pour obtenir des stratégies et une aide plus spécifiques pour passer à la bibliothèque cliente Microsoft Graph .NET.

Identificateurs de clé : objectId et id

Dans Azure AD Graph, tous les types de ressources d’entité ont un identificateur unique (ou clé) appelé objectId. Pour la plupart (sauf indication contraire), ce même identificateur est appelé id dans Microsoft Graph.

Propriétés et $select par défaut

Utilisez le $select paramètre de requête, dans les requêtes GET, pour personnaliser la réponse afin d’inclure toutes les propriétés requises par votre application.

Les opérations d’obtention ou de liste microsoft Graph pour les ressources utilisateur ou de groupe retournent uniquement un sous-ensemble de toutes les propriétés, appelées propriétés par défaut. Les propriétés par défaut représentent les propriétés les plus couramment utilisées pour une ressource. En revanche, Azure AD Graph retourne l’ensemble complet de toutes les propriétés de la ressource respective.

Pour obtenir d’autres propriétés dans la version 1.0, votre application doit les demander explicitement à l’aide du $select paramètre de requête. Cela inclut toutes les extensions de schéma d’annuaire que votre application peut utiliser. Il est recommandé de demander uniquement les propriétés dont votre application a réellement besoin.

Pour illustrer la différence, utilisez Graph Explorer pour exécuter les requêtes suivantes et comparer les différentes réponses.

GET https://graph.microsoft.com/v1.0/me/
GET https://graph.microsoft.com/beta/me/

Passez en revue les réponses de chaque requête. Vous remarquerez que les informations d’adresse sont retournées par la version /beta, mais pas par la version /v1.0. Cela est dû au fait que les propriétés d’adresse ne sont pas dans le jeu de propriétés par défaut.

Si votre application s’appuie sur les propriétés d’adresse, vous devez mettre à jour vos requêtes v1.0 pour inclure le paramètre de $select requête :

https://graph.microsoft.com/v1.0/me/?$select=displayName,streetAddress,city,state,postalCode

La réponse à cette demande inclut les propriétés d’adresse. Il inclut également la propriété displayName , mais uniquement parce qu’elle a été spécifiée par le paramètre de requête.

Pour en savoir plus sur :

Relations et propriétés de navigation

Les relations (ou propriétés de navigation) sont un concept clé dans Azure AD Graph et Microsoft Graph, qui crée un réseau de ressources associées. Par exemple, les propriétés manager et directReports étendent la ressource utilisateur pour fournir une hiérarchie organisationnelle.

Les relations définissent également les appartenances, telles que les groupes auxquels un utilisateur appartient, les membres appartenant à un groupe ou à un rôle d’annuaire, etc.

Les requêtes Azure AD Graph utilisent $links pour indiquer les relations entre les ressources. Dans Microsoft Graph, cela utilise la notation OData v4.01 $ref à la place.

Le tableau suivant présente plusieurs exemples :

Tâche Azure AD Graph Microsoft Graph
Ajouter un membre POST /groups/{id}/$links/members POST /groups/{id}/members/$ref
Lister les liens des membres GET /groups/{id}/$links/members GET /groups/{id}/members/$ref
Répertorier les membres GET /groups/{id}/members GET /groups/{id}/members
Supprimer un membre DELETE /groups/{id}/$links/members/{id} DELETE /groups/{id}/members/{id}/$ref

Lors de la migration de vos applications vers Microsoft Graph, recherchez les demandes qui utilisent $links pour associer des ressources; modifiez-les pour les utiliser $ref à la place.

Étapes suivantes