Mostrar los correos electrónicos de un usuario

  • 5 minutos

Ha ejecutado una aplicación ASP.NET Core y la ha conectado a Microsoft 365. Ahora es el momento de recuperar los correos de un usuario y mostrarlos en la aplicación.

Decidir qué permisos necesita la aplicación

Todos los datos expuestos por Microsoft Graph están protegidos y la aplicación debe tener los permisos adecuados para acceder a ellos. El permiso necesario depende del tipo de información a la que la aplicación necesita acceder. Por ejemplo, para acceder a los mensajes de correo electrónico de un usuario, la aplicación debe tener el permiso Mail.Read. La lista exacta de los permisos necesarios para cada operación está disponible en la referencia de la API de Microsoft Graph.

Si la aplicación carga diferentes tipos de datos, los usuarios deben concederle varios permisos necesarios para acceder a esta información. Se recomienda que solicite solo los permisos necesarios en la aplicación.

Obtener los permisos necesarios

La lista de permisos concedidos a la aplicación se integra directamente en el token de acceso. El estándar OAuth los llama “ámbitos". Cuando la aplicación usa MSAL para obtener el token de acceso, debe incluir una lista de ámbitos en la solicitud a Microsoft Entra ID. Cada operación en Microsoft Graph tiene su propia lista de ámbitos. Si el token de acceso no tiene uno de ellos, se denegará la solicitud.

La aplicación de ejemplo almacena los permisos necesarios en el archivo appsettings.json en una propiedad Scopes tal como vio anteriormente.

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

El valor de la propiedad Scopes es usado por el middleware ASP.NET Core de la aplicación, que controla la recuperación de un token de acceso después de que el usuario inicia sesión correctamente.

Middleware: plataforma de identidad de Microsoft y Microsoft Graph

ASP.NET Core admite middleware que se puede usar para autenticar y autorizar a los usuarios. También se puede usar para recuperar un token que se puede usar para llamar a Microsoft Graph, insertar un objeto de SDK de Microsoft Graph denominado GraphServiceClient en la aplicación, crear una caché de tokens y mucho más. El middleware se configura en Startup.cs y controla las tareas siguientes.

  1. Recupere los permisos necesarios definidos en la propiedad Scopes de appsettings.json.
  2. Agregue compatibilidad para la autenticación con OpenId.
  3. Especifique que la aplicación es una aplicación web de la plataforma de identidad de Microsoft que requiere un flujo de código de autenticación.
  4. Agregue la capacidad de llamar a las API de Microsoft Graph con permisos específicos.
  5. Habilite la inserción de dependencias para GraphServiceClient (un objeto proporcionado por el SDK de Microsoft Graph que se usa para realizar llamadas a Microsoft Graph).
  6. Agregue una caché de tokens en memoria.
  7. Requiera un usuario autenticado para acceder a la aplicación.
  8. Habilite la compatibilidad con Razor Pages.
  9. Agregue páginas de la interfaz de usuario de Microsoft Identity que proporcionen compatibilidad con el inicio y cierre de sesión del usuario.

Puede ver cada uno de estos pasos en el código siguiente definido en el método 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();

Una vez configurado el middleware necesario, la aplicación controlará automáticamente el inicio de sesión del usuario y la recuperación del token de acceso. A continuación, el token de acceso se puede usar para recuperar los mensajes de correo electrónico de un usuario, ya que contendrá los permisos necesarios. Veamos cómo funciona ese proceso.

Recuperar los correos de un usuario desde Microsoft Graph

Para obtener los correos de un usuario de Microsoft Graph, debe llamar al punto de conexión de /me/messages. Devuelve una lista de correos del buzón del usuario que inició sesión. Puede realizar la llamada a Microsoft Graph mediante el objeto GraphServiceClient que se mencionó anteriormente en la sección de middleware. GraphServiceClient proporciona API que se pueden usar para llamar a Microsoft Graph sin tener que realizar manualmente llamadas HTTP.

Este es un ejemplo de uso de GraphServiceClient para realizar una llamada que recupere los mensajes de correo electrónico de un usuario:

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

Los puntos de conexión de Microsoft Graph devuelven datos en orden arbitrario. Para asegurarse de que obtiene los mensajes más recientes, ordene los mensajes descendentes según la fecha en que se recibieron:

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

Al recuperar datos de Microsoft Graph, debe recuperar solo los datos que necesite. Minimizar la cantidad de datos que Microsoft Graph necesita para recuperar y transferir a través de la conexión a la aplicación le ayudará a mejorar significativamente el rendimiento de la aplicación.

Puede limitar la cantidad de datos recuperados de Microsoft 365 de dos maneras:

  • Seleccione cuántos elementos quiere obtener.
  • Seleccione la información específica que debe incluirse.

Para especificar las propiedades que desea recuperar, extienda la solicitud de Microsoft Graph con un método Select y cree un objeto que defina las propiedades que se devolverán. Por ejemplo, para obtener una lista de correos solo con su asunto y la fecha y hora en que se recibieron, use el siguiente comando:

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

Puede encontrar la lista completa de propiedades disponibles en cada punto de conexión en la referencia de la API de Microsoft Graph.

Otra acción que puede realizar para limitar la cantidad de datos devueltos desde Microsoft 365 es especificar cuántos elementos desea obtener. Para ello, extienda la solicitud de Microsoft Graph con el método Top. Por ejemplo, para recuperar los 10 correos electrónicos más recientes, puede usar el siguiente código:

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

Examinemos cómo puede usar este código en la aplicación.