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.
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.
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.
Pour utiliser l’application Graph Explorer avec les données d’un environnement Office 365 il faut se connecter : “Sign in with Microsoft”.
Il est nécessaire d’utiliser un compte membre de l’organisation cible.
Lors de la première connexion, le processus de permission et de consentement s’applique (voir concepts). Par défaut les droits accordés sont ceux propres au compte utilisé.
Il est également possible pour des comptes administrateurs de réaliser un consentement de niveau supérieur et avoir accès à l’ensemble des données de l’organisation à travers ce compte.
Il est possible de voir l’ajout du compte dans l’application via l’administration Azure Active Directory > Entreprise Applications – All applications > Graph explorer > Users & Groups.
Il est possible de voir l’ajout des permissions dans l’application via l’administration Azure Active Directory > Entreprise Applications – All applications > Graph explorer > Users & Groups.
Ecran d’accueil une fois le compte connecté.
Pour avoir accès à l’ensemble des exemples de requêtes il faut utiliser le bouton “show more samples” dans le menu de gauche.
Pour avoir accès à l’historique d’execution des requêtes, il faut utiliser le bouton “show more” dans le menu de gauche sous “History”.
Ecran d’ajout/suppression d’exemple de requêtes triées par catégories.
Vue complète de l’historique d’execution des requêtes.
Il est possible de choisir le type de methode HTTP pour la requête.
Il est possible de choisir le type de version de l’API Graph que va utiliser la requête.
Il est possible d’ajouter un “body” à être utiliser avec la requête.
Il est possible d’ajouter un/des “headers” associé(s) à la requête.
Lors de l’execution d’une requête (bouton “Run Query”), le résultat s’affiche au format JSON dans l’encart “Response Preview”.
Il est possible également de lire les “Headers” de la réponse.
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.
Ecran de connexion : Pour utiliser PostMan il est recommandé d’avoir un compte actif afin de pouvoir sauvegarder (synchronisation) son travail et pouvoir le retrouver facilement.
Pour créer une requête il faut utiliser le menu/block : Request.
Pour utiliser PostMan et être à même d’interroger l’API Microsoft Graph il est nécessaire de générer un token d’accès (voir partie sur les tokens).
Note ?: Il peut être nécessaire de valider “manuellement” le consentement lors d’une première utilisation (ou lors de phases de tests).
Lors de la création de la requête, il faut renseigner les informations nécessaires dans les Headers (key/value).
Le résultat de la requête s’affiche via la section “Body”.
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 ? ?
Création d’un Flow à déclenchement manuel
Note ? : si vous ne disposez pas d’une licence Microsoft Flow P1, il est possible d’activer une license d’essai. L’utilisation d’une action de type requêtes HTTP nécessite une licence Microsoft Flow Premium.
⚠️ Attention au changement concernant les licences de la PowerPlatform prévu pour entrer en vigueur à partir d’Octobre 2019 >>> LINK TWITTER <<<
Détail des actions du workflow pour effectuer un appel à l’API Graph.
Résultat de l’execution du workflow.
Réponse de l’appel à l’API Graph via l’historique d’execution du Flow. Comme pour le Graph Explorer et PostMan, la réponse se trouve dans le Body de la réponse.
” 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 :
- 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… - 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 - 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
- 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.
Actuellement en cours de rédaction…?
?Retours d’expériences et recommandations sur #Flow et la #PowerPlatform
?Présentation d’un outil 3rd party pour la gestion de vos #WorkFlow dans un environnement avancé
?Microsoft Teams Governance : Flow, un outil au service de la gouvernance, l’automatisation et le reporting.
