Utiliser l’API Microsoft Graph

Microsoft Graph est une API web RESTful qui vous permet d’accéder aux ressources de service Cloud Microsoft. Après avoir enregistré votre application et obtenu des jetons d’authentification pour un utilisateur ou un service, vous pouvez effectuer des requêtes dans l’API Microsoft Graph.

Important : la manière dont les stratégies d’accès conditionnel s’appliquent à Microsoft Graph est en cours de modification. Les applications doivent être mises à jour pour gérer les scénarios dans lesquels des stratégies d’accès conditionnel sont configurées. Pour plus d’informations et de conseils, consultez le guide du développeur pour l’accès conditionnel à Azure Active Directory.

Espace de noms OData

L’API Microsoft Graph définit la plupart de ses ressources, méthodes et énumérations dans l’espace de noms OData, microsoft.graph, dans les métadonnées de Microsoft Graph. Un petit nombre d’ensembles d’API sont définis dans leurs sous-espaces de noms, tels que l’ API d’enregistrement d’appels qui définit des ressources commecallRecord dans microsoft.graph.callRecords.

Sauf indication contraire dans la rubrique correspondante, les types, les méthodes et les énumérations font partie de l’espace de noms microsoft.graph.

Appeler une méthode API REST

Pour lire ou écrire à une ressource comme un utilisateur ou un message électronique, vous créez une requête qui se présente comme suit :

{HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters}

Les composants d’une requête incluent :

  • {Méthode HTTP} - Méthode HTTP utilisée dans la requête à Microsoft Graph.
  • {version} - Version de l’API Microsoft Graph que votre application utilise.
  • {ressource} - Ressource dans Microsoft Graph que vous référencez.
  • {Query-Parameters} - Options de requête OData facultatives ou paramètres de méthode Rest qui personnalisent la réponse.

Une fois que vous avez effectué une requête, la réponse renvoyée inclut ce qui suit :

  • Code d’état - Code d’état HTTP qui indique le succès ou l’échec. Pour plus d’informations sur les codes d’erreur HTTP, voir Erreurs.
  • Message de réponse - Données que vous avez demandées ou résultat de l’opération. Le message de réponse peut être vide pour certaines opérations.
  • nextLink - Si votre requête renvoie un grand nombre de données, vous devez parcourir les pages en choisissant @odata.nextLink. Pour plus d’informations, reportez-vous à Pagination.

Méthodes HTTP

Microsoft Graph utilise la méthode HTTP sur votre requête pour déterminer ce que fait cette dernière. L’API prend en charge les méthodes suivantes.

Méthode Description
GET Lire les données à partir d’une ressource.
POST Créer une nouvelle ressource ou effectuer une action.
PATCH Mettre à jour une ressource avec de nouvelles valeurs.
PUT Remplacer une ressource par une autre.
DELETE Supprimer une ressource.
  • Pour les méthodes CRUDGET etDELETE, le corps de la requête n’est pas requis.
  • Les méthodes POST, PATCH et PUT nécessitent un corps de requête, généralement spécifié au format JSON, qui contient des informations supplémentaires, telles que les valeurs des propriétés de la ressource.

Version

Microsoft Graph prend actuellement en charge les deux versions : v1.0 et beta.

  • v1.0 inclut les API généralement disponibles. Utilisez la version v1.0 pour toutes les applications de production.
  • beta inclut des API qui sont actuellement en version préliminaire. Étant donné que nous pourrions apporter des modifications majeures à la version bêta de nos API, nous vous recommandons d’utiliser la version bêta uniquement pour tester les applications en cours de développement ; ne les utilisez pas dans vos applications de production.

Nous recherchons toujours des commentaires sur les versions bêta de nos API. Pour fournir des commentaires ou demander des fonctionnalités, consultez notre Forum des idées de la Plateforme des développeurs Microsoft 365.

Pour plus d’informations sur les versions API, voir Contrôle de version et prise en charge.

Resource

Une ressource peut être une entité ou un type complexe, généralement défini avec des propriétés. Les entités diffèrent des types complexes en incluant toujours une propriété ID.

