Utiliser l’API Microsoft GraphUse the Microsoft Graph API

Microsoft Graph est une API web RESTful qui vous permet d’accéder aux ressources de service Cloud Microsoft.Microsoft Graph is a RESTful web API that enables you to access Microsoft Cloud service resources. 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.After you register your app and get authentication tokens for a user or service, you can make requests to the Microsoft Graph API.

Important : la manière dont les stratégies d’accès conditionnel s’appliquent à Microsoft Graph est en cours de modification.Important: How conditional access policies apply to Microsoft Graph is changing. Les applications doivent être mises à jour pour gérer les scénarios dans lesquels des stratégies d’accès conditionnel sont configurées.Applications need to be updated to handle scenarios where conditional access policies are configured. Pour plus d’informations et de conseils, consultez le guide du développeur pour l’accès conditionnel à Azure Active Directory.For more information and guidance, see Developer Guidance for Azure Active Directory Conditional Access.

Espace de noms ODataOData namespace

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.The Microsoft Graph API defines most of its resources, methods, and enumerations in the OData namespace, microsoft.graph, in the Microsoft Graph metadata. 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.A small number of API sets are defined in their sub-namespaces, such as the call records API which defines resources like callRecord in 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.Unless explicitly specified in the corresponding topic, assume types, methods, and enumerations are part of the microsoft.graph namespace.

Appeler une méthode API RESTCall a REST API method

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 :To read from or write to a resource such as a user or an email message, you construct a request that looks like the following:

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

Les composants d’une requête incluent :The components of a request include:

  • {Méthode HTTP} - Méthode HTTP utilisée dans la requête à Microsoft Graph.{HTTP method} - The HTTP method used on the request to Microsoft Graph.
  • {version} - Version de l’API Microsoft Graph que votre application utilise.{version} - The version of the Microsoft Graph API your application is using.
  • {ressource} - Ressource dans Microsoft Graph que vous référencez.{resource} - The resource in Microsoft Graph that you're referencing.
  • {Query-Parameters} - Options de requête OData facultatives ou paramètres de méthode Rest qui personnalisent la réponse.{query-parameters} - Optional OData query options or REST method parameters that customize the response.

Une fois que vous avez effectué une requête, la réponse renvoyée inclut ce qui suit :After you make a request, a response is returned that includes:

  • Code d’état - Code d’état HTTP qui indique le succès ou l’échec.Status code - An HTTP status code that indicates success or failure. Pour plus d’informations sur les codes d’erreur HTTP, voir Erreurs.For details about HTTP error codes, see Errors.
  • 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.Response message - The data that you requested or the result of the operation. The response message can be empty for some operations.
  • nextLink - Si votre requête renvoie un grand nombre de données, vous devez parcourir les pages en choisissant @odata.nextLink.nextLink - If your request returns a lot of data, you need to page through it by using the URL returned in @odata.nextLink. Pour plus d’informations, reportez-vous à Pagination.For details, see Paging.

Méthodes HTTPHTTP methods

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.Microsoft Graph uses the HTTP method on your request to determine what your request is doing. The API supports the following methods.

MéthodeMethod DescriptionDescription
GETGET Lire les données à partir d’une ressource.Read data from a resource.
POSTPOST Créer une nouvelle ressource ou effectuer une action.Create a new resource, or perform an action.
PATCHPATCH Mettre à jour une ressource avec de nouvelles valeurs.Update a resource with new values.
PUTPUT Remplacer une ressource par une autre.Replace a resource with a new one.
DELETEDELETE Supprimer une ressource.Remove a resource.
  • Pour les méthodes CRUDGET etDELETE, le corps de la requête n’est pas requis.For the CRUD methods GET and DELETE, no request body is required.
  • 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.The POST, PATCH, and PUT methods require a request body, usually specified in JSON format, that contains additional information, such as the values for properties of the resource.

VersionVersion

Microsoft Graph prend actuellement en charge les deux versions : v1.0 et beta.Microsoft Graph currently supports two versions: v1.0 and beta.

  • v1.0 inclut les API généralement disponibles.v1.0 includes generally available APIs. Utilisez la version v1.0 pour toutes les applications de production.Use the v1.0 version for all production apps.
  • beta inclut des API qui sont actuellement en version préliminaire.beta includes APIs that are currently in preview. É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.Because we might introduce breaking changes to our beta APIs, we recommend that you use the beta version only to test apps that are in development; do not use beta APIs in your production apps.

