Les premiers pas
Espace de noms OData
L'API de Microsoft Graph API structure la majorité de ses ressources, de ses méthodes et de ses énumérations au sein de l'espace de noms OData principal appelé microsoft.graph, tel que défini dans les métadonnées officielles de Microsoft Graph API. Cet espace de noms joue un rôle fondamental dans l'organisation logique de l'API, en fournissant un cadre cohérent pour accéder et manipuler les différents types de données proposés dans l'écosystème Microsoft 365.
Dans certains cas particuliers, un petit nombre de collections d'API sont définies dans des sous-espaces de noms spécifiques. C'est notamment le cas de l'API des enregistrements d'appels (call records API), exposant des ressources comme callRecord dans un sous-espace de noms distinct nommé microsoft.graph.callRecords. Cette structure permet de regrouper des fonctionnalités spécialisées tout en maintenant une séparation claire entre les domaines fonctionnels.
Sauf indication contraire explicitement mentionnée dans la documentation du sujet concerné, il faut donc considérer que tous les types, méthodes et énumérations utilisés dans Microsoft Graph API font partie de l'espace de noms microsoft.graph. Cela garantit une certaine uniformité dans la conception de l'API et facilite la découverte ainsi que l'intégration des ressources lors du développement d'applications connectées.
Appeler une méthode de l'API REST
Pour lire ou écrire dans une ressource, telle qu'un utilisateur ou un courriel, créez une requête semblable à celle-ci :
| {HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters} |
Les éléments d'une demande comprennent :
| Paramètre | Description |
|---|---|
| {HTTP method} | Ce paramètre permet d'indiquer la méthode HTTP utilisée sur la demande à Microsoft Graph API. |
| {version} | Ce paramètre permet d'indiquer la version de l'API de Microsoft Graph API utilisée par votre application. |
| {resource} | Ce paramètre permet d'indiquer la ressource dans Microsoft Graph API à laquelle vous faites référence. |
| {query-parameters} | Ce paramètre permet d'indiquer les options de requête OData facultatives ou paramètres de méthode REST personnalisant la réponse. |
| {headers} | Ce paramètre permet d'indiquer l'entêtes de requête permettant de personnaliser la requête. Ils peuvent être facultatifs ou obligatoires selon l'API. |
Après avoir effectué une demande, une réponse est renvoyée qui comprend :
| Partie | Description |
|---|---|
| Code d'état | Code d'état HTTP indiquant la réussite ou l'échec. Voir Codes d'état HTTP de Microsoft Graph API. |
| Message de réponse | Données demandées ou résultat de l'opération. Le message de réponse peut être vide pour certaines opérations. |
| @odata.nextLink | Si votre requête renvoie beaucoup de données, vous devez les parcourir en utilisant l'URL renvoyée dans @odata.nextLink. |
| Entêtes de réponse | Informations supplémentaires sur la réponse, telles que le type de contenu renvoyé et l'ID de la requête, que vous pouvez utiliser pour corréler la réponse à la requête. |
Méthodes HTTP
Microsoft Graph utilise la méthode HTTP de votre requête pour déterminer son action. Selon la ressource, l'API peut prendre en charge des opérations telles que des actions, des fonctions ou des opérations CRUD décrites ci-dessous.
| Méthode | Description |
|---|---|
| GET | Lire les données d'une ressource. |
| POST | Créez une nouvelle ressource ou effectuez une action. |
| PATCH | Mettre à jour une ressource avec de nouvelles valeurs ou insérer une ressource (créer si la ressource n'existe pas, mettre à jour sinon). |
| PUT | Remplacer une ressource par une nouvelle. |
| DELETE | Supprimer une ressource. |
Pour les méthodes CRUD GET et DELETE, aucun corps de requête n'est requis. Les méthodes POST, PATCH et PUT nécessitent un corps de requête, généralement spécifié au format JSON, contenant des informations supplémentaires, telles que les valeurs des propriétés de la ressource.
Important
Les requêtes d'écriture dans l'API de Microsoft Graph API ont une taille limite de 4 Mo.
Dans certains cas, la taille limite réelle des requêtes d'écriture est inférieure à 4 Mo. Par exemple, joindre un fichier à un événement utilisateur via POST /me/events/{id}/attachments a une taille limite de 3 Mo, car un fichier d'environ 3,5 Mo peut dépasser 4 Mo lorsqu'il est encodé en base64.
Les requêtes dépassant cette taille limite échouent avec le code d'état HTTP 413 et le message d'erreur «Entité de requête trop grande» ou «Charge utile trop grande».
Version
Microsoft Graph API est actuellement disponible en deux versions : v1.0 et bêta :
| Version | Description |
|---|---|
| v1.0 | La version v1.0 inclut les API généralement disponibles. Utilisez la version v1.0 pour toutes les applications de production. |
| beta | La version bêta inclut les API actuellement en préversion. Étant donné que des modifications importantes pourraient être apportées à nos API bêta, nous vous recommandons d'utiliser la version bêta uniquement pour tester les applications en développement ; n'utilisez pas les API bêta dans vos applications de production. |
Ressources
Une ressource peut être une entité ou un type complexe, généralement défini par des propriétés. Les entités se distinguent des types complexes par l'inclusion systématique d'une propriété id.
Votre URL inclura la ressource avec laquelle vous interagissez dans la requête, par exemple : moi, utilisateur, groupe, lecteur et site. Souvent, les ressources de niveau supérieur incluent également des relations, que vous pouvez utiliser pour accéder à des ressources supplémentaires, comme moi/messages ou moi/lecteur. Vous pouvez également interagir avec les ressources à l'aide de méthodes ; par exemple, pour envoyer un courriel, utilisez moi/sendMail.
Chaque ressource peut nécessiter des autorisations différentes pour y accéder. Vous aurez souvent besoin d'un niveau d'autorisation plus élevé pour créer ou mettre à jour une ressource que pour la lire. Pour plus d'informations sur les autorisations requises, consultez la rubrique de référence des méthodes.
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 acceptées par une méthode pour personnaliser sa réponse.
Vous pouvez utiliser des options de requête système OData facultatives pour inclure plus ou moins de propriétés que la réponse par défaut, filtrer la réponse pour les éléments correspondant à une requête personnalisée ou fournir des paramètres supplémentaires pour une méthode.
Par exemple, l'ajout du paramètre de filtre suivant limite les messages renvoyés à ceux dont la propriété emailAddress est jon@contoso.com :
| GET https://graph.microsoft.com/v1.0/me/messages?$filter=emailAddress eq 'jon@contoso.com' |
Outre les options de requête OData, certaines méthodes nécessitent des valeurs de paramètres spécifiées dans l'URL de requête. Par exemple, vous pouvez obtenir une liste d'événements survenus pendant une période donnée dans le calendrier d'un utilisateur en interrogeant la relation calendarView de cet utilisateur et en spécifiant les valeurs startDateTime et endDateTime de la période 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 |
Entêtes
Microsoft Graph API prend en charge les entêtes HTTP standard et les entêtes personnalisés.
Certaines API peuvent nécessiter l'inclusion d'entêtes supplémentaires dans la requête. Microsoft Graph API, quant à lui, renvoie toujours des entêtes obligatoires, tels que l'entête request-id dans la réponse. Certains en-têtes peuvent également être spécifiques à certaines API ou fonctionnalités. Par exemple, l'entête Retry-After est inclus lorsque votre application atteint les limites de limitation; ou l'en-tête Location est inclus pour les opérations de longue durée.
Les entêtes sont insensibles à la casse, conformément à la RFC 9110, sauf indication contraire explicite.
Graph Explorer
Graph Explorer est un outil web permettant de créer et de tester des requêtes à l'aide des API de Microsoft Graph API. Vous pouvez accéder à Graph Explorer à l'adresse : https://developer.microsoft.com/graph/graph-explorer.
Vous pouvez accéder aux données de démonstration sans vous connecter, ou vous connecter à votre propre locataire. Pour créer la requête, procédez comme suit :
- Sélectionnez la méthode HTTP.
- Sélectionnez la version de l'API que vous souhaitez utiliser.
- Saisissez la requête dans la zone de texte.
- Sélectionnez «Exécuter la requête».
Postman
Postman est un outil permettant de créer et de tester des requêtes à l'aide des API de Microsoft Graph API. Vous pouvez télécharger Postman à l'adresse : https://www.getpostman.com/. Pour interagir avec Microsoft Graph dans Postman, utilisez la collection Microsoft Graph API.