Zeigen Sie die E-Mails eines Benutzers an

  • 5 Minuten

Sie haben eine ASP.NET Core-App ausgeführt und mit Microsoft 365 verbunden. Jetzt ist es an der Zeit, die E-Mails eines Benutzers abzurufen und in Ihrer App anzuzeigen.

Entscheiden, welche Berechtigungen Ihre App benötigt

Alle von Microsoft Graph verfügbar gemachten Daten werden gesichert, und Ihre App muss über die erforderlichen Berechtigungen verfügen, um darauf zugreifen zu können. Die erforderlichen Berechtigungen sind von der Art der Informationen abhängig, auf die Ihre App zugreifen muss. Um beispielsweise auf die E-Mail-Nachrichten des Benutzers zuzugreifen, muss Ihre App über die Mail.Read-Berechtigung verfügen. Die vollständige Liste der für die einzelnen Vorgänge erforderlichen Berechtigungen finden Sie in der Microsoft Graph-API-Referenz.

Wenn Ihre App unterschiedliche Datentypen lädt, müssen Benutzer der App mehrere Berechtigungen erteilen, die für den Zugriff auf diese Informationen erforderlich sind. Es wird empfohlen, in Ihrer App nur die Berechtigungen anzufordern, die Sie benötigen.

Festlegen der erforderlichen Berechtigungen

Die Liste der gewährten Berechtigungen Ihrer App wird direkt im Zugriffstoken integriert. Im OAuth-Standard werden sie Bereiche (scopes) genannt. Wenn Ihre Anwendung MSAL zum Abrufen des Zugriffstokens verwendet, muss sie eine Liste von Bereichen in der Anforderung an die Microsoft Entra-ID enthalten. Jeder Vorgang in Microsoft Graph besitzt seine eigene Liste von Bereichen. Wenn in Ihrem Zugriffstoken eine solche fehlt, wird die Anforderung abgelehnt.

Wie Sie zuvor gesehen haben, speichert die Beispielanwendung die erforderlichen Berechtigungen in der Datei appsettings.json in einer Scopes-Eigenschaft.

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

Der Scopes-Eigenschaftswert wird von der ASP.NET Core-Middleware der App verwendet, die das Abrufen eines Zugriffstokens verarbeitet, nachdem sich der Benutzer erfolgreich angemeldet hat.

Middleware: Microsoft Identity Platform und Microsoft Graph

ASP.NET Core unterstützt Middleware, die zur Authentifizierung und Autorisierung von Benutzern verwendet werden kann. Es kann auch zum Abrufen eines Token genutzt werden, das verwendet werden kann, um Microsoft Graph aufzurufen, ein Microsoft Graph-SDK-Objekt namens GraphServiceClient in die Anwendung zu injizieren, einen Tokencache zu erstellen und vieles mehr. Die Middleware ist in Startup.cs konfiguriert und übernimmt die folgenden Aufgaben.

  1. Abrufen der in der Scopes-Eigenschaft definierten erforderlichen Berechtigungen aus appsettings.json.
  2. Hinzufügen von Support für die OpenId-Authentifizierung.
  3. Angeben, dass es sich bei der Anwendung um eine Microsoft Identity Platform-Web-App handelt, die einen Authentifizierungscodefluss erfordert.
  4. Hinzufügen der Möglichkeit, Microsoft Graph-APIs mit bestimmten Berechtigungen aufzurufen.
  5. Aktivieren der Abhängigkeitsinjektion für GraphServiceClient (ein vom Microsoft Graph-SDK bereitgestelltes Objekt, das für Microsoft Graph-Aufrufe verwendet wird).
  6. Hinzufügen eines Speichertokencache.
  7. Einen authentifizierten Benutzer für den Zugriff auf die App fordern.
  8. Aktivieren der Unterstützung für Razor Pages.
  9. Hinzufügen von Microsoft Identity-UI-Seiten, die Unterstützung für Benutzeranmeldung und -abmeldung bieten.

Sie können jeden dieser Schritte in folgendem Code in der ConfigureServices()-Methode von Startup.cs definiert sehen.

// 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();

Nachdem die erforderliche Middleware konfiguriert ist, übernimmt die Anwendung automatisch die Anmeldung des Benutzers und das Abrufen des Zugriffstokens. Das Zugriffstoken kann dann zum Abrufen der E-Mail-Nachrichten eines Benutzers verwendet werden, da es die erforderlichen Berechtigungen enthält. Sehen wir uns an, wie dieser Prozess funktioniert.

Abrufen der E-Mails eines Benutzers aus Microsoft Graph

Um E-Mails eines Benutzers von Microsoft Graph abzurufen, müssen Sie den Endpunkt "/me/messages" aufrufen. Er gibt eine Liste von E-Mails aus dem Postfach des angemeldeten Benutzers zurück. Sie können den Aufruf an Microsoft Graph mithilfe des zuvor im Middleware-Abschnitt erwähnten GraphServiceClient-Objekts ausführen. GraphServiceClient stellt APIs bereit, die zum Aufrufen von Microsoft Graph verwendet werden können, ohne manuell HTTP-Aufrufe ausführen zu müssen.

Im Folgenden finden Sie ein Beispiel für die Verwendung von GraphServiceClient zum Ausführen eines Aufrufs, der die E-Mail-Nachrichten eines Benutzers abruft:

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

Microsoft Graph-Endpunkte geben Daten in beliebiger Reihenfolge zurück. Um sicherzustellen, dass Sie die neuesten Nachrichten erhalten, sortieren Sie sie absteigend nach dem Datum, an dem sie empfangen wurden:

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

Beim Abrufen von Daten aus Microsoft Graph sollten Sie immer nur die Daten abrufen, die Sie benötigen. Durch die Minimierung der Datenmenge, die Microsoft Graph abrufen und über das Netzwerk an Ihre App übertragen muss, können Sie die Leistung Ihrer App erheblich verbessern.

Sie können die Menge der von Microsoft 365 abgerufenen Daten auf zwei Arten einschränken:

  • Wählen Sie aus, wie viele Elemente Sie abrufen möchten.
  • Wählen Sie die spezifischen Informationen aus, die eingeschlossen werden sollen.

Um anzugeben, welche Eigenschaften Sie abrufen möchten, erweitern Sie die Microsoft Graph Anforderung mit einer Select-Methode, und erstellen Sie ein Objekt, das die zurückzugebenden Eigenschaften definiert. Verwenden Sie beispielsweise den folgenden Code, um eine Liste von E-Mails mit nur ihrem Betreff und dem Datum/der Uhrzeit des Empfangs abzurufen:

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

Die vollständige Liste der Eigenschaften, die für jeden Endpunkt verfügbar sind, finden Sie in der Microsoft Graph API-Referenz.

Eine weitere Aktion, die Sie ausführen können, um die von Microsoft 365 zurückgegebene Datenmenge einzuschränken, besteht darin, anzugeben, wie viele Elemente Sie abrufen möchten. Erweitern Sie dazu die Microsoft Graph-Anforderung mit der Top-Methode. Um beispielsweise die 10 zuletzt empfangenen E-Mails abzurufen, können Sie den folgenden Code verwenden:

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

Sehen wir uns an, wie Sie diesen Code in der Anwendung verwenden können.