Meilleures pratiques d’utilisation de Microsoft Graph

  • Article

Cet article décrit les meilleures pratiques que vous pouvez appliquer pour aider vos applications à tirer le meilleur parti de Microsoft Graph, qu’il s’agisse d’en apprendre davantage sur Microsoft Graph, d’améliorer les performances des applications ou de rendre votre application plus fiable pour les utilisateurs finaux.

Utilisation de l’Afficheur Graph pour découvrir l’API

L’Afficheur Graph vous permet d’explorer facilement les données disponibles via Microsoft Graph. Il vous permet également de construire les requêtes REST (avec prise en charge totale des opérations CRUD), d’adapter les en-têtes des requêtes HTTP et de consulter les réponses de données. Pour vous aider à commencer, l’Afficheur Graph vous propose plusieurs exemples de requêtes.

Testez les nouvelles API avant de les intégrer dans votre application.

Authentification

Pour accéder aux données via Microsoft Graph, votre application doit acquérir un jeton d’accès OAuth 2.0 et le présenter à Microsoft Graph dans l’une des options suivantes :

  • soit dans l’en-tête de la requête HTTP Authorisation, sous la forme d’un jeton du porteur ;
  • soit dans le constructeur client Graph, si vous utilisez une bibliothèque cliente Microsoft Graph.

Utilisez l’API Bibliothèque d’authentification de Microsoft, MSAL pour acquérir le jeton d’accès à Microsoft Graph.

Appliquez les meilleures pratiques suivantes pour obtenir le consentement et l’autorisation dans votre application :

  • Appliquer les privilèges minimum. Accordez aux utilisateurs et aux applications uniquement l’autorisation privilégiée la plus basse dont ils ont besoin pour appeler l’API. Vérifiez la section autorisations dans les rubriques de méthode (par exemple, consultez création d’un utilisateur), puis choisissez les autorisations les moins privilégiées. Par exemple, si l’application lit uniquement le profil de l’utilisateur actuellement connecté, accordez user.Read au lieu de User.ReadBasic.All. Si une application ne lit pas le calendrier de l’utilisateur, ne lui accordez pas l’autorisation Calendars.Read . Pour obtenir la liste complète des autorisations, consultez l’article Référence des autorisations de Microsoft Graph.

  • Utilisez le type d’autorisation adapté aux scénarios. Évitez d’utiliser à la fois l’application et les autorisations déléguées dans la même application. Si vous créez une application interactive où un utilisateur est connecté, votre application doit utiliser des autorisations déléguées. Si, toutefois, votre application s’exécute sans utilisateur connecté, comme un service ou un démon d’arrière-plan, votre application doit utiliser des autorisations d’application.

    Attention

    Remarque : l’utilisation des autorisations d’application dans le cadre de scénarios interactifs peut exposer votre application à des risques de sécurité et de conformité. Il peut élever par inadvertance les privilèges d’un utilisateur pour accéder aux données, en contournant les stratégies configurées par un administrateur.

  • Configurez votre application rigoureusement. Les utilisateurs finaux et les administrateurs, ainsi que l’adoption et la sécurité de l’application, en bénéficieront directement. Par exemple :

    • Le nom, le logo, le domaine, l’état de vérification de l’éditeur, la déclaration de confidentialité et les conditions d’utilisation de votre application s’affichent dans le consentement et d’autres expériences. Configurez ces paramètres avec soin afin qu’ils soient compris par vos utilisateurs finaux.
    • Pensez aux personnes qui donneront leur consentement pour utiliser votre application (utilisateurs finaux ou administrateurs) et configurez votre application pour demander des autorisations adaptées.
    • Veillez à comprendre la différence entre consentement statique, dynamique et incrémentiel.

  • Pensez aux applications mutualisées. Attendez-vous à ce que les clients disposent de plusieurs contrôles d’application et de consentement dans différents états. Par exemple :

    • Les administrateurs client peuvent désactiver la possibilité pour les utilisateurs finaux de donner leur consentement aux applications. Dans ce cas, un administrateur devra donner son consentement au nom de leurs utilisateurs.
    • Les administrateurs client peuvent définir des stratégies d’autorisation personnalisées. Par exemple, ils peuvent empêcher des utilisateurs de lire les profils d’autres utilisateurs ou limiter la création de groupes en libre-service à un ensemble limité d’utilisateurs. Dans ce cas, votre application doit s’attendre à gérer 403 Forbidden réponse d’erreur lorsqu’elle agit pour le compte d’un utilisateur.

Traitement efficace des réponses

Selon les requêtes envoyées à Microsoft Graph, vos applications doivent être prêtes à traiter différents types de réponses. Voici quelques exemples de pratiques importantes à suivre pour vous assurer que votre application se comporte de manière prévisible et fiable pour vos utilisateurs finaux.

Pagination

