Meilleures pratiques d’utilisation de Microsoft GraphBest practices for working with Microsoft Graph

Cet article décrit les meilleures pratiques à adopter pour que vos applications tirent le meilleur parti de Microsoft Graph. Pour cela, vous pouvez explorer le fonctionnement de Microsoft Graph, optimiser les performances de votre application ou proposer une application plus fiable aux utilisateurs finaux.This article describes best practices that you can apply to help your applications get the most out of Microsoft Graph - whether that involves learning about Microsoft Graph, improving app performance, or making your application more reliable for end users.

Utilisation de l’Afficheur Graph pour découvrir l’APIUse Graph Explorer to get to know the API

L’Afficheur Graph vous permet d’explorer facilement les données disponibles via Microsoft Graph.The easiest way to start exploring the data available through Microsoft Graph is to use Graph Explorer. 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.Graph Explorer lets you craft REST requests (with full CRUD support), adapt the HTTP request headers, and see the data responses. Pour vous aider à commencer, l’Afficheur Graph vous propose plusieurs exemples de requêtes.To help you get started, Graph Explorer also provides a set of sample queries.

Testez les nouvelles API avant de les intégrer dans votre application.Experiment with new APIs before you integrate them into your application.

AuthentificationAuthentication

Pour accéder aux données dans Microsoft Graph, votre application doit acquérir un jeton d’accès OAuth 2.0 et le présenter à Microsoft Graph :To access the data in Microsoft Graph, your application will need to acquire an OAuth 2.0 access token, and present it to Microsoft Graph in either of the following:

  • soit dans l’en-tête de la requête HTTP Authorisation, sous la forme d’un jeton du porteur ;The HTTP Authorization request header, as a Bearer token
  • soit dans le constructeur client Graph, si vous utilisez une bibliothèque cliente Microsoft Graph.The graph client constructor, when using a Microsoft Graph client library

Utilisez l’API Bibliothèque d’authentification de Microsoft, MSAL pour acquérir le jeton d’accès à Microsoft Graph.Use the Microsoft Authentication Library API, MSAL to acquire the access token to Microsoft Graph.

