🎓Guide – Microsoft Graph – Comment bien démarrer sur l’API de Microsoft 365

Qu’est-ce que Microsoft Graph ? Comment commencer ? Où se former ?

Microsoft Graph est une passerelle permettant l’accès, l’échange et la manipulation de données sur l’ensemble des services de l’écosystème Micrsoft 365. Disposant d’une interface de communication unifiée, Microsoft Graph rend accessible les données disponibles dans Office 365, Windows 10 et Enterprise Mobility + Security : emails, discussions, calendriers, groupes, documents, alertes de sécurité, #Planner, #OneNote, #Teams, #Yammer, mais pas seulement ….

---

---

Il est également possible de réaliser des scénarios plus avancés avec l’utilisation des services Azures (Azure AI, Azure Bot Service, Azure Automation etc…). Ceci permet d’augmenter le champs des possibles et de rendre plus productif certains processus en passant par de l’automatisation pour optimiser la productivité, tout en permettant d’accéder à des données situées localement (OnPrem) à l’aide des connecteurs (DataGateway).

---

Microsoft Graph est composé de 3 briques :

• L’API Microsoft Graph
• Le composant Microsoft Graph data connect
• Les Connecteurs Microsoft Graph

---

---

👉Ce guide se concentrera sur le fonctionnement et l’utilisation de l’API Microsoft Graph.👈

---

Avant de se plonger sur l’API Microsoft Graph, son utilisation et les possibilités d’applications métiers, il est nécessaire de maîtriser les concepts liés au fonctionnement d’une API REST (ou RESTful).

Pour comprendre ce qu’est une API, découvrir les différents types d’API je vous invite à lire la documentation Microsoft suivante : https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design#introduction-to-rest

---

Pour pouvoir explorer le potentiel de l’API Microsoft Graph il faut tout d’abord assimiler les thèmes suivants :

L’authentification et l’authorisation : elles reposent sur l’utilisation du protocole OAuth 2.0. : https://oauth.net/2/ . Pour être à même de manipuler l’API Graph, il est nécessaire de savoir générer et utiliser des tokens (jeton d’accès); et de disposer d’une application Azure Active Directory possédant des droits sur l’API Graph.

Note 💡Un Guide 🎓 pas-à-pas est disponible ici pour créer votre application Azure ActiveDirectory dans votre environnement 👈

---

Les différentes méthodes (Verb) HTTP : Ces méthodes permettent d’interagir de différentes manières avec les endpoints de l’API Microsoft Graph.

• GET: Récupérer les données d’une ressource spécifiée.
• POST: Soumettre les données à traiter à une ressource spécifiée.
• PUT: Mettre à jour une ressource spécifiée.
• DELETE: Supprimer une ressource spécifiée.
• PATCH: Mettre à jour une partie d’une ressource spécifiée.

---

La syntaxe d’une requête :

{version} : l’API Graph dispose de 2 versions : la /v1.0 qui est celle supportée et recommandée par Microsoft; et la /beta qui permet de tester en avance des endpoint et les nouveautés à venir. ⚠️La version /beta n’est pas supportée dans les environnements de production.
Note 💡: Il est recommandé de suivre l’évolution de ces deux versions à l’aide du changelog.

{resource} : détermine le service sur lequel l’opération doit être effectuée. Exemple de resource : les utilisateurs, les groupes, les sites SharePoint, les fichiers …

{id} : (en option en fonction de la requête) permet de spécifier un objet précis dans le type de resource cible.

{property} : (en option en fonction de la requête) permet de spécifier une propriété sous-jacente à la ressource parent.

?{query-parameters} : (en option en fonction de la requête) permet de modifier la réponse renvoyée par la requête pour y réaliser un filtre ou une mise en forme.

Les endpoints : Ce sont des Points de terminaison qui permettent de récupérer ou de manipuler de la donnée. Voici un exemple de endpoints propres à l’API Microsoft Graph.

