Vue d’ensemble des opérations | Concepts de l’API Graph

  • Article

L’API Azure Active Directory (AD) Graph est un service compatible avec OData 3.0 permettant de lire et de modifier des objets tels que des utilisateurs, des groupes et des contacts dans un locataire. L’API Azure AD Graph expose les points de terminaison REST auxquels vous envoyez des demandes HTTP pour effectuer des opérations à l’aide du service. Les sections suivantes fournissent des informations générales sur la mise en forme des demandes et les réponses attendues lors de l’utilisation de l’API Graph pour la lecture et l’écriture de ressources d’annuaire, sur les appels de fonctions et d’actions d’annuaire et sur l’exécution de requêtes dans l’annuaire. Pour plus d’informations sur l’exécution de ressources d’annuaire d’opérations spécifiques, consultez la rubrique appropriée sur les opérations dans la documentation Référence de l’API Graph Azure AD.

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.

Une demande réussie à l’API Graph doit être acheminée vers un point de terminaison valide et être correctement mise en forme, autrement dit, elle doit contenir les en-têtes nécessaires et, le cas échéant, une charge utile JSON dans le corps de la demande. L’application qui effectue la demande doit inclure un jeton provenant d’Azure AD prouvant qu’elle est autorisée à accéder aux ressources ciblées par la demande. L’application doit être en mesure de gérer les réponses reçues de l’API Graph.

Les sections de cette rubrique vont vous aider à comprendre le format des demandes et des réponses utilisé avec l’API Graph.

Authentification et autorisation

Chaque demande adressée à l’API Graph doit avoir un jeton de porteur émis par Azure Active Directory en pièce jointe. Le jeton véhicule des informations sur votre application, l’utilisateur connecté (dans le cas d’autorisations déléguées), l’authentification et les opérations sur l’annuaire que votre application est autorisée à traiter. Ce jeton figure dans l’entête Authorization de la demande. Par exemple (le jeton a été réduit par souci de concision) :

Authorization: Bearer eyJ0eX ... FWSXfwtQ

L’API Graph effectue une autorisation basée sur les étendues d’autorisation OAuth 2.0 présentes dans le jeton. Pour plus d’informations sur les étendues d’autorisation exposées par l’API Graph, consultez Étendues d’autorisation de l’API Graph.

Afin que votre application s’authentifie auprès d’Azure AD et appelle l’API Graph, vous devez l’ajouter à votre locataire et la configurer pour exiger des autorisations (étendues d’autorisation OAuth 2.0) pour Azure Active Directory. Pour plus d’informations sur l’ajout et la configuration d’une application, consultez Intégration d’applications à Azure Active Directory.

Azure AD utilise le protocole d’authentification OAuth 2.0. Vous pouvez en savoir plus sur OAuth 2.0 dans Azure AD, notamment sur les flux et les jetons d’accès pris en charge dans OAuth 2.0 dans Azure AD.

Adressage du point de terminaison

Pour effectuer des opérations avec l’API Graph, vous envoyez des requêtes HTTP à l’aide d’une méthode prise en charge (GET, POST, PATCH, PUT ou DELETE) à un point de terminaison qui cible le service, un regroupement de ressources, une ressource individuelle, une propriété de navigation d’une ressource ou une fonction ou action exposée par le service. Les points de terminaison sont exprimés en tant qu’URL.

Le format de base d’un point de terminaison de l’API Graph est décrit ci-après :

https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}

Les composant suivants comprennent l’URL :

Remarque: dans certains cas, lors de la lecture de regroupements de ressources, les paramètres de requête OData peuvent être ajoutés à la demande pour filtrer, classer et paginer le jeu de résultats. Pour plus d’informations, consultez la section Paramètres de requête OData dans cette rubrique.

Identificateur du client {tenant_id}

Vous pouvez spécifier le locataire cible d’une demande de l’une des quatre manières suivantes :

  • Par ID d’objet locataire. Il s’agit d’un GUID qui a été affecté lors de la création du locataire. Celui-ci figure dans la propriété objectId de l’objet [TenantDetail]. L’URL suivante montre comment traiter le regroupement de ressources des utilisateurs à l’aide de l’ID d’objet locataire :
    https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.

  • Par nom de domaine vérifié (inscrit). Il s’agit de l’un des noms de domaine inscrits pour le locataire. Ceux-ci figurent dans la propriété verifiedDomains de l’objet [TenantDetail]. L’URL suivante montre comment traiter le regroupement de ressources des utilisateurs d’un locataire dont le domaine est contoso.com :
    https://graph.windows.net/contoso.com/users?api-version=1.6.

  • En utilisant l’alias myOrganization . Cet alias n’est disponible qu’en utilisant l’authentification de type Octroi d’un code d’autorisation Oauth (en 3 étapes), c’est-à-dire lors de l’utilisation d’une étendue d’autorisation déléguée. L’alias ne respecte pas la casse. Il remplace l’ID d’objet ou le domaine du locataire dans l’URL. Quand l’alias est utilisé, l’API Graph déduit le client à partir des revendications présentées dans le jeton joint à la demande. L’URL suivante montre comment traiter le regroupement de ressources des utilisateurs d’un locataire utilisant cet alias :
    https://graph.windows.net/myorganization/users?api-version=1.6.

  • En utilisant l’alias me . Cet alias n’est disponible qu’en utilisant l’authentification de type Octroi d’un code d’autorisation Oauth (en 3 étapes), c’est-à-dire lors de l’utilisation d’une étendue d’autorisation déléguée. L’alias ne respecte pas la casse. Il remplace l’ID d’objet ou le domaine du locataire dans l’URL. Quand l’alias est utilisé, l’API Graph déduit l’utilisateur à partir des revendications présentées dans le jeton joint à la demande. Utilisez l’URL suivante pour traiter l’utilisateur connecté en utilisant cet alias :
    https://graph.windows.net/me?api-version=1.6.

