Visualizzazione dei messaggi di posta elettronica di un utente

  • 5 minuti

Hai eseguito un'app ASP.NET Core e l'hai connessa a Microsoft 365. Ora è possibile recuperare i messaggi di posta elettronica di un utente e visualizzarli nell'app.

Decidere quali autorizzazioni sono necessarie per l'app

Tutti i dati esposti da Microsoft Graph sono protetti e l'app deve disporre delle autorizzazioni appropriate per accedervi. L'autorizzazione necessaria dipende dal tipo di informazioni a cui l'app deve accedere. Ad esempio, per accedere ai messaggi di posta elettronica dell'utente, l'app deve disporre dell'autorizzazione Mail.Read. L'elenco esatto delle autorizzazioni necessarie per ogni operazione è disponibile nel riferimento all'API di Microsoft Graph.

Se l'app carica diversi tipi di dati, gli utenti dovranno concedere più autorizzazioni necessarie per accedere a queste informazioni. Nella tua app è consigliabile richiedere solo le autorizzazioni necessarie.

Specificare le autorizzazioni necessarie

L'elenco delle autorizzazioni concesse all'app viene inserito direttamente nel token di accesso. Lo standard OAuth le definisce “ambiti". Quando l'applicazione usa MSAL per ottenere il token di accesso, deve includere un elenco di ambiti nella richiesta a Microsoft Entra ID. Ogni operazione in Microsoft Graph ha un proprio elenco di ambiti. Se il token di accesso non ne ha uno, la richiesta verrà rifiutata.

L'applicazione di esempio archivia le autorizzazioni necessarie nel file appsettings.json in una Scopes proprietà come illustrato in precedenza.

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

Il Scopes valore della proprietà viene usato dal middleware ASP.NET Core dell’app, che gestisce il recupero di un token di accesso dopo che l'utente ha eseguito correttamente l'accesso.

Middleware: Microsoft Identity Platform e Microsoft Graph

ASP.NET Core supporta middleware che possono essere usati per autenticare e autorizzare gli utenti. Può essere usato anche per recuperare un token che può essere usato per chiamare Microsoft Graph, inserire un oggetto Microsoft Graph SDK denominato GraphServiceClientnell'applicazione, creare una cache dei token e altro ancora. Il middleware è configurato in Startup.cs e gestisce le attività seguenti.

  1. Recuperare le autorizzazioni necessarie definite nella proprietà Scopes da appsettings.json.
  2. Aggiungere il supporto per l'autenticazione OpenId.
  3. Specificare che l'applicazione è un'app Web di Microsoft Identity Platform che richiede un flusso di codice di autenticazione.
  4. Aggiungere la possibilità di chiamare l’API di Microsoft Graph con autorizzazioni specifiche.
  5. Abilitare l'inserimento delle dipendenze per GraphServiceClient(un oggetto fornito da Microsoft Graph SDK che è usato per effettuare chiamate Microsoft Graph).
  6. Aggiungere una cache dei token in memoria.
  7. Richiedere a un utente autenticato di accedere all'app.
  8. Abilitare il supporto delle Razor Pages.
  9. Aggiungere pagine dell'interfaccia utente di Microsoft Identity che forniscono supporto per l'accesso e la disconnessione dell'utente.

È possibile vedere ognuno di questi passaggi nel codice seguente definiti nel metodo ConfigureServices() di 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();

Dopo aver configurato il middleware necessario, l'applicazione gestirà automaticamente l'accesso all'utente e il recupero del token di accesso. Il token di accesso può quindi essere usato per recuperare i messaggi di posta elettronica di un utente perché conterrà le autorizzazioni necessarie. Vediamo come funziona questo processo.

Recuperare i messaggi di posta elettronica di un utente da Microsoft Graph.

Per ottenere i messaggi di posta elettronica di un utente da Microsoft Graph, è necessario chiamare /me/messages l'endpoint. Questo restituisce un elenco di messaggi di posta elettronica dalla cassetta postale dell'utente connesso. È possibile effettuare la chiamata a Microsoft Graph usando GraphServiceClient l'oggetto menzionato in precedenza nella sezione middleware. GraphServiceClientfornisce API che possono essere usate per chiamare Microsoft Graph senza dover effettuare chiamate HTTP manualmente.

Ecco un esempio di utilizzo GraphServiceClient per effettuare una chiamata che recupera i messaggi di posta elettronica di un utente:

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

Gli endpoint di Microsoft Graph restituiscono i dati in ordine arbitrario. Per assicurarsi di ottenere i messaggi più recenti, ordinarli in ordine decrescente in base alla data in cui sono stati ricevuti:

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

Quando si recuperano dati da Microsoft Graph, è consigliabile recuperare sempre solo i dati necessari. Ridurre al minimo la quantità di dati che Microsoft Graph deve recuperare e trasferire tramite cavo all'app consente di migliorare significativamente le prestazioni dell’app.

È possibile limitare la quantità di dati recuperati da Microsoft 365 in due modi:

  • selezionando il numero di elementi da ottenere;
  • Selezionare le informazioni specifiche da includere.

Per specificare le proprietà che si vuole recuperare, estendere la richiesta di Microsoft Graph con un Select metodo e creare un oggetto che definisce le proprietà da restituire. Ad esempio, per ottenere un elenco di messaggi di posta elettronica con solo l'oggetto e la data/ora in cui sono stati ricevuti, usare il comando seguente:

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

È possibile trovare l'elenco completo delle proprietà disponibili in ogni endpoint nel riferimento dell'API di Microsoft Graph.

Un'altra azione possibile per limitare la quantità di dati restituiti da Microsoft 365 consiste nello specificare il numero di elementi da recuperare. A tale scopo, estendere la richiesta di Microsoft Graph con il Top metodo. Ad esempio, per recuperare i 10 messaggi di posta elettronica ricevuti più di recente, è possibile usare il codice seguente:

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

Esaminiamo come si può usare questo codice nell'applicazione.