Übersicht über die Verwendung der Outlook-REST-APIs

Tipp

Probieren Sie REST-Beispielaufrufe in unserem Graph-Tester aus. Sie können Ihr eigenes Konto oder eines unserer Testkonten verwenden. Kehren Sie, sobald Sie mit dem Testen der API fertig sind, hierher zurück, und wählen Sie Ihre bevorzugte Plattform auf der linken Seite aus. Sie werden durch die Schritte zum Schreiben einer einfachen Anwendung zum Abrufen von Nachrichten aus Ihrem Posteingang geführt.

Wenn Ihre bevorzugte Plattform nicht aufgeführt ist, fahren Sie mit dem Lesen dieser Seite fort. Hier werden die gleichen Schritte unter Verwendung von unformatierten HTTP-Anforderungen beschrieben.

In diesem Leitfaden werden Sie schrittweise durch den Prozess des Aufrufs der Outlook-Mail-API zum Abrufen von Nachrichten in Office 365 und Outlook.com geführt. Im Gegensatz zu den plattformspezifischen Erste-Schritte-Anleitungen liegt in diesem Leitfaden der Fokus auf OAuth- und REST-Anforderungen und -Antworten. Es wird die Abfolge der Anforderungen und Antworten behandelt, die eine App zum Authentifizieren und Abrufen von Nachrichten verwendet.