Opération	URL
GET mon profil	https://graph.microsoft.com/v1.0/me
GET mes fichiers	https://graph.microsoft.com/v1.0/me/drive/root/children
GET ma photo	https://graph.microsoft.com/v1.0/me/photo/$value
GET mon courrier	https://graph.microsoft.com/v1.0/me/messages
GET mon courrier Importance haute	https://graph.microsoft.com/v1.0/me/messages?$filter=importance%20eq%20'high'
GET mes événements du calendrier	https://graph.microsoft.com/v1.0/me/events
GET mon responsable	https://graph.microsoft.com/v1.0/me/manager
GET le dernier utilisateur pour modifier le fichier foo.txt	https://graph.microsoft.com/v1.0/me/drive/root/children/foo.txt/lastModifiedByUser
GET les groupes Office 365 dont je suis membre	https://graph.microsoft.com/v1.0/me/memberOf/$/microsoft.graph.group?$filter=groupTypes/any(a:a%20eq%20'unified')
GET des utilisateurs dans mon organisation	https://graph.microsoft.com/v1.0/users
GET les groupes de mon organisation	https://graph.microsoft.com/v1.0/groups
GET des personnes en relation avec moi	https://graph.microsoft.com/v1.0/me/people
GET les éléments qui me sont suggérés	https://graph.microsoft.com/beta/me/insights/trending
GET mes notes	https://graph.microsoft.com/v1.0/me/onenote/notebooks

La liste complète des endpoints est disponible dans la documentation “référence” de l’API Graph : https://docs.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0

---

Note 💡 : Dans le cas d’une utilisation sur un grand volume de données, les réponses faites par l’API Microsoft Graph sont généralement paginées par lot de 500 valeurs. Exemple : GET /users/ dans une organisation avec 2000 comptes, retournera une réponse avec 4 pages, 4 x500. A prendre en compte dans la conception de vos projets 🤓.

---

Enfin, la manipulation du language JSON : https://en.wikipedia.org/wiki/
ou à défaut des notions en XML sont nécessaires.

Après avoir appréhender l’ensemble des concepts ci-dessus il est désormais possible d’utiliser l’API Microsoft Graph. Pour cela, les 3 solutions les plus simples à disposition sont :

---

Graph explorer :

Microsoft nous a mis à disposition un outil pour jouer avec l’API Microsoft Graph. C’est le Graph Explorer. Ce dernier permet d’essayer des appels, découvrir les réponses et les valeurs, metas disponibles, celles qu’il est possible de manipuler ou non et ainsi comprendre l’utilisation de l’API.

---

---

PostMan :

PostMan est un outil permettant d’interroger des webservices et des APIs. Il est disponible sous Windows, Mac et Linux, dispose d’une interface graphique simple à prendre en main. Il permet entre autres de définir des environnements, créer des collections de requêtes, exporter et partager son travail. Il dispose également d’une forte communauté et d’une documentation riche en exemples.

---

---

PowerPlatform : Microsoft Flow

Microsoft Flow est l’une des briques de la PowerPlatform de Microsoft 365 et permet de créer des flux et processus de travails pour en automatiser les opérations. Cet outil est intégré à l’éco-système Office 365 et permet donc d’interagir de manière native avec les briques tel que SharePoint, Teams, OneDrive … et les données qui y sont présentes. Pour en savoir plus : 🎓 Guide 🚀Microsoft Flow – Comment bien démarrer ? 👈

---

---

” L’API est au CitizenDeveloper (ou PowerUser) ce que l’User Interface (UI) est à l’utilisateur “

---

En résumé l’API Microsoft Graph peut être comparée à une interface, simple d’accès, et disponible pour toute personne désirant construire une solution ayant besoin d’accéder ou d’interagir avec l’écosystème Office 365. De part sa facilité d’utilisation, sa standardisation et la richesse de sa documentation, les données présentes dans les environnements Microsoft Office 365 sont consommables aussi bien par des développeurs que des utilisateurs avancés (PowerUser; CitizenDeveloper).

---

Pourquoi Microsoft Graph ?