Lors de l’interrogation d’une collection de ressources, vous devez vous attendre à ce que Microsoft Graph retourne le jeu de résultats dans plusieurs pages, en raison des limites de taille de page côté serveur. Quand un jeu de résultats s’étend sur plusieurs pages, Microsoft Graph renvoie une propriété @odata.nextLink dans la réponse contenant une URL vers la page de résultats suivante.

Par exemple, le fait de répertorier les messages des utilisateurs connectés :

GET https://graph.microsoft.com/v1.0/me/messages

renvoie une réponse contenant une propriété @odata.nextLink, si le jeu de résultats dépasse la limite de taille des pages côté serveur.

"@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$skip=23"

Remarque

Votre application doit toujours gérer la possibilité que les réponses soient paginées par nature et utiliser la propriété @odata.nextLink pour obtenir le jeu de résultats paginé suivant, jusqu’à ce que toutes les pages du jeu de résultats aient été lues. La dernière page ne contiendra aucune propriété @odata.nextLink. Saisissez l’URL complète dans la propriété @odata.nextLink de votre requête pour la page de résultats suivante, en traitant l’URL complète comme une chaîne opaque.

Pour en savoir plus, consultez l’article relatif à la pagination.

Traitement des erreurs attendues

Même si votre application devrait traiter toutes les réponses d’erreur (comprises entre 400 et 500), accordez une attention particulière aux erreurs et réponse attendues répertoriées dans le tableau suivant.

Rubrique Code d’erreur HTTP Meilleures pratiques
L’utilisateur n’a pas accès 403 Si votre application fonctionne correctement, cette erreur peut survenir même si elle a obtenu les autorisations nécessaires via une expérience de consentement. Dans ce cas, il est fort probable que l’utilisateur connecté ne dispose pas des privilèges pour accéder à la ressource demandée. Votre application doit générer une erreur générique « Accès refusé » à l’utilisateur connecté.
Introuvable 404 Dans certains cas, il est impossible de trouver une ressource demandée. Par exemple, il est possible qu’une ressource n’existe pas, car elle n’a pas encore été configurée (par exemple, la photo d’un utilisateur) ou car elle a été supprimée. Certaines ressources supprimées peuvent être entièrement restaurées dans les 30 jours suivant la suppression (notamment, les ressources d’utilisateur, de groupe et d’application). Votre application doit également prendre ce critère en compte.
Limitation 429 Les API peuvent limiter les requêtes à tout moment pour diverses raisons. Votre application doit donc toujours être prête à traiter les réponses d’erreur 429. Cette réponse d’erreur inclut le champ Retry-After dans l’en-tête de la réponse HTTP. L’interruption des requêtes en utilisant le retard Retry-After est le moyen le plus rapide de récupération à la suite d’une limitation. Pour en savoir plus, consultez l’article relatif à la limitation.
Service non disponible 503 Cette erreur indique vraisemblablement que le service est occupé. Nous vous recommandons d’adopter une stratégie d’interruption semblable à celle utilisée pour l’erreur 429. De plus, pensez toujours à envoyer des requêtes de nouvelle tentative via une nouvelle connexion HTTP.

Gérer de futurs membres dans des énumérations modulables

L’ajout de membres à des énumérations existantes peut arrêter des applications utilisant déjà ces énumérations. Les énumérations modulables sont un mécanisme utilisé par l’API Microsoft Graph pour ajouter de nouveaux membres aux énumérations existantes sans entraîner de changement cassant pour les applications.

Les énumérations modulables ont un membre commun sentinelle appelé unknownFutureValue qui sépare les membres connus ayant été initialement définis dans l’énumération et les membres inconnus qui sont ajoutés par la suite ou qui sont définis dans le futur. De manière interne, les membres connus sont mappés vers des valeurs numériques inférieures au membre sentinelles et les membres inconnus ont une valeur supérieure au membre sentinelle. La document d’une énumération modulable répertorie les valeurs chaîne possibles dans l’ordre croissant : les membres connus suivis par unknownFutureValue, suivis par les membres inconnus. Comme d’autres types d’énumération, vous devez toujours référencer les membres des énumérations modulables par leur valeur chaîne.

Par défaut, une opération OBTENIR renvoie uniquement les membres connus pour les propriétés des types d’énumération modulables et votre application doit uniquement gérer les membres connus. Si vous créez votre application pour qu’elle gère également les membres inconnus, vous pouvez accepter de recevoir ces membres en utilisant un en-tête de requête Prefer HTTP :

Prefer: include-unknown-enum-members

Stockage des données localement

Dans la mesure du possible, votre application doit appeler Microsoft Graph pour extraire des données en temps réel selon ses besoins. Mettez en cache ou stockez localement les données uniquement si un scénario spécifique l’exige, si ce cas d’utilisation est couvert par vos conditions d’utilisation et votre politique de confidentialité et s’il ne viole pas les conditions d’utilisation des API Microsoft. Votre application doit également implémenter des stratégies de rétention et de suppression des données adaptées.

