Afficher les courriers électroniques d’un utilisateur

  • 5 minutes

Vous utilisez une application ASP.NET Core et vous l’avez connectée à Microsoft 365. À présent, il est temps de récupérer les e-mails d’un utilisateur et de les afficher dans votre application.

Choisir les autorisations dont votre application a besoin

Toutes les données exposées par Microsoft Graph sont sécurisées et votre application doit avoir les autorisations nécessaires pour y accéder. L’autorisation nécessaire dépend du type d’informations dont votre application a besoin pour l’accès. Par exemple, pour accéder aux messages électroniques de l’utilisateur, votre application doit disposer de l’autorisation Mail.Read. La liste exacte des autorisations requises pour chaque opération est disponible dans la référence de l’API Microsoft Graph.

Si votre application charge différents types de données, les utilisateurs qui l’utilisent doivent lui accorder plusieurs autorisations d’accès à ces informations. Il est recommandé de demander dans votre application uniquement les autorisations dont vous avez besoin.

Spécifier les autorisations nécessaires

La liste des autorisations accordées à votre application se trouve dans le jeton d’accès. La norme OAuth les appelle « étendues ». Lorsque votre application utilise MSAL pour obtenir le jeton d’accès, elle doit inclure une liste d’étendues dans la requête à l’ID Microsoft Entra. Chaque opération dans Microsoft Graph possède sa propre liste d’étendues. Si votre jeton d’accès n’en a pas, la demande sera refusée.

L’exemple d’application stocke les autorisations requises dans le fichier appsettings.json dans une propriété Scopes comme vous l’avez vu précédemment.

"Scopes": "user.read presence.read mailboxsettings.read mail.read"

La valeur de propriété Scopes est utilisée par l’intergiciel ASP.NET Core de l’application, qui gère la récupération d’un jeton d’accès une fois que l’utilisateur s’est correctement connecté.

Intergiciel : Plateforme d'identités Microsoft et Microsoft Graph

ASP.NET Core prend en charge les intergiciels qui peuvent être utilisés pour authentifier et autoriser les utilisateurs. Il peut également être utilisé pour récupérer un jeton qui peut être utilisé pour appeler Microsoft Graph, injecter un objet SDK Microsoft Graph nommé GraphServiceClient dans l’application, créer un cache de jetons et bien plus encore. L’intergiciel est configuré dans Startup.cs et gère les tâches suivantes.

  1. Récupérez les autorisations requises définies dans la propriété Scopes à partir de appsettings.json.
  2. Ajoutez la prise en charge de l’authentification OpenId.
  3. Spécifiez que l’application est une application web Plateforme d'identités Microsoft qui nécessite un flux de code d’authentification.
  4. Ajoutez la possibilité d’appeler des API Microsoft Graph avec des autorisations spécifiques.
  5. Activer l’injection de dépendances pour GraphServiceClient (objet fourni par le SDK Microsoft Graph utilisé pour effectuer des appels Microsoft Graph).
  6. Ajoutez un cache de jetons en mémoire.
  7. Exigez qu’un utilisateur authentifié accède à l’application.
  8. Activez la prise en charge de Razor Pages.
  9. Ajoutez des pages d’interface utilisateur Microsoft Identity qui fournissent la prise en charge de la connexion et de la déconnexion de l’utilisateur.

Vous pouvez voir chacune de ces étapes dans le code suivant défini dans la méthode ConfigureServices() de Startup.cs.

// 1. Retrieve required permissions from appsettings
string[] initialScopes =
Configuration.GetValue<string>("DownstreamApi:Scopes")?.Split(' ');

services
  // 2. Add support for OpenId authentication
  .AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)

  // 3. Microsoft identity platform web app that requires an auth code flow
  .AddMicrosoftIdentityWebApp(Configuration)

  // 4. Add ability to call Microsoft Graph APIs with specific permissions
  .EnableTokenAcquisitionToCallDownstreamApi(initialScopes)

  // 5. Enable dependency injection for GraphServiceClient
  .AddMicrosoftGraph(Configuration.GetSection("DownstreamApi"))

  // 6. Add in-memory token cache
  .AddInMemoryTokenCaches();