Microsoft Graph est une initiative de Microsoft qui vise à centraliser ses différentes API en un seul point. Le fait d’unifier les API va permettre de faciliter l’accessibilité des données que ce soit par des utilisateurs, des services informatiques ou des partenaires qui souhaitent concevoir des solutions génératrices de facturation.
Exemples de processus qu’il est possible de traiter via Microsoft Graph :

Traitement de l’ajout de nouveau collaborateur dans une organisation (on boarding). Il est également possible via la PowerPlatform ou via des développements spécifiques d’automatiser les processus de flux de travail.

L’intégration avec les données présentes dans les fichiers Excel mais également la manipulation des tableurs.

La conversion de fichiers.

---

N’étant pas un développeur et ayant appris par la pratique comment utiliser l’API Microsoft Graph, voici mon retour d’expérience et mes recommandations pour se former de manière efficace :

1. Commencer avec la série “30 days of Microsoft Graph” : Cette série est normalement à destination des développeurs, mais il est facile de suivre et de reproduire les exemples qui y sont présentés sans avoir de connaissances particulières en développement.
   Note 💡: Pensez à délaisser Notepad++ au profit de VisualStudio Code et à prendre le temps de lire la documentation pour comprendre la structures des appels, les headers JSON associés etc…
2. Approfondir ses connaissances autour de l’authentification et des permission pour bien maitriser les concepts et comprendre les notions de consentement, de bear token, refresh token, de session, de droit d’application et droit délégué.
   Note 💡: Privilégiez ici l’utilisation de PostMan pour vos tests autour de la génération, manipulation, utilisation de token. Pensez à utiliser un profile Chrome/Edge dédié pour ne pas avoir de chevauchement avec une éventuelle session MS/365 dans votre navigateur/profil principal
3. Tester des endpoints en utilisant de préférence la version 1.0 de l’API Graph pour commencer. Puis, adapter les exemples mis à disposition par Jeremy Thake dans la collection disponible sur GitHub : MicrosoftGraph Postman Collection
4. Finir par l’utilisation de Microsoft Flow et se construire un workflow de test disponible à tout moment pour découvrir le fonctionnement de nouveaux appels. Les outils de la PowerPlatform et plus particulièrement les briques logiques et algorithmiques de Flow permettent facilement d’imbriquer des appels et de stocker le(s) résultat(s) directement dans votre environnement Office365 et/ou Azure (OneDrive, SharePoint, Teams, Blob…)

Dans le cas de R&D ou d’un projet qui va vous demander d’être au quotidien sur des tests d’appels je vous invite fortement à configurer PostMan pour être à même de récupérer un token automatiquement et réaliser vos tests. L’un des avantages majeur de PostMan est la possibilité d’enregistrer votre travail, le partager et le tester dans différents environnement depuis le même client.

---

Afin de s’affranchir des limitations des droits que l’on peut vous accorder sur votre environnement de production, il est fortement conseiller de disposer de son propre environnement de test/dev/demo : Voir la procédure pas-à-pas ici pour créer votre propre environnement de Démo : 🎓 Guide – Comment créer un environnement Microsoft Office 365 de Démo

---

Microsoft Graph dispose également d’une communauté très active aussi bien côté Microsoft que côté partenaires.

👉Pour aller plus loin :
Page d’accueil du site de Microsoft Graph : Microsoft Graph Developer
Microsoft Graph sur GitHub : Microsoft Graph sur GitHub
Documentation Microsoft Graph : https://docs.microsoft.com/en-us/graph/overview
Vidéo : Présentation Microsoft Graph API (Ignite 2018)
Blog Serie : 30 Days of Microsoft Graph : https://aka.ms/30DaysMSGraph

Note💡: Le contenu est exact au moment de la publication. Toutefois, des mises à jour et des ajouts sont effectués quotidiennement par Microsoft, ce qui pourrait en modifier l’exactitude ou la pertinence. Veuillez garder cela à l’esprit lorsque vous utilisez mes articles.

N’hésitez pas à partager votre retour d’expérience dans les commentaires ou si vous avez des questions.