Microsoft Graph API et SharePoint Framework (SPFx)

Introduction au Microsoft Graph API

L’API Microsoft Graph permet aux développeurs de se connecter à un seul point d’entrée unique (https://graph.microsoft.com) et pouvoir interagir avec les services de Microsoft 365.

La consommation de l’API se fait soit en REST soit en utilisant un des SDK mis à disposition par Microsoft (.NET, JavaScript, PHP, Android, etc.).

Si vous avez besoin de tester rapidement le Microsoft Graph API, Microsoft met à disposition le Graph Explorer. Vous pourrez exécuter des requêtes soit sur des exemples de données soit sur les données de votre tenant Office 365.

Aujourd’hui, il existe deux versions de l’API Microsoft Graph : la v.1.0 et la beta. Concernant la beta, c’est un aperçu des APIs qui risquent de basculer en 1.0. Il n’est pas recommandé de les utiliser en environnement de production mais uniquement à des fins de test.

Tout récemment, dans la rubrique Teamwork (Microsoft Teams), nous avons la possibilité de créer et paramétrer les équipes (onglets, apps, gestion des membres, channels, etc.). Cependant, la possibilité de lister les messages d’un channel est encore en bêta.

Quelques mots sur le SharePoint Framework (SPFx)

Le SharePoint Framework (ou SPFx) est un modèle de développement permettant de créer des nouvelles fonctionnalités sur SharePoint Online et SharePoint on-premises (2016 Feature Pack 2 et 2019). Il propose aussi aux développeurs de nouveaux outils de développement moderne.

Je ne vais pas m’étendre longtemps sur la présentation du SharePoint Framework, mon collègue Haythem Brigui l’a évoqué dans sa série sur le SharePoint Framework.

Interagir avec le Microsoft Graph à l’aide du SharePoint Framework

Prérequis

Dans ce qui va suivre, on va partir d’un projet SPFx sans framework JavaScript pour simplifier la démonstration. Il faut à minima la version 1.6 du SharePoint Framework. Si vous n’êtes pas sûr de la version du SharePoint Framework utilisée, voici comment procéder :

• Dans le cadre d’un projet existant

Vous pouvez ouvrir le fichier package.json du projet.

Dans la capture ci-dessous, je vérifie les versions des packages @microsoft/sp-* : c’est la version 1.4.1 de SPFx. Si je souhaite partir de ce projet, il faudra au moins migrer les packages npm de 1.4.1 vers 1.7.

• Dans le cadre d’un nouveau projet

Il faudra vérifier la version du package “@microsoft/generator-sharepoint”.
– Si le package a été installé globalement :

npm info @microsoft/generator-sharepoint version

– Si le package a été installé localement :

npm list --depth=0

Se connecter au Microsoft Graph

Pour interroger le Microsoft Graph et utiliser les données de votre tenant, vous avez dû voir qu’il fallait se connecter à votre tenant.

En SPFx, avec AadHttpClient et MSGraphClient, vous n’avez pas besoin de gérer la partie authentification. L’authentification à l’Azure Active Directory et la récupération de l’access token sont gérées par le SharePoint Framework avec la librairie ADAL.js (implicit flow OAuth 2.0).
ℹ MSAL JavaScript est encore en preview.

Néanmoins, côté développement, il faudra écrire les requêtes à envoyer au Microsoft Graph et demander les permissions nécessaires pour que la solution SPFx fonctionne correctement.

Consommer le Microsoft Graph API dans SPFx

Dans le cadre de projet de développement sur SharePoint Online, vous pouvez être amené à vouloir travailler avec d’autres services Microsoft 365. Par exemple, les services de la suite Office 365 tels que Outlook (mails, calendrier, contacts), OneDrive, Microsoft Teams ou Planner par exemple.
⚠ Pour la partie SharePoint, privilégiez au maximum l’API SharePoint REST.

Exemple de requête : récupération du titre du site courant

Depuis la version 1.4 du SharePoint Framework, il a été introduit en preview les classes AadHttpClient et MSGraphClient. Depuis la version 1.6, ces deux classes ne sont plus en preview.

AadHttpClient ou MSGraphClient pour Microsoft Graph ?

AadHttpClient permet d’exécuter des requêtes REST de manière asynchrone sur une application sécurisée par l’Azure AD.
MSGraphClient est similaire à AadHttpClient. Il permet d’interroger uniquement le Microsoft Graph et c’est une « version SPFx » du Microsoft Graph SDK. Pour faire des appels Microsoft Graph, vous pouvez donc utiliser AadHttpClient ou MSGraphClient.

D’un point de vue développement, la syntaxe pour interroger le Microsoft Graph est différente.

Dans ce qui va suivre, nous allons utiliser MSGraphClient.

MSGraphClient par la pratique

Dans cette partie, le but est d’afficher le nom des documents récents de l’utilisateur connecté. Ces documents peuvent provenir de OneDrive ou de sites SharePoint (Microsoft Teams compris).
Requête Microsoft Graph : https://graph.microsoft.com/v1.0/me/drive/recent

Téléchargement des typings pour Microsoft Graph (Optionnel)

Au niveau du projet, afin de pouvoir typer correctement les variables, vous pouvez télécharger le package npm @microsoft/microsoft-graph-types. Cela permet de typer les valeurs de retour en TypeScript et avoir de l’autocomplétion.

npm i @microsoft/microsoft-graph-types --save-dev

Écrire le code nécessaire pour interroger les API Microsoft Graph

Importer les dépendances nécessaires :

import { MSGraphClient } from '@microsoft/sp-http';

Dans le code de la web part, récupérer une instance de MSGraphClient via le contexte de la web part. Une fois l’instance récupérée, exécuter la requête Microsoft Graph souhaitée et traiter la valeur de réponse.

Au niveau des requêtes Microsoft Graph, pensez à optimiser au maximum vos requêtes. Si on souhaite afficher uniquement le nom des documents, on devrait plutôt exécuter la requête suivante : https://graph.microsoft.com/v1.0/me/drive/recent?$select=name

Voici un exemple de réponse dans le Graph Explorer : collection de données de type driveItem

Déclarer les permissions nécessaires

Si on se rend sur la documentation Microsoft, la requête « /me/drive/recent » nécessite à minima les permissions Files.Read (Permission type : Delegated (work or school account)).

Au niveau du projet, dans le dossier config, il faudrait ajouter la propriété webApiPermissionRequest dans le fichier package-solution.json. On doit ensuite indiquer la ressource Microsoft Graph et le niveau de permission.

Déploiement de la solution SPFx dans l’App Catalog

Vous pourrez ensuite créer la solution SPFx et la déployer dans l’App Catalog. Au déploiement, il est demandé si on est sûr de vouloir déployer la solution. De plus, un message d’avertissement indique qu’il faudra approuver les permissions demandées par la solution.

Une fois déployée, vérifier qu’aucun message d’erreur n’est visible (dernière colonne dans la liste).

Approbation des scopes de permissions demandés par la solution SPFx

Dernière étape avant de pouvoir tester la web part, on doit approuver les permissions demandées par la solution SPFx. Il faut donc se rendre sur le portail d’administration SharePoint.

ℹ Si vous avez un message vous demandant de tester le nouveau portail d’administration, basculez sur le nouveau portail.

Dans le menu de gauche, dans la catégorie Advanced, cliquez sur le lien API Management. Dans la liste qui s’affiche, approuvez la permission « Files.Read » requise par la solution.

ℹ Dans le cas où vous récupérer une solution SPFx d’un autre développeur, pensez à faire une revue du code de la solution afin de vérifier si les permissions demandées ont été correctement paramétrées. Par exemple, si la solution contient une web part qui affiche seulement la liste des documents récents, le niveau de permission doit être Files.Read au lieu de Files.ReadWrite.

⚠ Dans la page API Management, une fois qu’un scope de permissions a été approuvé, toutes les autres solutions SPFx existantes et futures solutions du tenant en bénéficieront aussi. En effet, côté Azure Active Directory, il n’y a qu’un seul service principal (SharePoint Online Client Extensibility Web Application Principal) pour gérer les permissions demandées dans la page API Management.

Aperçu du résultat

Il ne vous restera plus qu’à vous rendre sur un site SharePoint et ajouter l’application. Ensuite, il faudra créer une page et ajouter la web part. Le résultat de la requête s’affichera dans la console JavaScript (F12 dans votre navigateur web).

Si vous souhaitez afficher le résultat dans la web part, il faudra afficher le contenu dans la méthode Render de la web part. Le code source est disponible à la fin de l’article.

Se connecter à une API sécurisée par l’Azure AD sans AadHttpClient et MSGraphClient

Dans le cas où vous avez besoin de vous connecter à une API sécurisée avec l’Azure AD ou au Microsoft Graph sans pouvoir utiliser AadHttpClient et MSGraphClient, vous pouvez récupérer un access token via AadTokenProvider pour ensuite faire un appel aux APIs souhaitées.

ℹ AadHttpClient et MSGraphClient utilisent implicitement AadTokenProvider.

Exemple avec les fichiers récents :

ℹ Si vous avez dernièrement travaillé sur des bots Azure, vous pouvez passer l’access token au bot pour qu’il puisse effectuer ensuite les appels au Microsoft Graph.

SPFx , un framework uniquement pour SharePoint ?

Actuellement, la version du SharePoint Framework est la version 1.7 (sortie le 8 novembre 2018). Cette mise à jour est certainement l’une des plus grosses mises à jour depuis le lancement de SPFx.

Aujourd’hui, vous êtes de plus en plus sur Microsoft Teams plutôt que Skype for Business. Sachez qu’il sera possible de déployer une solution SPFx pour Microsoft Teams en tant qu’onglet. On pourra donc reprendre un développement SPFx dans Microsoft Teams et garder les habitudes de développement SPFx pour développer de nouvelles solutions sur Microsoft Teams.

ℹ La fonctionnalité est en preview pour la version 1.7 de SPFx.

A partir de cette fonctionnalité, le nom du framework risque peut-être de changer à l’avenir. Pour Office 365 Framework ?

Code source : Github