Vergleich der Microsoft Graph- und Outlook-REST-API-Endpunkte

Die Outlook-REST-APIs stehen sowohl im Microsoft Graph- als auch im Outlook-API-Endpunkt (https://outlook.office.com/api) zur Verfügung. Die APIs bieten weitgehend die gleiche Funktionalität und verwenden die gleichen Ressourcentypen.

Welchen Endpunkt sollte ich verwenden?

Microsoft empfiehlt, sofern möglich Microsoft Graph zu verwenden. Die Microsoft Graph-APIs enthalten mehr Funktionen als nur Outlook-bezogene APIs, einschließlich OneDrive und Active Directory. Bei Auswahl des Microsoft Graph-Endpunkts kann Ihre App ein Zugriffstoken abrufen, das Zugriff auf Outlook-Daten und andere Ressourcen ermöglicht, ohne dass mehrere Tokenanforderungen notwendig sind.

Es gibt jedoch einige Features, die entweder nur im Outlook-Endpunkt oder nur in der Beta-API von Microsoft Graph verfügbar sind. Wenn Ihre App diese Features benötigt, sollten Sie den Outlook-Endpunkt wählen.

Features, die nur im Outlook-Endpunkt verfügbar sind

Feature Beschreibung
Outlook-Aufgaben Die Outlook-API bietet Zugriff auf Benutzeraufgaben. Dieses Feature steht derzeit nur in der Beta-API des Microsoft Graph-Endpunkts zur Verfügung.

Umwandeln zwischen Graph und Outlook

Die meisten Outlook-APIs sind in der Referenzdokumentation zur Microsoft Graph-API dokumentiert. Um diese Informationen für den Outlook-Endpunkt nutzen zu können, müssen Sie einige Informationen umwandeln.

API-Versionen

Die Microsoft Graph-API bietet zwei Versionen: v1.0 und beta, während Outlook v1.0, v2.0 und beta bietet. Microsoft Graph v1.0 entspricht Outlook v2.0, und Microsoft Graph beta entspricht Outlook beta.

OAuth-Bereiche

Während sowohl der Microsoft Graph- als auch der Outlook-Endpunkt von Azure AD-ausgestellte Token verwendet, unterscheiden sich die Bereiche der einzelnen Endpunkte geringfügig. Apps, die Microsoft Graph-Anforderungsbereiche verwenden, wie Mail.Read oder Calendars.Write.Shared. Token, die durch Anforderung dieser Bereiche generiert werden, sind für den Outlook-Endpunkt nicht gültig.

Um die Bereiche umzuwandeln, qualifizieren Sie sie einfach mit https://outlook.office.com/. Beispielsweise wird der Microsoft Graph-Bereich Mail.Read für den Outlook-Endpunkt in https://outlook.office.com/Mail.Read umgewandelt.

Eigenschaftenname von Ressourcen

Die Ressourcen sind in Outlook und Microsoft Graph gleich. Die Groß-/Kleinschreibung der Eigenschaftennamen wird von den beiden Endpunkten jedoch unterschiedlich gehandhabt. Microsoft Graph verwendet Camel-Case-Schreibweise (camelCase, gemischte Groß-/Kleinschreibung) für Eigenschaftennamen, während Outlook Pascal-Schreibweise (PascalCase) verwendet. Zum Umwandeln zwischen den beiden Varianten muss einfach die Groß-/Kleinschreibung konvertiert werden.

Die Microsoft Graph-Nachrichtenressource definiert beispielsweise Eigenschaften wie subject, from und receivedDateTime. Im Outlook-Endpunkt lauten die Namen dieser Eigenschaften Subject, From und ReceivedDateTime.

Beispiel: Abrufen einer Nachricht

Betrachten wird ein einfaches Beispiel. In diesem Szenario fordert eine Web-App eine Liste von Nachrichten im Posteingang des Benutzers an.

Microsoft Graph

Zunächst fordert die App den Benutzer zur Anmeldung auf, um die Anwendung zu autorisieren. Da die App den Microsoft Graph-Bereich Mail.Read verwendet, sieht die Autorisierungs-URL wie folgt aus:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?scope=openid+Mail.Read&response_type=code&client_id=<SOME GUID>&redirect_uri=<REDIRECT URL>

Sobald die App über ein Zugriffstoken verfügt, sendet sie die folgende Anforderung:

GET https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$top=1&$select=subject,from,receivedDateTime,isRead
Accept: application/json
Authorization: Bearer <token>

Der Server gibt die folgende Antwort zurück:

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('b63d5fb9-4f43-44c4-8f9d-fd0727842876')/mailFolders('inbox')/messages(subject,from,receivedDateTime,isRead)",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$top=1&$select=subject%2cfrom%2creceivedDateTime%2cisRead&$skip=1",
  "value": [
    {
      "@odata.etag": "W/\"CwAAABYAAACd9nJ/tVysQos2hTfspaWRAAD8ujHV\"",
      "id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEMAACd9nJ-tVysQos2hTfspaWRAAD8tDzlAAA=",
      "receivedDateTime": "2015-11-03T03:21:04Z",
      "subject": "Scrum",
      "isRead": false,
      "from": {
        "emailAddress": {
          "name": "user0TestUser",
          "address": "user0@a830edad9050849NDA1.onmicrosoft.com"
        }
      }
    }
  ]
}

Outlook

Zunächst fordert die App den Benutzer zur Anmeldung auf, um die Anwendung zu autorisieren. Da die App den Outlook-Bereich https://outlook.office.com/Mail.Read verwendet, sieht die Autorisierungs-URL wie folgt aus:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?scope=openid+https%3A%2F%2Foutlook.office.com%2Fmail.read&response_type=code&client_id=<SOME GUID>&redirect_uri=<REDIRECT URL>

Sobald die App über ein Zugriffstoken verfügt, sendet sie die folgende Anforderung:

GET https://outlook.office.com/api/v2.0/me/mailfolders/inbox/messages?$top=1&$select=Subject,From,ReceivedDateTime,IsRead
Accept: application/json
Authorization: Bearer <token>

Der Server gibt die folgende Antwort zurück:

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/MailFolders('inbox')/Messages(Subject,From,ReceivedDateTime,IsRead)",
  "@odata.nextLink": "https://outlook.office.com/api/v2.0/$metadata#Me/MailFolders('inbox')/Messages(Subject,From,ReceivedDateTime,IsRead)",
  "value": [
    {
      "@odata.etag": "W/\"CwAAABYAAACd9nJ/tVysQos2hTfspaWRAAD8ujHV\"",
      "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEMAACd9nJ-tVysQos2hTfspaWRAAD8tDzlAAA=",
      "ReceivedDateTime": "2015-11-03T03:21:04Z",
      "Subject": "Scrum",
      "IsRead": false,
      "From": {
        "EmailAddress": {
          "Name": "user0TestUser",
          "Address": "user0@a830edad9050849NDA1.onmicrosoft.com"
        }
      }
    }
  ]
}