In diesem Lernprogramm wird Microsoft Graph zum Aufrufen der Mail-API verwendet. Microsoft empfiehlt die Verwendung von Microsoft Graph für den Zugriff auf Outlook-Mail, -Kalender und -Kontakte. Verwenden Sie die Outlook-APIs nur dann direkt (über https://outlook.office.com/api), wenn Sie ein Feature benötigen, das in den Graph-Endpunkten nicht verfügbar ist.

Mit den Informationen in diesem Leitfaden können Sie dies in einem beliebigen Sprache oder Plattform implementieren, die HTTP-Anforderungen senden kann.

Authentifizieren mit OAuth2

Um die Mail-API aufzurufen, benötigt die App ein Zugriffstoken von Azure Active Directory. Zu diesem Zweck implementiert die App einen der unterstützten OAuth-Flüsse im Azure v2.0-Endpunkt. Damit dies funktioniert, muss die App jedoch im App-Registrierungsportal registriert werden.

Registrieren einer App

Hinweis

In diesem Beispielszenario wird der Autorisierungscodefluss verwendet. Die einzelnen Schritte für den impliziten Fluss bzw. den Clientanmeldeinformationen-Fluus sind leicht unterschiedlich.

Sie können das App-Registrierungsportal zum schnellen Registrieren einer App verwenden, die eine der Outlook-APIs nutzt.

Wichtig

Neue App-Registrierungen sollten im Anwendungsregistrierungsportal erstellt und verwaltet werden, damit sie mit Outlook.com kompatibel sind. Erstellen Sie neue App-Registrierungen nur dann im Azure-Verwaltungsportal Folgendes auf Ihre App zutrifft:

  • Sie verwendet den OAuth2 Client Credentials Grant-Fluss oder
  • Sie muss neben Outlook auf andere Office 365-Arbeitslasten zugreifen (z. B. OneDrive for Business oder SharePoint)

Beachten Sie, dass mithilfe des Azure-Verwaltungsportals registrierte Apps nicht mit Outlook.com kompatibel sind und dass Berechtigungsbereiche nicht dynamisch angefordert werden können. Vorhandene App-Registrierungen, die im Azure-Verwaltungsportal erstellt wurden, funktionieren weiterhin nur für Office 365. Diese Registrierungen werden nicht im Anwendungsregistrierungsportal angezeigt und müssen im Azure-Verwaltungsportal verwaltet werden.

Kontoanforderungen

Um das Anwendungsregistrierungsportal zu verwenden, benötigen Sie entweder ein Office 365-Geschäfts- oder Schulkonto oder ein Microsoft-Konto. Wenn Sie nicht über eines dieser Konten verfügen, haben Sie verschiedene Möglichkeiten:

  • Registrieren Sie sich hier für ein neues Microsoft-Konto.
  • Sie haben mehrere Möglichkeiten, ein Office 365-Abonnement zu erhalten:

REST-API-Verfügbarkeit

Die REST-API ist derzeit auf allen Office 365-Konten, die über Exchange Online verfügen, sowie auf allen Outlook.com-Konten aktiviert.

Nachdem Sie die App registriert haben, verfügen Sie über eine Client-ID und ein Geheimnis. Diese werden im Autorisierungscodefluss verwendet.

Abrufen eines Autorisierungscodes

Im ersten Schritt des Autorisierungscodeflusses wird ein Autorisierungscode abgerufen. Dieser Code wird von Azure an die App zurückgegeben, wenn der Benutzer sich anmeldet und der Zugriffsstufe zustimmt, die die App erfordert.

Die App generiert zunächst eine Anmelde-URL für den Benutzer. Diese URL muss in einem Browser geöffnet werden, damit der Benutzer sich anmelden und seine Zustimmung erteilen kann.

Die Basis-URL für die Anmeldung sieht wie folgt aus:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Die App fügt Abfrageparameter an diese Basis-URL an, um Azure mitzuteilen, welche App die Anmeldung anfordert und welche Berechtigungen angefordert werden.

  • client_id: Die beim Registrieren der App generierte Client-ID. Anhand dieser erkennt Azure, welche App die Anmeldung anfordert.
  • redirect_uri: Der Ort, zu dem Azure umleitet, nachdem der Benutzer seine Zustimmung für die App erteilt hat. Dieser Wert muss mit dem Wert des beim Registrieren der App verwendeten Umleitungs-URI übereinstimmen.
  • response_type: Der Antworttyp, den die App erwartet. Für den Autorisierungscodefluss muss der Wert immer code lauten.
  • scope: Eine mit Leerzeichen getrennte Liste von Zugriffsbereichen, die Ihre App benötigt. Eine vollständige Liste der Outlook-Bereiche in Microsoft Graph finden Sie unter Microsoft Graph-Berechtigungsbereiche.

Eine Anwendung, die Lesezugriff auf E-Mails benötigt, würde z. B. alle die Parameter zusammenstellen, um eine Anforderungs-URL wie die folgende zu generieren:

Autorisierungscodeanforderung

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=<CLIENT ID>&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&response_type=code&scope=openid+Mail.Read

Es wird ein Anmeldefenster mit dem Namen der App angezeigt. Wenn der Benutzer die App zum ersten Mal verwendet, wird nach dem Anmelden eine Liste der App-Berechtigungen angezeigt, die die App benötigt, und der Benutzer wird aufgefordert, diesen zuzustimmen oder sie zu verweigern. Wenn Benutzer dem erforderlichen Zugriff zustimmen, erfolgt im Browser eine Umleitung an den Umleitungs-URI, der in der ursprünglichen Anforderung angegeben wurde.

Umleitungsanforderung nach erfolgreicher Anmeldung

GET  HTTP/1.1 302 Found
Location: http://localhost/myapp/?code= AwABAAAA...cZZ6IgAA&session_state=7B29111D-C220-4263-99AB-6F6E135D75EF&state=D79E5777-702E-4260-9A62-37F75FF22CCE

Den Wert des Abfrageparameters code in der URL ist der Autorisierungscode. Im nächsten Schritt wird dieser Code gegen ein Zugriffstoken eingetauscht.

Abrufen eines Zugriffstokens

Zum Abrufen eines Zugriffstokens sendet die App fomularcodierte Parameter an die Tokenanforderungs-URL, die immer wie folgt lautet:

https://login.microsoftonline.com/common/oauth2/v2.0/token

Die App verwendet die folgenden Parameter.

  • client_id: Die beim Registrieren der App generierte Client-ID.
  • client_secret: Das beim Registrieren der App generierte Clientgeheimnis.
  • code: Der im vorherigen Schritt abgerufene Autorisierungscode.
  • redirect_uri: Dieser Wert muss mit dem in der Autorisierungscodeanforderung verwendeten Wert übereinstimmen.
  • grant_type: Der von der App verwendete Gewährungstyp. Für den Autorisierungscodefluss muss der Wert immer authorization_code lauten.

Diese Parameter werden in den Inhaltstyp application/x-www-form-urlencoded codiert und an die Tokenanforderungs-URL gesendet.

Zugriffstokenanforderung

POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AwABAAAA...cZZ6IgAA&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&client_id=<CLIENT ID>&client_secret=<CLIENT SECRET>

Azure antwortet mit einer JSON-Nutzlast, die das Zugriffstoken enthält.

Zugriffstokenantwort

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "token_type":"Bearer",
  "expires_in":"3600",
  "access_token":"eyJ0eXAi...b66LoPVA",
  "scope":"Mail.Read",
}

