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

  • Artikel

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 der Microsoft Identity Platform. Verwenden Sie einen der unterstützten OAuth 2.0-Flows, um ein Zugriffstoken abzurufen.

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

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.