Optimisations

En règle générale, pour des raisons de performances voire même de sécurité ou de confidentialité, vous ne devez extraire que les données dont votre application a réellement besoin.

Utilisations prévues

Choisissez uniquement les propriétés dont votre application a réellement besoin pour éviter le trafic réseau et le traitement de données inutiles dans votre application (et dans le service).

Remarque

Utilisez le paramètre de requête $select pour limiter les propriétés retournées par une requête à celles requises par votre application.

Par exemple, lorsque vous récupérez les messages de l’utilisateur connecté, vous pouvez indiquer que seules les propriétés from et subject doivent être renvoyées :

GET https://graph.microsoft.com/v1.0/me/messages?$select=from,subject

Lorsque vous effectuez une requête GET sans utiliser $select pour limiter la quantité de données de propriétés, Microsoft Graph inclut une propriété @microsoft.graph.tips qui fournit une recommandation de bonne pratique pour l’utilisation $select similaire au message suivant :

"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",

Obtention de réponses minimales

Pour certaines opérations, par exemple, PUT et PATCH (et dans certains cas, POST), si votre application n’a pas besoin d’utiliser une réponse de charge utile, vous pouvez demander à l’API de renvoyer le minimum de données. Notez que certains services retournent déjà une 204 No Content réponse pour les opérations PUT et PATCH.

Remarque

Demandez des réponses de représentation minimale à l’aide de l’en-tête Prefer défini sur return=minimal, lorsque pris en charge. Pour les opérations de création, l’utilisation de cet en-tête peut ne pas être appropriée, car votre application peut s’attendre à obtenir le service généré id pour l’objet nouvellement créé dans la réponse.

Suivi des modifications : requête delta et notifications webhook

Si votre application doit connaître les modifications apportées aux données, vous pouvez recevoir une notification webhook dès que certaines données sont modifiées. Cette méthode est plus efficace que la méthode d’interrogation, même effectuée de façon régulière.

Utilisez les notifications webhook pour recevoir des notifications Push quand des données sont modifiées.

Si votre application doit mettre en cache ou stocker localement les données Microsoft Graph, et tenir ces données à jour ou suivre les modifications apportées aux données pour tout autre raison, nous vous recommandons d’utiliser une requête delta. Ainsi, votre application n’aura pas besoin d’effectuer un nombre excessif de calculs pour récupérer des données que votre application possède déjà. De plus, cela limitera le trafic réseau et réduira la probabilité d’atteindre un seuil de limitation.

Utilisez une requête delta pour tenir des données à jour.

Utilisation de la requête delta avec les webhooks

Les webhooks et la requête delta fonctionnent souvent mieux ensemble, alors que l’utilisation d’une requête delta seule nécessite l’identification du bon intervalle d’interrogation. Un intervalle trop court peut générer des réponses vides qui gaspillent les ressources et un intervalle trop long peut aboutir à des données périmées. Si vous utilisez les notifications webhook comme déclencheur pour appeler une requête delta, vous profitez des atouts des deux fonctionnalités.

Utilisez les notifications webhook comme déclencheur pour appeler une requête delta. Vérifiez également que votre application possède un seuil d’interrogation de sécurité, au cas où aucune notification ne serait déclenchée.

Traitement par lots

Le traitement par lots JSON permet d’optimiser votre application en combinant plusieurs requêtes dans un seul objet JSON. La combinaison des requêtes individuelles dans une requête de lots unique permet à l’application de limiter la latence du réseau et de conserver les ressources de connexion.

Utilisez le traitement par lots quand une latence majeure du réseau peut avoir des répercussions importantes sur les performances de votre applications.

Fiabilité et prise en charge

Pour garantir la fiabilité et faciliter la prise en charge de votre application :

  • Utilisez TLS 1.2 pour prendre en charge toutes les fonctionnalités de Microsoft Graph. Pour plus d’informations sur Microsoft Graph TLS 1.0 et 1.1, voir Activer la prise en charge de TLS 1.2dans votre environnement.
  • Respectez la durée de vie (TTL) du DNS et configurez la durée de vie de connexion correspondant à celle du DNS. Ainsi, la disponibilité de votre application est garantie en cas de basculements.
  • Ouvrez les connexions à toutes les réponses DNS publiées.
  • Générez un GUID unique et envoyez-le sur chaque demande REST de Microsoft Graph. Microsoft pourra ainsi examiner plus facilement les erreurs si vous devez signaler un problème survenu avec Microsoft Graph.
    • Sur chaque demande envoyée à Microsoft Graph, générez un GUID unique, envoyez-le dans l’en-tête de demande HTTP client-request-id et consignez-le également dans les journaux de votre application.
    • Consignez toujours et request-idDate à partir des en-têtes de réponse HTTP. Ces éléments, ainsi que leclient-request-id, sont nécessaires pour signaler des problèmes dans Microsoft Q&A ou au support Microsoft.