Votre URL doit inclure la ressource avec laquelle vous interagissez dans la requête, notamment me, utilisateur, groupe, drive, et site. Souvent, les ressources de niveau supérieur incluent également des relations, que vous pouvez utiliser pour accéder à des ressources supplémentaires, par exemple me/messages ou me/drive. Vous pouvez également interagir avec les ressources à l’aide de méthodes. Par exemple, pour envoyer un e-mail, utilisez me/sendMail. Pour plus d’informations, voiraccéder aux données et aux méthodes en accédant à Microsoft Graph.

Chaque ressource peut nécessiter des autorisations différentes pour pouvoir y accéder. Vous avez souvent besoin d’un niveau supérieur d’autorisations pour créer ou mettre à jour une ressource, comparé aux autorisations de lecture. Pour plus d’informations sur les autorisations requises, consultez la rubrique sur la référence aux méthodes.

Pour plus d’informations sur les autorisations, reportez-vous à Référence aux autorisations.

Paramètres de requête

Les paramètres de requête peuvent être des options de requête système OData ou d’autres chaînes qu’une méthode accepte pour personnaliser sa réponse.

Vous pouvez utiliser la requête de système OData optionnel pour inclure plus ou moins de propriétés que la réponse par défaut, filtrer la réponse pour les éléments qui correspondent à une requête personnalisée ou fournir des paramètres supplémentaires pour une méthode.

Par exemple, l’ajout du paramètrefiltersuivant restreint les messages renvoyés uniquement à ceux avec laemailAddresspropriété dejon@contoso.com.

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'

Pour plus d’informations sur les options de requête OData, voir utiliser les paramètres de requête pour personnaliser les réponses.

Hormis les options de requête OData, certaines méthodes nécessitent des valeurs de paramètre spécifiées dans le cadre de l’URL de requête. Par exemple, vous pouvez obtenir une collection d’événements qui se sont produits au cours d’un laps de temps dans le calendrier d’un utilisateur, en interrogeant la relation de calendarView d'un utilisateur et en spécifiant le pointstartDateTime et endDateTime les valeurs comme paramètres de requête :

GET https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

Outils d’interaction avec Microsoft Graph

Afficheur Graph

L’Afficheur Graph est un outil web que vous pouvez utiliser pour créer et tester des requêtes à l’aide des API Microsoft Graph. Vous pouvez accéder à l’Afficheur Graph à l’adresse suivante : https://developer.microsoft.com/graph/graph-explorer.

Vous pouvez accéder aux données de démonstration sans vous connecter, ou vous pouvez vous connecter par l’intermédiaire du client de votre choix. Utilisez la procédure suivante pour créer la requête :

  1. Sélectionnez la méthode HTTP.
  2. Sélectionnez la version d’API que vous souhaitez utiliser.
  3. Tapez la requête dans la zone de texte de la requête.
  4. Sélectionnez Exécuter la requête.

L’exemple suivant présente une requête qui retourne des informations sur les utilisateurs vers le client de démonstration :

Capture d’écran de l’Afficheur Graph avec une requête utilisateur GET mise en surbrillance

Des exemples de requêtes sont fournis dans l’Afficheur Graph pour vous permettre d’exécuter plus rapidement des requêtes courantes. Pour afficher des exemples disponibles, sélectionnez Afficher plus d’exemples. Sélectionnez Activé pour la série d’exemples que vous voulez afficher, puis après fermeture de la fenêtre de sélection, une liste de requêtes prédéfinies doit s’afficher.

Un code d’état et un message s’affichent après l’envoi de la requête et la réponse apparaît dans l’onglet Aperçu de la réponse.

Postman

Postman est un outil que vous pouvez utiliser pour créer et tester des requêtes à l’aide des API Microsoft Graph. Vous pouvez télécharger Postman à l'adresse suivante : https://www.getpostman.com/. Pour interagir avec Microsoft Graph dans Postman, vous utilisez la collection Microsoft Graph.

Pour obtenir plus d’informations, consultez Utilisation de Postman avec l’API Microsoft Graph.

Étapes suivantes

Vous êtes prêt à devenir opérationnel avec Microsoft Graph. Découvrez le Démarrage rapide ou débutez à l’aide de l’un de nos exemples de codes et kits de développement logiciel (SDK).