Appliquez les meilleures pratiques suivantes pour obtenir le consentement et l’autorisation dans votre application :Apply the following best practices for consent and authorization in your app:

  • Utilisez des autorisations selon le principe des privilèges minimum.Use least privilege. Demandez uniquement les autorisations absolument nécessaires et uniquement quand vous en avez besoin.Only request permissions that are absolutely necessary, and only when you need them. Pour les API appelées par votre application, consultez la section relative aux autorisations dans les rubriques des méthodes (par exemple, Créer un utilisateur), puis sélectionnez les autorisations ayant le moins de privilèges.For the APIs your application calls, check the permissions section in the method topics (for example, see creating a user, and choose the least privileged permissions. Pour obtenir la liste complète des autorisations, consultez l’article Référence des autorisations de Microsoft Graph.For a full list of permissions, see permissions reference.

  • Utilisez le type d’autorisation adapté aux scénarios.Use the correct permission type based on scenarios. Si vous créez une application interactive où un utilisateur est connecté, votre application doit utiliser des autorisations déléguées. En d’autres termes, l’application délègue des autorisations pour agir au nom de l’utilisateur connecté quand elle appelle Microsoft Graph.If you're building an interactive application where a signed in user is present, your application should use delegated permissions, where the application is delegated permission to act as the signed-in user when making calls to Microsoft Graph. 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.If, however, your application runs without a signed-in user, such as a background service or daemon, your application should use application permissions.

    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é.Note: Using application permissions for interactive scenarios can put your application at compliance and security risk. Cela peut élever accidentellement le niveau des privilèges d’un utilisateur pour accéder aux données et ainsi contourner les stratégies configurées par l’administrateur.It can inadvertently elevate a user's privileges to access data, circumnavigating policies configured by an administrator.

  • Configurez votre application rigoureusement.Be thoughtful when configuring your app. Les utilisateurs finaux et les administrateurs, ainsi que l’adoption et la sécurité de l’application, en bénéficieront directement.This will directly affect end user and admin experiences, along with application adoption and security. Par exemple :For example:

    • La déclaration de confidentialité, les conditions d’utilisation, le nom, le logo et le domaine de votre application s’afficheront dans l’expérience de consentement, entre autres. Ainsi, prenez le temps de les configurer correctement pour que ces informations soient comprises par vos utilisateurs finaux.Your application's privacy statement, terms of use, name, logo and domain will show up in consent and other experiences - so make sure to configure these carefully so they are understood by your end-users.
    • 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.Consider who will be consenting to your application - either end users or administrators - and configure your application to request permissions appropriately.
    • Assurez-vous que vous comprenez bien la différence entre consentement statique, dynamique et incrémentiel.Ensure that you understand the difference between static, dynamic and incremental consent.
  • Pensez aux applications mutualisées.Consider multi-tenant applications. Attendez-vous à ce que les clients disposent de plusieurs contrôles d’application et de consentement dans différents états.Expect customers to have various application and consent controls in different states. Par exemple :For example:

    • Les administrateurs client peuvent désactiver la possibilité pour les utilisateurs finaux de donner leur consentement aux applications.Tenant administrators can disable the ability for end users to consent to applications. Dans ce cas, un administrateur devra donner son consentement au nom de leurs utilisateurs.In this case, an administrator would need to consent on behalf of their users.
    • 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.Tenant administrators can set custom authorization policies such as blocking users from reading other user's profiles, or limiting self-service group creation to a limited set of users. Dans ce cas, votre application devra traiter des réponses d’erreur 403 quand elle agit au nom d’un utilisateur.In this case, your application should expect to handle 403 error response when acting on behalf of a user.

Traitement efficace des réponsesHandle responses effectively

Selon les requêtes envoyées à Microsoft Graph, vos applications doivent être prêtes à traiter différents types de réponses.Depending on the requests you make to Microsoft Graph, your applications should be prepared to handle different types of responses. 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.The following are some of the most important practices to follow to ensure that your application behaves reliably and predictably for your end users.

PaginationPagination

Quand vous interrogez une collection de ressources, attendez-vous à ce que Microsoft Graph renvoie le jeu de résultats dans plusieurs pages, en raison des limites de taille des pages côté serveur.When querying a resource collection, you should expect that Microsoft Graph will the return result set in multiple pages, due to server-side page size limits. 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.When a result set spans multiple pages, Microsoft Graph returns an @odata.nextLink property in the response that contains a URL to the next page of results.

Par exemple, le fait de répertorier les messages des utilisateurs connectés :For example, listing the signed-in users messages:

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.Would return a response containing an @odata.nextLink property, if the result set exceeds the server-side page size limit.

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

Remarque : votre application doit toujours envisager la possibilité que les réponses sont paginées par nature, et elle doit utiliser la propriété @odata.nextLink pour obtenir le jeu de résultats paginés suivant, jusqu’à ce que toutes les pages du jeu de résultats aient été lues.Note: Your application should always handle the possibility that the responses are paged in nature, and use the @odata.nextLink property to obtain the next paged set of results, until all pages of the result set have been read. La dernière page ne contiendra aucune propriété @odata.nextLink.The final page will not contain an @odata.nextLink property. 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.You should include the entire URL in the @odata:nextLink property in your request for the next page of results, treating the entire URL as an opaque string.

Pour en savoir plus, consultez l’article relatif à la pagination.For more details, see paging.

Traitement des erreurs attenduesHandling expected errors

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.While your application should handle all error responses (in the 400 and 500 ranges), pay special attention to certain expected errors and responses, listed in the following table.

RubriqueTopic Code d’erreur HTTPHTTP error code Meilleures pratiquesBest practice
L’utilisateur n’a pas accèsUser does not have access 403403 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.If your application is up and running, it could encounter this error even if it has been granted the necessary permissions through a consent experience. Dans ce cas, il est fort probable que l’utilisateur connecté ne dispose pas des privilèges pour accéder à la ressource demandée.In this case, it's most likely that the signed-in user does not have privileges to access the resource requested. Votre application doit générer une erreur générique « Accès refusé » à l’utilisateur connecté.Your application should provide a generic "Access denied" error back to the signed-in user.
IntrouvableNot found 404404 Dans certains cas, il est impossible de trouver une ressource demandée.In certain cases, a requested resource might not be found. 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.For example a resource might not exist, because it has not yet been provisioned (like a user's photo) or because it has been deleted. 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.Some deleted resources might be fully restored within 30 days of deletion - such as user, group and application resources, so your application should also take this into account.
LimitationThrottling 429429 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.APIs might throttle at any time for a variety of reasons, so your application must always be prepared to handle 429 responses. Cette réponse d’erreur inclut le champ Retry-After dans l’en-tête de la réponse HTTP.This error response includes the Retry-After field in the HTTP response header. 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.Backing off requests using the Retry-After delay is the fastest way to recover from throttling. Pour en savoir plus, consultez l’article relatif à la limitation.For more information, see throttling.
Service non disponibleService unavailable 503503 Cette erreur indique vraisemblablement que le service est occupé.This is likely because the services is busy. Nous vous recommandons d’adopter une stratégie d’interruption semblable à celle utilisée pour l’erreur 429.You should employ a back-off strategy similar to 429. De plus, pensez toujours à envoyer des requêtes de nouvelle tentative via une nouvelle connexion HTTP.Additionally, you should always make new retry requests over a new HTTP connection.

Énumérations évolutivesEvolvable enums

Les applications clientes peuvent s’arrêter si des membres sont ajoutés à une énumération existante.Client applications can be broken by the addition of members to an existing enum. Pour certaines énumérations plus récentes dans Microsoft Graph, un mécanisme est disponible pour autoriser l’ajout de nouveaux membres sans subir de modification importante.For some newer enums in Microsoft Graph, a mechanism is available to allow for adding new members without incurring a breaking change. Dans ces énumérations plus récentes, vous verrez un membre sentinel courant appelé unknownFutureValue, qui délimite les membres d’énumération connus et inconnus.On these newer enums, you'll see a common sentinel member called unknownFutureValue that demarcates known and unknown enum members. Les membres connus auront un nombre inférieur au membre sentinel, tandis que les membres inconnus auront une valeur supérieure.Known members will have a number less than the sentinel member, while unknown members will be greater in value. Par défaut, les membres inconnus ne sont pas renvoyés par Microsoft Graph.By default, unknown members are not returned by Microsoft Graph. Si, toutefois, votre application est conçue pour traiter l’apparence des membres inconnus, elle peut accepter de recevoir des membres d’énumération inconnus, en utilisant l’en-tête de requête HTTP Prefer.If, however, your application is written to handle the appearance of unknown members, it can opt-in to receive unknown enum members, using an HTTP Prefer request header.

Remarque : si votre application est prête à traiter des membres d’énumération inconnus, elle doit l’accepter en utilisant l’en-tête de requête HTTP Prefer : Prefer: include-unknown-enum-members.Note: If your application is prepared to handle unknown enum members, it should opt-in by using an HTTP prefer request header: Prefer: include-unknown-enum-members.

Stockage des données localementStoring data locally

Dans la mesure du possible, votre application doit appeler Microsoft Graph pour extraire des données en temps réel selon ses besoins.Your application should ideally make calls to Microsoft Graph to retrieve data in real time as necessary. 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.You should only cache or store data locally if required for a specific scenario, and if that use case is covered by your terms of use and privacy policy, and does not violate the Microsoft APIs Terms of Use. Votre application doit également implémenter des stratégies de rétention et de suppression des données adaptées.Your application should also implement proper retention and deletion policies.

OptimisationsOptimizations

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.In general, for performance and even security or privacy reasons, you should only get the data your application really needs, and nothing more.

Utilisations prévuesUse projections

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).Choose only the properties your application really needs and no more, because this saves unnecessary network traffic and data processing in your application (and in the service).

Remarque : utilisez le paramètre de requête $select pour que les requêtes envoient uniquement les propriétés requises par votre application.Note: Use the $select query parameter to limit the properties returned by a query to those needed by your 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 :For example, when retrieving the messages of the signed-in user, you can specify that only the from and subject properties be returned:

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

Obtention de réponses minimalesGetting minimal responses

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.For some operations, such as PUT and PATCH (and in some cases POST), if your application doesn't need to make use of a response payload, you can ask the API to return minimal data. Notez que certains services renvoient déjà une réponse 204 (Aucun contenu) pour les opérations PUT et PATCH.Note that some services already return a 204 No Content response for PUT and PATCH operations.

Remarque : demandez des réponses de représentation minimales à l’aide d’un en-tête de requête HTTP le cas échéant : Prefer : return = minimal.Note: Request minimal representation responses using an HTTP request header where appropriate: Prefer: return=minimal. Ce conseil n’est pas forcément adapté pour les opérations de création, car votre application peut s’attendre à obtenir l’id du service généré pour le nouvel objet créé dans la réponse.Note that for creation operations, this might not be appropriate because your application may expect to get the service generated id for the newly created object in the response.

Suivi des modifications : requête delta et notifications webhookTrack changes: delta query and webhook notifications

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.If your application needs to know about changes to data, you can get a webhook notification whenever data of interest has changed. Cette méthode est plus efficace que la méthode d’interrogation, même effectuée de façon régulière.This is more efficient than simply polling on a regular basis.

Utilisez les notifications webhook pour recevoir des notifications Push quand des données sont modifiées.Use webhook notifications to get push notifications when data changes.

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.If your application is required to cache or store Microsoft Graph data locally, and keep that data up to date, or track changes to data for any other reasons, you should use delta query. 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.This will avoid excessive computation by your application to retrieve data your application already has, minimize network traffic, and reduce the likelihood of reaching a throttling threshold.

Utilisez une requête delta pour tenir des données à jour.Use delta query to efficiently keep data up to date.

Utilisation de la requête delta avec les webhooksUsing webhooks and delta query together

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.Webhooks and delta query are often used better together, because if you use delta query alone, you need to figure out the right polling interval - too short and this might lead to empty responses which wastes resources, too long and you might end up with stale data. Si vous utilisez les notifications webhook comme déclencheur pour appeler une requête delta, vous profitez des atouts des deux fonctionnalités.If you use webhook notifications as the trigger to make delta query calls, you get the best of both worlds.

Utilisez les notifications webhook comme déclencheur pour appeler une requête delta.Use webhook notifications as the trigger to make delta query calls. 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.You should also ensure that your application has a backstop polling threshold, in case no notifications are triggered.

Traitement par lotsBatching

Le traitement par lots JSON permet d’optimiser votre application en combinant plusieurs requêtes dans un seul objet JSON.JSON batching allows you to optimize your application by combining multiple requests into a single JSON object. 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.Combining individual requests into a single batch request can save the application significant network latency and can conserve connection resources.

Utilisez le traitement par lots quand une latence majeure du réseau peut avoir des répercussions importantes sur les performances de votre applications.Use batching where significant network latency can have a big impact on the performance.

Fiabilité et prise en chargeReliability and support

Pour garantir la fiabilité et faciliter la prise en charge de votre application :To ensure reliability and facilitate support for your application:

  • Respectez la durée de vie (TTL) du DNS et configurez la durée de vie de connexion correspondant à celle du DNS.Honor DNS TTL and set connection TTL to match it. Ainsi, la disponibilité de votre application est garantie en cas de basculements.This ensures availability in case of failovers.
  • Ouvrez les connexions à toutes les réponses DNS publiées.Open connections to all advertised DNS answers.
  • Générez un GUID unique et envoyez-le sur chaque demande REST de Microsoft Graph.Generate a unique GUID and send it on each Microsoft Graph REST request. Microsoft pourra ainsi examiner plus facilement les erreurs si vous devez signaler un problème survenu avec Microsoft Graph.This will help Microsoft investigate any errors more easily if you need to report an issue with 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.On every request to Microsoft Graph, generate a unique GUID, send it in the client-request-id HTTP request header, and also log it in your application's logs.
    • Consignez toujours les éléments request-id, timestamp et x-ms-ags-diagnostic à partir des en-têtes de réponse HTTP.Always log the request-id, timestamp and x-ms-ags-diagnostic from the HTTP response headers. Ces éléments, ainsi que l’élément client-request-id, sont nécessaires lorsque vous signalez des problèmes dans Stack Overflow ou au support Microsoft.These, together with the client-request-id, are required when reporting issues in Stack Overflow or to Microsoft Support.