Remarque : l’alias me cible uniquement des opérations pour l’utilisateur connecté. Pour plus d’informations, reportez-vous à la rubrique Opérations de l’utilisateur connecté.

Chemin de la ressource {resource_path}

Spécifiez le {resource_path} différemment selon que vous ciblez un regroupement de ressources, une ressource individuelle, une propriété de navigation d’une ressource, une fonction ou une action exposée sur le locataire, ou encore une fonction ou une action sur une ressource.

Cible Chemin d’accès Explication
Métadonnées du service /$metadata Retourne le document de métadonnées du service. L’exemple suivant cible les métadonnées de service utilisant le locataire contoso.com :
https://graph.windows.net/contoso.com/$metadata?api-version=1.6

Remarque: aucune authentification n’est nécessaire pour lire les métadonnées du service.
Regroupement de ressources /{resource_collection} Cible un regroupement de ressources, comme des utilisateurs ou des groupes dans le locataire. Vous pouvez utiliser ce chemin d’accès pour lire les ressources dans le regroupement et, selon le type de ressource, pour créer une ressource dans le locataire. Dans de nombreux cas, le jeu de résultats retourné par une lecture peut être affiné par l’ajout de paramètres de requête afin de filtrer, ordonner ou paginer les résultats de la page. L’exemple suivant cible le regroupement d’utilisateurs :
https://graph.windows.net/myorganization/users?api-version=1.6
Ressource unique /{resource_collection}/{resource_id} Cible une ressource spécifique dans un locataire, tel qu’un utilisateur, un contact professionnel ou un groupe. Pour la plupart des ressources, le resource_id est l’ID d’objet. Certaines ressources autorisent les spécificateurs supplémentaires ; par exemple, les utilisateurs peuvent également être spécifiés par le nom d’utilisateur principal (UPN). Selon la ressource, vous pouvez utiliser ce chemin d’accès pour obtenir les propriétés déclarées de la ressource, modifier ses propriétés déclarées ou supprimer la ressource. L’exemple suivant cible l’utilisateur john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6
Propriété de navigation (objets) /{resource_collection}/{resource_id}/{property_name} Cible une propriété de navigation d’une ressource spécifique, tel que le responsable ou les appartenances aux groupes d’un utilisateur ou les membres d’un groupe. Vous pouvez utiliser ce chemin pour renvoyer le ou les objets référencés par la propriété de navigation cible. L’exemple suivant cible le gestionnaire de john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6

Remarque : cette forme d’adressage est disponible uniquement pour les lectures.
Propriété de navigation (liens) /{resource_collection}/{resource_id}/$links/{property_name} Cible une propriété de navigation d’une ressource spécifique, tel que le responsable ou les appartenances aux groupes d’un utilisateur ou les membres d’un groupe. Vous pouvez utiliser cette forme d’adressage pour lire et modifier une propriété de navigation. Sur les lectures, les objets référencés par la propriété sont renvoyés sous la forme d’un ou plusieurs liens dans le corps de la réponse. Sur les écritures, les objets sont spécifiés sous la forme d’un ou plusieurs liens dans le corps de la demande. L’exemple suivant cible la propriété de gestionnaire de john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6
Fonctions ou actions exposées sur le locataire /{function_name} Cible une fonction ou une action exposée sur le locataire. Les fonctions et les actions sont généralement appelées avec une demande POST et peuvent inclure un corps de demande. L’exemple suivant cible la fonction isMemberOf :
https://graph.windows.net/myorganization/isMemberOf?api-version=1.6.
Fonctions ou actions exposées sur un ressource. /{resource_collection}/{resource_id}/{function_name} Cible une fonction ou une action exposée sur une ressource. Les fonctions et les actions sont généralement appelées avec une demande POST et peuvent inclure un corps de demande. L’exemple suivant cible la fonction getMemberGroups :
https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6.

Version de l’API Graph {api-version}

