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

5 мин

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

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

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

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

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

Список разрешений, предоставленных вашему приложению, включается прямо в маркер доступа. В стандарте OAuth они называются "областями". Когда приложение использует MSAL для получения маркера доступа, оно должно включить список областей в запрос к идентификатору Microsoft Entra. У каждой операции в Microsoft Graph есть собственный список областей. Если у маркера доступа нет одной из них, запрос отклоняется.

В примере приложения необходимые разрешения сохраняются в файле appsettings.json в свойстве Scopes, как было показано ранее.

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

Значение свойства Scopes используется в ПО промежуточного слоя ASP.NET Core приложения, где обрабатывается получение маркера доступа после успешного входа пользователя.

ПО промежуточного слоя: платформа удостоверений Майкрософт и Microsoft Graph

ASP.NET Core поддерживает ПО промежуточного слоя, которое можно использовать для проверки подлинности и авторизации пользователей. Оно также может использоваться для получения маркера, применимого для вызова Microsoft Graph, вставки в приложение объекта Microsoft Graph SDK под именем GraphServiceClient, создания кэша маркеров и для других целей. ПО промежуточного слоя настроено в Startup.cs и выполняет указанные ниже задачи.

Извлечение из appsettings.json необходимых разрешений, определенных в свойстве Scopes.
Добавление поддержки проверки подлинности OpenId.
Указание, что приложение является веб-приложением платформы удостоверений Майкрософт, требующим потока кода проверки подлинности.
Добавление возможности вызывать API Microsoft Graph с определенными разрешениями.
Включение внедрения зависимостей для GraphServiceClient (объект из пакета SDK Майкрософт Graph, используемый для вызовов Microsoft Graph).
Добавление кэша маркеров в памяти.
Требование проверки подлинности пользователя для доступа к приложению.
Включение поддержки Razor Pages.
Добавление страниц пользовательского интерфейса платформы удостоверений Майкрософт, которые обеспечивают поддержку входа и выхода пользователя.

Каждое из этих действий можно увидеть в следующем коде, определенном в методе ConfigureServices() файла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();

После настройки необходимого ПО промежуточного слоя приложение будет автоматически обрабатывать вход пользователя и получение маркера доступа. Затем маркер доступа можно использовать для получения сообщений электронной почты пользователя, так как он содержит необходимые разрешения. Рассмотрим, как работает этот процесс.

Получение электронных писем пользователя из Microsoft Graph

Чтобы получить сообщения электронной почты пользователя из Microsoft Graph, необходимо вызвать конечную точку /me/messages. Она выдает список сообщений из почтового ящика пользователя, вошедшего в систему. Microsoft Graph можно вызвать с помощью объекта GraphServiceClient, который был упомянут ранее в разделе ПО промежуточного слоя. GraphServiceClientпредоставляет интерфейсы API, которые можно использовать для вызова Microsoft Graph: это избавляет от необходимости делать HTTP-запросы вручную.

Вот пример использования GraphServiceClient для вызова, в результате которого приложение получает сообщения электронной почты пользователя:

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

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

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

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

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

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

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

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

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

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

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

Рассмотрим, как использовать этот код в приложении.

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

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

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

ПО промежуточного слоя: платформа удостоверений Майкрософт и Microsoft Graph

Получение электронных писем пользователя из Microsoft Graph

Обратная связь