Microsoft Graph SDK

Utilisez cette skill lors de l'intégration de Microsoft Graph dans une application pour accéder aux données et services Microsoft 365.

Ancrez toujours l'implémentation dans la documentation actuelle de Microsoft Graph SDK et la version du SDK pour le langage cible plutôt que de vous fier à la mémoire seule.

Déterminez d'abord le langage cible

1. Utilisez le workflow .NET quand le projet contient des fichiers .cs, .csproj ou .sln, ou quand l'utilisateur demande des conseils en C#. Suivez references/dotnet.md.
2. Utilisez le workflow TypeScript / JavaScript quand le projet contient package.json, des fichiers .ts ou .js, ou quand l'utilisateur demande des conseils pour Node.js / navigateur. Suivez references/typescript.md.
3. Utilisez le workflow Python quand le projet contient .py, pyproject.toml ou requirements.txt, ou quand l'utilisateur demande des conseils en Python. Suivez references/python.md.
4. Si plusieurs langages sont présents, adaptez-vous au langage des fichiers en cours de modification ou demandez à l'utilisateur.

Consultez toujours la documentation en direct

• Présentation de Microsoft Graph : https://learn.microsoft.com/graph/overview
• Graph Explorer (testez les appels en direct) : https://developer.microsoft.com/graph/graph-explorer
• Référence des permissions Graph : https://learn.microsoft.com/graph/permissions-reference
• Utilisez les outils MCP Microsoft Docs quand disponibles pour récupérer les formes API actuelles et les exemples SDK.

Authentification — choisissez le bon modèle

Sélectionner le mauvais flux d'authentification est l'erreur la plus courante lors de l'intégration de Graph. Appliquez cet arbre de décision avant d'écrire du code d'authentification :

• N'utilisez jamais client credentials quand un contexte utilisateur est requis — Graph l'impose au niveau des permissions (application vs. delegated).
• Préférez DefaultAzureCredential dans les applications hébergées sur Azure ; elle essaie d'abord l'identité gérée et revient gracieusement au développement local.
• N'encodez jamais les secrets en dur. Utilisez des variables d'environnement, Azure Key Vault ou le Secret Manager.

Modèles d'utilisation du SDK principal

Construire le client

Construisez toujours GraphServiceClient une seule fois et réutilisez-le (il gère la mise en cache des tokens en interne).

Passez une credential de la bibliothèque Azure Identity — ne construisez jamais manuellement des clients HTTP bruts.

Effectuer des appels

• Utilisez l'API fluent builder : client.Users[userId].Messages.GetAsync(...).
• await toujours les appels asynchrones.
• Spécifiez $select pour limiter les champs retournés — Graph retourne de grandes charges utiles par défaut.
• Utilisez $filter côté serveur plutôt que de filtrer les collections retournées en mémoire.
• Utilisez $expand pour récupérer les ressources liées en un seul appel quand les relations sont petites.

Pagination

Graph pagine les collections. Ne supposez jamais que tous les éléments arrivent en une seule réponse :

• Vérifiez la présence de @odata.nextLink sur la réponse.
• Utilisez le helper PageIterator du SDK (disponible dans les trois SDKs) pour parcourir les pages automatiquement.
• Définissez $top pour contrôler la taille de la page (le maximum varie par ressource, typiquement 999).

Modèles avancés

Requêtes batch

Combinez jusqu'à 20 appels Graph indépendants en une seule requête HTTP en utilisant l'endpoint $batch. Utilisez le batching quand :

• Vous initialisez les données pour un tableau de bord ou un agent qui a besoin de plusieurs ressources d'avance.
• Vous réduisez la latence dans les opérations à grand nombre d'appels.

Les réponses batch arrivent désordonnées — faites-les correspondre avec le champ id que vous avez assigné à chaque requête.

Delta queries

Utilisez les delta queries pour synchroniser les changements de façon incrémentale au lieu de sonder des collections complètes :

