Отображение электронных писем пользователя

  • 5 мин

Вы создали приложение JavaScript и подключили его к Microsoft 365 с помощью библиотеки проверки подлинности Майкрософт. Теперь пришло время получить сообщения электронной почты пользователя и отобразить их в вашем приложении.

Выбор разрешений, необходимых вашему приложению

Все данные, представляемые посредством Microsoft Graph, защищены, и вашему приложению должны быть предоставлены соответствующие разрешения на доступ к ним. Необходимые разрешения зависят от типа сведений, к которым приложение должно получить доступ. Например, для доступа к календарю пользователя у вашего приложения должно быть разрешение Calendars.Read. Чтобы получить доступ к электронной почте пользователя, вашему приложению требуется разрешение Mail.Read. Точный список разрешений, необходимых для каждой операции, доступен в справочнике по API Microsoft Graph.

Если приложение загружает различные типы данных, пользователи должны предоставить ему несколько разрешений, необходимых для доступа к этой информации. Ваше приложение должно запрашивать только необходимые разрешения.

Предположим, что ваше приложение содержит две страницы. На одной странице показаны сообщения электронной почты пользователя, а на другой — его календарь. Когда пользователь впервые входит в приложение, ваше приложение запрашивает доступ только к его основным сведениям профиля. Когда пользователь переходит на страницу с электронными письмами, ваше приложение запрашивает разрешение на чтение его электронной почты. Если он никогда не посещал страницу в вашем приложении, содержащую его календарь, у приложения не будет доступа к его данным календаря.

Этот шаблон называется динамическим согласием. Это рекомендуемый способ запроса разрешений приложениями, подключенными к Microsoft 365. При помощи динамического согласия пользователи управляют данными, которыми они делятся с используемыми приложениями, что минимизирует угрозы безопасности.

Указание необходимых разрешений

Перед вызовом Microsoft Graph убедитесь, что библиотека проверки подлинности Майкрософт содержит список разрешений, необходимых для Microsoft Graph. Библиотека проверки подлинности Майкрософт автоматически проверяет, содержит ли ранее полученный маркер доступа необходимые области. Если нет, он автоматически пытается получить новый маркер доступа для вас. При первом использовании приложения в библиотеке проверки подлинности Майкрософт появляется всплывающее окно с запросом вашего согласия на доступ приложения к этому фрагменту информации.

Если вы отслеживаете области библиотеки проверки подлинности Майкрософт в глобальной переменной, перед выполнением вызова проверьте, включены ли необходимые разрешения в список областей. Так как необходимо обеспечивать наличие необходимых областей перед каждым вызовом, это можно оформить во вспомогательной функции.

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

При вызове Microsoft Graph для извлечения данных убедитесь, что необходимые разрешения включены путем вызова вспомогательной функции.

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

Извлечение сообщений электронной почты пользователя из Microsoft Graph

Чтобы получить сообщения электронной почты пользователя из Microsoft Graph, вызовите конечную точку /me/messages. Она возвращает список писем из почтового ящика вошедшего пользователя. Чтобы получать сообщения электронной почты пользователя, приложению должно быть предоставлено разрешение Mail.Read. Вы можете вызывать конечные точки Microsoft Graph с помощью пакета SDK Microsoft Graph. Чтобы использовать его, необходимо указать конечную точку и тип выполняемого запроса.

Извлечение сообщений электронной почты — это запрос GET, выполняемый следующим образом.

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

Конечные точки Microsoft Graph возвращают данные в произвольном порядке. Чтобы убедиться, что вы получили последние сообщения, отсортируйте их в порядке убывания по дате их получения.

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

При извлечении данных из Microsoft Graph всегда следует извлекать только необходимые данные, как указано ранее. Минимизация объема данных, которые Microsoft Graph извлекает и передает в ваше приложение, позволяет значительно повысить производительность приложения.

Вы можете ограничить объем данных, извлекаемых из Microsoft 365, двумя способами:

  • Выберите количество элементов, которые вы хотите получить.
  • Выберите конкретные сведения для включения.

Чтобы указать свойства, которые необходимо извлечь, расширьте запрос Microsoft Graph с помощью метода select и передайте список возвращаемых свойств, разделенных запятыми. Например, чтобы получить список сообщений электронной почты только с темой и датой/временем их получения, используйте следующую команду.


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

Совет

Полный список свойств, доступных для каждой конечной точки, см. в справочнике по API Microsoft Graph.

Еще одно действие, которое можно выполнить, чтобы ограничить объем данных, возвращаемых из Microsoft 365, — указание количества элементов, которые вы хотите получить. Чтобы указать количество элементов, которые вы хотите получить, расширьте запрос Microsoft Graph с помощью метода top. Например, чтобы извлечь 10 последних полученных сообщений электронной почты, используйте следующую команду.

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

Дальнейшие действия

Давайте рассмотрим на практике все изученное вами и расширим возможности вашего приложения для отображения 10 последних полученных сообщений электронной почты текущего пользователя.