Différences de demande entre Azure AD Graph et Microsoft Graph
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 qui 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 et découvrir les différences entre les requêtes et les réponses avant de mettre à jour votre code.
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 (retiré) | https://graph.cloudapi.de |
https://graph.microsoft.de |
| - Chine (21Vianet) | https://graph.chinacloudapi.cn |
https://microsoftgraph.chinacloudapi.cn |
| {tenant_id} | Spécifiez l’ID de locataire ou le nom de domaine dans la demande. | Optional. L’ID de locataire est déduit du jeton d’accès. Si vous spécifiez l’ID de locataire, utilisez la syntaxe suivante : https://graph.microsoft.com/{version}/{tenant_id}/{resource}?query-parameters. |
| {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. |
La syntaxe des paramètres de requête est la même pour Microsoft Graph et Azure AD Graph. Toutefois, Microsoft Graph prend en charge davantage de paramètres de requête et de fonctionnalités de requête 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 le locataire Contoso. Le tableau suivant présente les différences de requête entre Azure AD Graph et Microsoft Graph.
| Azure AD Graph | Microsoft Graph |
|---|---|
GET https://graph.windows.net/contoso.com/users?$filter=startswith(givenName,'Dan')&api-version=1.6 |
GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName,'Dan') |
Identificateurs de clé primaire : objectId et id
Dans Azure AD Graph, tous les types de ressources d’entité ont un identificateur unique (ou clé primaire) appelé objectId. Pour la plupart des entités (sauf indication contraire), cet identificateur est appelé id dans Microsoft Graph.
En plus de la clé primaire, certaines entités prennent en charge un autre identificateur de clé. Par exemple, les ressources application et servicePrincipal dans Microsoft Graph prennent en charge un autre identificateur de clé pour leur propriété appId .
Propriétés et $select par défaut
Il est recommandé de demander uniquement les propriétés dont votre application a réellement besoin. Utilisez le $select paramètre de requête, dans les requêtes GET, pour personnaliser la réponse afin d’inclure uniquement les propriétés requises par votre application.
Dans certains cas, dans Microsoft Graph, par exemple, les opérations GET ou LIST pour les ressources utilisateur et de groupe , seul un sous-ensemble de toutes les propriétés est retourné. Ces propriétés par défaut représentent les propriétés les plus couramment utilisées pour les ressources. En revanche, Azure AD Graph retourne l’ensemble complet de toutes les propriétés de la ressource respective. Lorsque la ressource retourne uniquement les propriétés par défaut, votre application doit demander explicitement d’autres propriétés à l’aide du $select paramètre de requête.
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/
Notez la différence dans les réponses. La /beta version retourne plus de propriétés que la /v1.0 version. Si votre application s’appuie sur la propriété streetAddress , par exemple, vous devez mettre à jour vos v1.0 demandes pour utiliser le $select paramètre de requête pour demander la propriété streetAddress en plus des autres propriétés dont l’application a besoin. Par exemple :
https://graph.microsoft.com/v1.0/me?$select=displayName,streetAddress,city,state,postalCode
Pour en savoir plus sur :
- Propriétés par défaut sur les ressources d’utilisateur et de groupe. Consultez utilisateurs et groupes
- Le
$selectparamètre et les autres paramètres de requête ODATA pris en charge, consultez Utiliser des paramètres de requête pour personnaliser les réponses. - Autres optimisations recommandées, consultez Bonnes pratiques.
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. Microsoft Graph 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, mettez à jour les références qui utilisent $links pour associer des ressources à utiliser à la $ref place.