Das Zugriffstoken befindet sich im Feld access_token der JSON-Nutzlast. Die App verwendet diesen Wert zum Festlegen des Authorization-Headers beim Senden von REST-Aufrufen an die API.

Aufrufen der Mail-API

Wenn die App über ein Zugriffstoken verfügt, kann die Mail-API aufgerufen werden. Die Mail-API-Referenz enthält umfassende Informationen. Da diese App Nachrichten abruft, verwendet sie eine HTTP-GET-Anforderung für die https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages-URL. Hierdurch wird Nachrichten aus dem Posteingang abgerufen.

Optimieren der Anforderung

Apps können das Verhalten von GET-Anforderungen mithilfe von OData-Abfrageparametern steuern. Diese Parameter sollten von den Apps verwendet werden, um die Anzahl der zurückgegebenen Ergebnisse und der für jedes Element zurückgegebenen Felder einzuschränken. Hier ist ein Beispiel.

Betrachten Sie eine App, die Nachrichten in einer Tabelle anzeigt. Die Tabelle enthält nur Betreff, Absender sowie Datum und Zeit den Nachrichtenempfangs. In der Tabelle werden maximal 25 Zeilen angezeigt, und sie sollte so sortiert sein, dass zuletzt empfangene Nachrichten oben aufgeführt werden.

Um dies zu erreichen, verwendet die App die folgenden Abfrageparameter.

  • Der $select-Parameter wird verwendet, um nur die Felder subject, from und receivedDateTime anzugeben.
  • Der $top-Parameter wird zum Festlegen der maximalen Anzahl von 25 Elementen verwendet.
  • Der Parameter $orderby wird zum Sortieren der Ergebnisse nach dem Feld receivedDateTime verwendet.

Das Ergebnis ist die folgende Anforderung.

Mail-API-Anforderung für Nachrichten im Posteingang

GET https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$select=subject,from,receivedDateTime&$top=25&$orderby=receivedDateTime%20DESC

Accept: application/json
Authorization: Bearer eyJ0eXAi...b66LoPVA
X-AnchorMailbox: jason@contoso.onmicrosoft.com

Mail-API-Antwort

HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(...)/mailfolders('inbox')messages(subject,from,receivedDateTime)",
  "value": [
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABufX4i\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABufW1UAAA=",
      "subject": "Ruby on Rails tutorial",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2015-01-29T20:44:53Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABSzmz4\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABMirSeAAA=",
      "subject": "Trip Information",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-12-09T21:55:41Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABzxiLG\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABAblZoAAA=",
      "subject": "Multiple attachments",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-11-19T20:35:59Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAAA9yBBa\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAAA9x_8YAAA=",
      "subject": "Attachments",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-11-18T20:38:43Z"
    }
  ]
}

Nachdem Sie nun gelernt haben, wie Aufrufe an die Mail-API gesendet werden, können Sie anhand der API-Referenz beliebige Arten von Aufrufen erstellen, die für Ihre App erforderlich sind. Denken Sie jedoch daran, dass entsprechende Berechtigungen für die App bei der App-Registrierung für die Aufrufe konfiguriert werden müssen.