L’API Microsoft Graph : possibilités et exemples d’application avec WinDev
Microsoft Graph est une API REST unifiée mise à disposition par Microsoft. Elle permet d'accéder, de piloter et d'interagir avec toutes les ressources liées à Microsoft 365 (ex-Office 365) via un point d’entrée unique : utilisateurs, e-mails, documents, calendriers, sites SharePoint, etc.
1/ Pourquoi utiliser l’API Microsoft Graph ?
L’API Graph présente plusieurs avantages clés pour les développeurs et les intégrateurs :
- Point d’accès centralisé : Toutes les ressources (mails, utilisateurs, documents, etc.) sont accessibles selon un modèle unifié, ce qui facilite l’intégration et réduit la complexité une fois la logique maîtrisée.
- Une sécurité maîtrisée : L’utilisation de l’API nécessite une déclaration de l’application, ainsi que l’attribution de permissions spécifiques. De ce fait, lors de la demande d’un jeton, on sera limité à ses droits. Une application ne peut accéder qu’aux ressources pour lesquelles elle a été autorisée. Aucun jeton, aucun accès.
- Une intégration dans vos outils métier : Intégrer Microsoft Graph dans vos applications réalisées en WinDev permet de renforcer le lien entre les données générées par votre application et celles stockées ou traitées dans Microsoft 365
2/ Comment utiliser l’API Graph ?
- Étape 1 : Récupérer un jeton d’accès
Préalable à toute utilisation d’une ressource, la récupération du jeton se fait grâce à plusieurs paramètres
- URL d’obtention du jeton
- Id locataire
- Client ID (identifiant de l’application déclaré dans ENTRA)
- Client Secret
Ces paramètres sont récupérables suite à la création d'une application dédiée dans Microsoft Entra. Seuls les administrateurs du Tenant ou les administrateurs systèmes délégués peuvent le faire.
En retour, de l’appel on reçoit un JSON contenant le jeton :
{
"token_type": "Bearer",
"expires_in": 3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbG..."
}C’est ce jeton qui permet de passer à l’étape 2 : l’utilisation des ressources.
Exemple avec Windev pour récupérer un Jeton :
// Déclaration des variables
Config est un OAuth2Paramètres
Jeton est un AuthToken
// Initialisation des paramètres
Config.ClientID = "" // ClientID
Config.ClientSecret = "" // clientSecret
Config.URLToken = ""
Config.Scope = "https://graph.microsoft.com/.default"
Config.TypeRéponse = oauth2TypeRéponseToken
Config.TypeAutorisation = taApplicationCliente
Config.ParamètresSupplémentaires = "grant_type=client_credentials"
// Authentification
Jeton = AuthIdentifie(Config)
SI PAS Jeton.Valide ALORS
Erreur("Erreur de récupération du token" + RC + ErreurInfo(errComplet))
FIN
Note : Si le couple client_id/client_secret fonctionne très bien, Microsoft Entra limite sa validité à 3 ans maximum. Il faut donc prévoir des systèmes permettant la rotation de ces identifiants, ou bien utiliser à la place les certificats client et les assertions JWT correspondantes.
- Étape 2 : Appeler une ressource Microsoft 365
Les appels à une ressource se basent sur le modèle suivant :
https://graph.microsoft.com/{version}/{ressource}?[filtres]
Si on décompose l’URL, on retrouve :
- L’adresse URL unique
- Le numéro de version de l’API (v1.0 ou beta)
- La ressource à utiliser
- Les filtres éventuels (select ou filter)
Par exemple pour récupérer une liste (expéditeur et sujet) de mail pour l’utilisateur connecté :
https://graph.microsoft.com/v1.0/me/messages?$select=sender,subjectLe retour de l’appel permettra de récupérer un JSON sur la ressource que l’on interroge.
Exemple avec Windev pour lister les sites Sharepoint (on voit ici l’affectation du jeton pour la requête) :
qryGraph est un httpRequête
resGraph est un httpRéponse
qryGraph.AuthToken = jeton
qryGraph.URL = "https://graph.microsoft.com/v1.0/sites" // exemple de récupération des sites SharePoint
qryGraph.DuréeNonRéponse = 10 s
resGraph = qryGraph.Envoie()
SI ErreurDétectée ALORS
Erreur("Erreur à l'envoi de la requête", ErreurInfo(errComplet))
FIN
SI PartieEntière(resGraph.CodeEtat / 100) > 3 ALORS
Erreur("Erreur de retour", resGraph.Contenu)
FIN3/ Points de vigilance
L’API Graph est une option intéressante pour les développements. Sa couverture fonctionnelle et sa gestion des droits permettent de couvrir un large éventail de projets en garantissant au mieux la sécurité des accès. Attention néanmoins à certains points :
- Version utilisée : la version beta notamment évolue régulièrement, et certains mécanismes peuvent changer d’une version à l’autre
- Fonction utilisée : Certaines fonctions sont à utiliser avec prudence. Par exemple, déplacer un mail dans la corbeille (supprimer un mail dans le langage commun), n’a pas le même impact que la suppression de mail au sens de l’API (pas de passage par la corbeille).
4/ En résumé, l'API Graph comme solution gagnante
L’API Microsoft Graph est une solution puissante et sécurisée pour interagir avec l’écosystème Microsoft 365 depuis vos applications et notamment celles développées avec WinDev. Grâce à une interface centralisée et des contrôles d’accès robustes, elle s’adapte à un grand nombre de cas d’usage professionnels :
- Intégration d’e-mails,
- Synchronisation de calendriers,
- Gestion de documents,
- Supervision de comptes, etc.
Une idée de projet ? Contactez-nous
