Exibir os e-mails de um usuário

  • 5 minutos

Você criou um aplicativo JavaScript e conectou-o Microsoft 365 usando a Biblioteca de Autenticação da Microsoft. 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 por Microsoft Graph são protegidos e seu aplicativo deve ter as permissões adequadas concedidas para accessá-los. As permissões necessárias dependem do tipo de informação que seu aplicativo precisa acessar. Por exemplo, para acessar o calendário de um usuário, seu aplicativo deve ter a permissão de Leitura de Calendários. Para acessar o email de um usuário, seu aplicativo precisa da permissão Leitura de Email. A lista exata das permissões necessárias para cada operação está disponível na referência Microsoft Graph API.

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. Seu aplicativo deve solicitar apenas as permissões de que você realmente precisa.

Digamos que seu aplicativo tenha duas páginas. Uma página mostra os emails de um usuário e a outra página mostra o calendário. Quando o usuário entra em seu aplicativo pela primeira vez, seu aplicativo solicita acesso apenas às informações básicas do perfil. Quando eles vão para a página que mostra emails, seu aplicativo solicita permissão para ler seus emails. Se eles nunca visitarem a página em seu aplicativo que mostra o calendário, seu aplicativo não terá acesso aos dados do calendário.

Esse padrão é chamado dee é a maneira recomendada de solicitar permissões por aplicativos conectados Microsoft 365. Com o consentimento dinâmico, os usuários controlam os dados que compartilham com os aplicativos que usam, o que minimiza os riscos de segurança.

Especificar as permissões necessárias

Antes de chamar Microsoft Graph, verifique se a Biblioteca de Autenticação da Microsoft contém uma lista das permissões exigidas pelo Microsoft Graph. A Biblioteca de Autenticação da Microsoft verifica automaticamente se o token de acesso recuperado anteriormente tem os escopos necessários ou não. Caso contrário, ele tentará recuperar automaticamente um novo token de acesso para você. Quando você usa o aplicativo pela primeira vez, a Biblioteca de Autenticação da Microsoft mostra uma janela pop-up que solicita que você consenta com o aplicativo acessando essas informações.

Se você acompanhar os escopos da Biblioteca de Autenticação da Microsoft em uma variável global, verifique se as permissões necessárias estão incluídas na lista de escopos antes de executar a chamada. Como você precisa garantir os escopos necessários antes de cada chamada, você pode encapsule-os em uma função auxiliar.

function ensureScope (scope) {
  if (!msalRequest.scopes.some((s) => s.toLowerCase() === scope.toLowerCase())) {
    msalRequest.scopes.push(scope);
  }
}

Ao chamar Microsoft Graph para recuperar dados, você garante que as permissões necessárias sejam incluídas chamando a função auxiliar.

async function getEmails() {
  ensureScope('mail.read');
  // ...
}

Recuperar emails 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. Para obter emails de um usuário, seu aplicativo deve receber a permissão Mail.Read usuário. Você pode chamar Microsoft Graph de extremidade usando o SDK do Microsoft Graph. Para usá-lo, especifique o ponto de extremidade e o tipo de solicitação que deseja executar.

A recuperação de emails é uma solicitação GET que você executa da seguinte maneira:

graphClient.api('/me/messages').get();

Microsoft Graph pontos de extremidade retornam dados em ordem arbitrária. Para garantir que você receba as mensagens mais recentes, classifique-as em ordem decrescente até a data em que foram recebidas.

graphClient
  .api('/me/messages')
  .orderby('receivedDateTime desc')
  .get();

Ao recuperar dados de Microsoft Graph, você sempre deve recuperar apenas os dados necessários, conforme mencionado anteriormente. 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 a serem incluídas.

Para especificar quais propriedades você deseja recuperar, estenda a solicitação Microsoft Graph com o método select e passe uma lista separada por vírgulas de 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 comando:


graphClient
  .api('/me/messages')
  .select('subject,receivedDateTime')
  .orderby('receivedDateTime desc')
  .get();

Dica

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

Outra ação que você pode fazer para limitar a quantidade de dados retornados Microsoft 365 é especificar quantos itens você deseja obter. Para especificar quantos itens você deseja obter, estenda a solicitação Microsoft Graph com o top método. Por exemplo, para recuperar os 10 últimos emails recebidos, use o seguinte comando:

graphClient
  .api('/me/messages')
  .select('subject,receivedDateTime')
  .orderby('receivedDateTime desc')
  .top(10)
  .get();

Próximas etapas

Vamos colocar tudo o que você aprendeu para praticar e estender seu aplicativo para mostrar os 10 últimos emails recebidos para o usuário atual.