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.

Pour lire ou écrire dans une ressource telle qu’un utilisateur ou un message électronique, vous construisez 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. - The version of the Microsoft Graph API your application is using.
  • {ressource} - Ressource dans Microsoft Graph que vous référencez. - 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 link - If your request returns a lot of data, you need to page through it by choosing @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 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 or resources you are interacting with in the request, such as me, ****, ****, ****, and ****. 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.Each of the 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 query parameters to customize the response in your Microsoft Graph app. Use query parameters 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 property of .

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

Étapes suivantesNext steps

Vous êtes prêt à devenir opérationnel avec Microsoft Graph.You're ready to get up and running with Microsoft Graph. Pour plus d’informations, accédez à l’Afficheur Graph pour tester des requêtes, testez le démarrage rapide, ou commencez à utiliser l’un de nos exemples de code et SDK.To learn more, go to the Graph Explorer to try out some requests, try the Quick Start, or get started using one of our SDKs and code samples.