Le paramètre de requête api-version permet de cibler une version spécifique de l’API Graph pour une opération. Ce paramètre est requis.

Le paramètre api-version peut posséder l’une des valeurs suivantes :

  • "beta"
  • "1.6"
  • "1.5"
  • "2013/11/08"
  • "2013/04/05"

Par exemple, l’URL suivante cible le regroupement d’utilisateurs à l’aide de l’API Graph version 1.6 :

https://graph.windows.net/myorganization/users?api-version=1.6

Pour plus d’informations sur les versions et les modifications de fonctionnalité entre versions, consultez Contrôle de version.

Paramètres de requête OData

La plupart du temps, lorsque vous lisez un regroupement de ressources, vous pouvez filtrer, trier et paginer le jeu de résultats en associant des paramètres de requête OData à votre demande.

L’API Graph prend en charge les paramètres de requête OData suivants :

  • $filter
  • $batch
  • $expand
  • $orderby
  • $top
  • $skiptoken et page précédente

Pour plus d’informations sur les paramètres de requête OData pris en charge et sur leurs limitations dans l’API Graph, consultez Options de requêtes, de filtres et de pagination prises en charge.

En-têtes de demande et de réponse

Le tableau suivant montre les en-têtes HTTP communs utilisés dans les demandes avec l’API Graph. Elle n’est pas censée être complète.

En-tête de demande Description
Autorisation Obligatoire. Jeton de support émis par Azure Active Directory. Reportez-vous à Authentification et autorisation dans cette rubrique pour plus d’informations.
Content-Type Obligatoire si le corps de la demande est présent. Type de support du contenu placé dans le corps de la demande. Utilisez application/json. Il est possible d’inclure des paramètres avec le type de support.
Remarque : application/atom+xml et application/xml (liens) sont pris en charge, mais ne sont pas recommandés pour des raisons de performances et parce que la prise en charge de XML sera dépréciée dans une version ultérieure.
Content-Length Obligatoire si le corps de la demande est présent. Longueur de la demande, en octets.

Le tableau suivant montre les en-têtes HTTP communs renvoyés dans les réponses par l’API Graph. Elle n’est pas censée être complète.

En-tête de réponse Description
Content-Type Type de support du contenu placé dans le corps de la réponse. La valeur par défaut est application/json. Les demandes de photos miniatures de l’utilisateur retournent image/jpeg par défaut.
Localisation Valeur renvoyée dans les réponses aux demandes POST qui créent une nouvelle ressource (objet) dans le répertoire. Contient l’URI de la ressource nouvellement créée.
ocp-aad-diagnostics-server-name Identificateur du serveur qui a effectué l’opération demandée.
ocp-aad-session-key Clé qui identifie la session active avec le service d’annuaire.

Au minimum, nous vous recommandons de procéder comme suit pour chaque demande :

  1. Consigner un horodatage précis de l’envoi de la demande.
  2. Envoyer et consigner le client-request-id.
  3. Consigner le code de réponse HTTP et request-id.

Fournir des informations dans ces journaux aidera Microsoft à résoudre les problèmes lorsque vous aurez besoin d’aide ou d’assistance technique.

Corps de demande et de réponse

Les corps des demandes POST, PATCH et PUT peuvent être envoyés dans les charges utiles JSON ou XML. Les réponses du serveur peuvent être retournées dans les charges utiles JSON ou XML. Vous pouvez spécifier la charge utile dans les corps de requête à l’aide de l’en-tête de demande Content-Type et dans les réponses à l’aide de l’en-tête de demande Accept.

Nous vous recommandons vivement d’utiliser les charges utiles JSON dans les demandes et les réponses avec l’API Graph, et ce, pour des raisons de performances et parce que XML sera déconseillé dans une version ultérieure.

Fonctionnalités avancées

Les sections précédentes ont abordé la mise en forme des demandes et des réponses de base à l’aide de l’API Graph. Des fonctionnalités plus avancées peuvent ajouter des paramètres de chaîne de requête supplémentaires ou posséder des corps de demande et de réponse vraiment différents de ceux des opérations de base décrites précédemment dans cette rubrique.

Ces fonctions incluent :

  • Traitement par lots : l’API Graph prend en charge la mise en lots. L’envoi de demandes par lots réduit les allers-retours au serveur, ce qui diminue la charge pesant sur le réseau et aide à accomplir vos opérations plus rapidement. Pour plus d’informations sur le traitement par lots à l’aide de l’API Graph, consultez Traitement par lots.
  • Requête différentielle : l’API Graph prend en charge l’exécution de requêtes différentielles. La requête différentielle vous permet de retourner des modifications à des entités spécifiques dans un locataire entre des requêtes émises à des moments différents. Cette fonctionnalité est souvent utilisée pour synchroniser un magasin local avec des modifications sur le locataire. Pour plus d’informations sur la requête différentielle à l’aide de l’API Graph, consultez Requête différentielle.

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