// 7. Require an authenticated user
services.AddControllersWithViews(options =>
{
  var policy = new AuthorizationPolicyBuilder()
    .RequireAuthenticatedUser()
    .Build();
  options.Filters.Add(new AuthorizeFilter(policy));
});

services
  // 8. Add Razor Pages support
  .AddRazorPages()

  // 9. Add Microsoft Identity UI pages that provide user
  // sign-in and sign-out support
  .AddMicrosoftIdentityUI();

Une fois l’intergiciel requis configuré, l’application gère automatiquement la connexion de l’utilisateur et la récupération du jeton d’accès. Le jeton d’accès peut ensuite être utilisé pour récupérer les messages électroniques d’un utilisateur, car il contient les autorisations requises. Examinons le fonctionnement de ce processus.

Récupérer les e-mails d’un utilisateur à partir de Microsoft Graph

Pour récupérer les e-mails d’un utilisateur à partir de Microsoft Graph, vous devez appeler le point de terminaison /me/messages. Il renvoie la liste des e-mails de la boîte aux lettres de l’utilisateur connecté. Vous pouvez effectuer l’appel à Microsoft Graph à l’aide de l’objet GraphServiceClient mentionné précédemment dans la section de l’intergiciel. GraphServiceClient fournit des API qui peuvent être utilisées pour appeler Microsoft Graph sans avoir à effectuer manuellement des appels HTTP.

Voici un exemple d’utilisation de GraphServiceClient pour effectuer un appel qui récupère les messages électroniques d’un utilisateur :

var emails = await _graphServiceClient.Me.Messages
            .Request()
            .GetAsync();

Les points de terminaison Microsoft Graph retournent les données dans l’ordre arbitraire. Pour vous assurer que vous recevez les derniers messages, triez-les par ordre décroissant à partir de la date de réception :

var emails = await _graphServiceClient.Me.Messages
            .Request()
            .OrderBy("receivedDateTime desc")
            .GetAsync();

Lors de la récupération de données à partir de Microsoft Graph, vous devez toujours récupérer uniquement les données dont vous avez besoin. La minimisation de la quantité de données dont Microsoft Graph a besoin de récupérer et transférer par virement vers votre application vous permet d’améliorer considérablement les performances de votre application.

Vous pouvez limiter la quantité de données récupérées à partir de Microsoft 365 de deux façons :

  • Sélectionnez le nombre d’éléments que vous voulez obtenir.
  • Sélectionnez les informations spécifiques qui doivent être incluses.

Pour spécifier les propriétés que vous souhaitez récupérer, étendez la requête Microsoft Graph avec une méthode Select et créez un objet qui définit les propriétés à retourner. Par exemple, pour obtenir une liste d’e-mails avec uniquement leur objet et la date/heure auxquelles ils ont été reçus, utilisez le code suivant :

var emails = await _graphServiceClient.Me.Messages
            .Request()
            .Select(msg => new {
              msg.Subject,
              msg.ReceivedDateTime
            })
            .OrderBy("receivedDateTime desc")
            .GetAsync();

Vous trouverez la liste complète des propriétés disponibles sur chaque point de terminaison dans la référence d’API Microsoft Graph.

Une autre action que vous pouvez effectuer pour limiter la quantité de données retournées par Microsoft 365 consiste à spécifier le nombre d’éléments que vous souhaitez récupérer. Pour ce faire, étendez la demande Microsoft Graph avec la méthode Top. Par exemple, pour récupérer les 10 derniers e-mails reçus, vous pouvez utiliser le code suivant :

var emails = await _graphServiceClient.Me.Messages
            .Request()
            .Select(msg => new {
              msg.Subject,
              msg.ReceivedDateTime
            })
            .OrderBy("receivedDateTime desc")
            .Top(10)
            .GetAsync();

Examinons comment vous pouvez utiliser ce code dans l’application.