Exibir os e-mails de um usuário

  • 5 minutos

Você executou um aplicativo ASP.NET Core e conectou-o ao Microsoft 365. Agora é hora de recuperar os emails de um usuário e exibi-los em seu aplicativo.

Decidir quais permissões seu aplicativo precisa

Todos os dados expostos pelo Microsoft Graph são protegidos e seu aplicativo deve ter as permissões adequadas concedidas para acessá-los. A permissão necessária depende do tipo de informação que seu aplicativo precisa acessar. Por exemplo, para acessar as mensagens de email do usuário, seu aplicativo precisa ter a permissão Mail.Read. A lista exata das permissões necessárias para cada operação está disponível na referência da API do Microsoft Graph.

Se seu aplicativo carregar diferentes tipos de dados, os usuários deverão conceder a ele várias permissões necessárias para acessar essas informações. É recomendável que, em seu aplicativo, você solicite apenas as permissões necessárias.

Especificar as permissões necessárias

A lista de permissões concedidas ao seu aplicativo é inserida diretamente no token de acesso. O padrão OAuth os chama de escopos. Quando a sua aplicação utiliza a MSAL para obter o token de acesso, tem de incluir uma lista de âmbitos no pedido para o ID do Microsoft Entra. Cada operação no Microsoft Graph tem sua própria lista de escopos. Se o token de acesso não tiver um deles, a solicitação será negada.

O aplicativo de exemplo armazena as permissões necessárias no arquivo appsettings.json em uma propriedade Scopes como você viu anteriormente.

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

O valor da propriedade Scopes é usado pelo middleware ASP.NET Core do aplicativo, que manipula a recuperação de um token de acesso depois que o usuário entra com êxito.

Middleware: plataforma de identidade da Microsoft e Microsoft Graph

ASP.NET Core dá suporte a middleware que pode ser usado para autenticar e autorizar usuários. Ele também pode ser usado para recuperar um token que pode ser usado para chamar o Microsoft Graph, injetar um objeto do SDK do Microsoft Graph chamado GraphServiceClient no aplicativo, criar um cache de token e muito mais. O middleware é configurado em Startup.cs e manipula as tarefas a seguir.

  1. Recupere as permissões necessárias definidas na propriedade Scopes de appsettings.json.
  2. Adicione suporte para autenticação OpenId.
  3. Especifique que o aplicativo é um aplicativo Web da plataforma de identidade da Microsoft que requer um fluxo de código de autenticação.
  4. Adicione a capacidade de chamar APIs do Microsoft Graph com permissões específicas.
  5. Habilite a injeção de dependência para GraphServiceClient (um objeto fornecido pelo SDK do Microsoft Graph que é usado para fazer chamadas Microsoft Graph).
  6. Adicione um cache de token na memória.
  7. Será necessário um usuário autenticado para acessar o aplicativo.
  8. Habilite suporte ao Razor Pages.
  9. Adicione páginas de interface do usuário do Microsoft Identity que forneçam suporte para entrada e saída do usuário.

Você pode ver cada uma dessas etapas no código a seguir definido no método ConfigureServices() do 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();

Depois que o middleware necessário for configurado, o aplicativo manipulará automaticamente a entrada do usuário e a recuperação do token de acesso. O token de acesso pode ser usado para recuperar as mensagens de email de um usuário, já que conterá as permissões necessárias. Vamos examinar como esse processo funciona.

Recuperar e-mails de um usuário do Microsoft Graph.

Para obter emails de um usuário do Microsoft Graph, chame o ponto de extremidade /me/messages. Ele retorna uma lista de emails da caixa de correio do usuário conectado. Você pode fazer a chamada para o Microsoft Graph usando o objeto GraphServiceClient que foi mencionado anteriormente na seção de middleware. GraphServiceClient fornece APIs que podem ser usadas para chamar o Microsoft Graph sem precisar fazer chamadas HTTP manualmente.

Veja um exemplo de como usar GraphServiceClient para fazer uma chamada que recupere as mensagens de email de um usuário:

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

Microsoft Graph pontos de extremidade retornam dados em ordem arbitrária. Para garantir que recebe as mensagens mais recentes, ordene-as por ordem descendente até à data em que foram recebidas:

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

Ao recuperar dados de Microsoft Graph, você sempre deve recuperar apenas os dados necessários. Minimizar a quantidade de dados que Microsoft Graph recupera e transfere durante a transmissão para seu aplicativo ajuda você a melhorar significativamente o desempenho do aplicativo.

Você pode limitar a quantidade de dados recuperados Microsoft 365 de duas maneiras:

  • Selecione quantos itens você deseja obter.
  • Selecione as informações específicas que devem ser incluídas.

Para especificar quais propriedades você deseja recuperar, estenda a solicitação do Microsoft Graph solicitação com um método Select e crie um objeto que define as propriedades a serem retornadas. Por exemplo, para obter uma lista de emails com apenas o assunto e a data/hora em que eles foram recebidos, use o seguinte código:

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

Você pode encontrar a lista completa de propriedades disponíveis em cada ponto de extremidade na referência da API do Microsoft Graph.

Outra ação que você pode tomar para limitar a quantidade de dados retornados do Microsoft 365 é especificar quantos itens você deseja obter. Para fazer isso, estenda a solicitação do Microsoft Graph com o método Top. Por exemplo, para recuperar os 10 emails recebidos mais recentemente, você pode usar o seguinte código:

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

Vamos examinar como você pode usar esse código no aplicativo.