Nous recherchons toujours des commentaires sur les versions bêta de nos API.We are always looking for feedback on our beta APIs. Pour fournir des commentaires ou demander des fonctionnalités, consultez notre page UserVoice.To provide feedback or request features, see our UserVoice page.

Pour plus d’informations sur les versions API, voir Contrôle de version et prise en charge.For more information about API versions, see Versioning and support.

ResourceResource

Une ressource peut être une entité ou un type complexe, généralement défini avec des propriétés.A resource can be an entity or complex type, commonly defined with properties. Les entités diffèrent des types complexes en incluant toujours une propriété ID.Entities differ from complex types by always including an id property.

Votre URL doit inclure la ressource avec laquelle vous interagissez dans la requête, notamment me, utilisateur, ** groupe **, drive, et site.Your URL will include the resource you are interacting with in the request, such as me, user, group, drive, and 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.Often, top-level resources also include relationships, which you can use to access additional resources, like me/messages or me/drive. Vous pouvez également interagir avec les ressources à l’aide de méthodes. Par exemple, pour envoyer un e-mail, utilisez me/sendMail.You can also interact with resources using methods; for example, to send an email, use me/sendMail. Pour plus d’informations, voiraccéder aux données et aux méthodes en accédant à Microsoft Graph.For more information, see Access data and methods by navigating 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.Each resource might require different permissions to access it. You will often need a higher level of permissions to create or update a resource than to read it. For details about required permissions, see the method reference topic.

Pour plus d’informations sur les autorisations, reportez-vous à Référence aux autorisations.For details about permissions, see Permissions reference.

Paramètres de requêteQuery parameters

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.Query parameters can be OData system query options, or other strings that a method accepts to customize its response.

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.You can use optional OData system query options to include more or fewer properties than the default response, filter the response for items that match a custom query, or provide additional parameters for a method.

Par exemple, l’ajout du paramètrefiltersuivant restreint les messages renvoyés uniquement à ceux avec laemailAddresspropriété dejon@contoso.com.For example, adding the following filter parameter restricts the messages returned to only those with the emailAddress property of jon@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.For more information about OData query options, see Use query parameters to customize responses.

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.Aside from OData query options, some methods require parameter values specified as part of the query URL. 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 :For example, you can get a collection of events that occurred during a time period in a user's calendar, by querying the calendarView relationship of a user, and specifying the period startDateTime and endDateTime values as query parameters:

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 GraphTools for interacting with Microsoft Graph

Afficheur GraphGraph Explorer

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.Graph Explorer is a web-based tool that you can use to build and test requests using Microsoft Graph APIs. Vous pouvez accéder à l’Afficheur Graph à l’adresse suivante : https://developer.microsoft.com/graph/graph-explorer.You can access Graph Explorer at: 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.You can either access demo data without signing in, or you can sign in to a tenant of your own. Procédez comme suit pour créer la requête :Use the following steps to build the request:

  1. Sélectionnez la méthode HTTP.Select the HTTP method.
  2. Sélectionnez la version d’API que vous souhaitez utiliser.Select the version of API that you want to use.
  3. Tapez la requête dans la zone de texte de la requête.Type the query in the request text box.
  4. Sélectionnez Exécuter la requête.Select Run Query.

L’exemple suivant présente une requête qui retourne des informations sur les utilisateurs vers le client de démonstration :The following example shows a request that returns information about users in the demo tenant:

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.Sample queries are provided in Graph Explorer to enable you to more quickly run common requests. Pour afficher des exemples disponibles, sélectionnez Afficher plus d’exemples.To see the samples that are available, select show more samples. 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.Select On for the set of samples that you want to see, and then after closing the selection window, you should see a list of predefined requests.

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.A status code and message are displayed after a request is sent and the response is shown in the Response Preview tab.

PostmanPostman

Postman est un outil que vous pouvez utiliser pour créer et tester des requêtes à l’aide des API Microsoft Graph.Postman is a tool that you can use to build and test requests using the Microsoft Graph APIs. Vous pouvez télécharger Postman à l'adresse suivante : https://www.getpostman.com/.You can download Postman at: https://www.getpostman.com/. Pour interagir avec Microsoft Graph dans Postman, vous utilisez la collection Microsoft Graph.To interact with Microsoft Graph in Postman, you use the Microsoft Graph collection.

Pour obtenir plus d’informations, consultez Utilisation de Postman avec l’API Microsoft Graph.For more information, see Use Postman with the Microsoft Graph API.

Étapes suivantesNext steps

Vous êtes prêt à devenir opérationnel avec Microsoft Graph.You're ready to get up and running with 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).Try the Quick Start, or get started using one of our SDKs and code samples.