• Premier appel : GET /users/delta retourne tous les éléments + un @odata.deltaLink.
• Appels suivants : utilisez le deltaLink pour recevoir uniquement ce qui a changé depuis la dernière synchronisation.
• Supporté sur : users, groups, messages, calendar events, Teams channels, et bien d'autres.
• Stockez le deltaLink de façon durable (base de données, blob) entre les exécutions de synchronisation.

Notifications de changement (webhooks)

Abonnez-vous aux changements de ressources avec POST /subscriptions :

• Graph envoie les événements de changement à votre URL de notification HTTPS.
• Les abonnements expirent — renouvelez-les avant expirationDateTime (le maximum varie par ressource ; typiquement 1–3 jours pour mail/calendar, jusqu'à 4230 minutes pour users/groups).
• Validez la poignée de main de l'abonnement : Graph envoie un paramètre de requête validationToken lors de la création — retournez-le en tant que texte simple avec HTTP 200.
• Utilisez les notifications de cycle de vie (notificationUrl + lifecycleNotificationUrl) pour gérer les événements manqués et la réautorisation.
• Pour les scénarios à haut volume, préférez change notifications with resource data (nécessite une configuration de chiffrement supplémentaire).

Throttling

Graph throttle agressivement. Gérez toujours HTTP 429 :

• Lisez l'en-tête Retry-After — il spécifie les secondes exactes à attendre, pas un backoff fixe.
• Le middleware de retry intégré du SDK gère 429 automatiquement quand configuré ; activez-le explicitement.
• Évitez les modèles fan-out qui frappent Graph avec des centaines de requêtes parallèles ; utilisez plutôt le batching ou le queuing.

Permissions

Obtenez les permissions correctes avant d'écrire du code d'authentification — les mauvais scopes résultent en erreurs 403 qui sont difficiles à déboguer plus tard.

• Les permissions d'application s'exécutent sans utilisateur (daemon / service). Elles nécessitent le consentement administrateur.
• Les permissions delegated s'exécutent dans le contexte d'un utilisateur connecté. Certaines nécessitent le consentement administrateur.
• Demandez les permissions minimales nécessaires. La référence des permissions de Graph liste les options de least-privilege pour chaque opération.
• Utilisez Graph Explorer pour tester quelles permissions un appel exige réellement avant de coder.
• Dans les enregistrements d'application Azure : accordez les permissions API → Microsoft Graph → sélectionnez le type (Application ou Delegated) → accordez le consentement administrateur où nécessaire.

Ressources Graph courantes — référence rapide

De manière similaire, utilisez l'API fluent du SDK pour naviguer vers ces ressources dans le code.

Workflow

1. Déterminez le langage cible et lisez le fichier de référence correspondant.
2. Identifiez le scénario d'authentification et choisissez le flux correct dans le tableau ci-dessus.
3. Récupérez la documentation actuelle du SDK et les exemples de Graph Explorer avant de faire des choix d'implémentation.
4. Appliquez les permissions de least-privilege — confirmez dans la référence des permissions de Graph.
5. Implémentez la pagination dès le départ — ne supposez pas des réponses mono-page.
6. Activez le middleware de retry pour le throttling dès le premier jour.
7. Pour les scénarios de synchronisation, préférez les delta queries au polling.
8. Utilisez les noms de packages, la configuration du fournisseur d'authentification et les modèles de code spécifiques au langage du fichier de référence choisi.

Critères d'achèvement

• Le flux d'authentification correspond au scénario (pas de recours par défaut à client credentials pour les appels avec contexte utilisateur).
• GraphServiceClient est construit une seule fois et réutilisé.
• Toutes les lectures de collections gèrent la pagination.
• Le throttling (429) est géré via le middleware de retry ou une logique explicite de Retry-After.
• Les permissions sont limitées au minimum requis.
• Aucun secret ou credential n'est encodé en dur.
• Le code correspond aux modèles de version SDK actuels pour le langage sélectionné.