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

  • Artikel

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

Hinweis

Die Outlook-REST-APIs sind veraltet.

Die Outlook-REST-Endpunkte werden im März 2024 vollständig außer Betrieb genommen. Migrieren Sie bestehende Apps, um Microsoft Graph zu verwenden. Dies schließt nicht die OAuth2-Tokenzielgruppe ein, wie unter Authentifizieren einer IMAP-, POP- oder SMTP-Verbindung mithilfe von OAuth beschrieben.

Welchen Endpunkt sollte ich verwenden?

Mit Microsoft Graph befindet sich Outlook REST v2.0 auf dem Weg zur Außerbetriebnahme. Mit dem Microsoft Graph-Endpunkt können Sie auf Outlook und viele andere Dienste und Features zugreifen, darunter andere Office 365-Dienste, Enterprise Mobility + Security und Windows 10. 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.

Featureunterschiede

Es gibt einige Features, die derzeit entweder nur im Outlook-Endpunkt oder nur in der Betaversion von Microsoft Graph verfügbar sind.

Hinweis

Wir arbeiten ständig daran, alle derzeit auf dem Outlook-Endpunkt in Microsoft Graph verfügbaren Features zu integrieren. Es wird empfohlen, diese Liste regelmäßig nach Updates zu überprüfen.

Feature Unterschied zwischen Endpunkten
Outlook-Aufgaben Der Zugriff auf Aufgaben der Benutzer in Microsoft Graph ist über die To Do-API verfügbar.
Umfassende Benachrichtigungen Die Outlook-API ermöglicht es Entwicklern, bestimmte Felder in die Benachrichtigungsnutzlast einzubeziehen, indem sie den $select-Parameter verwenden. Microsoft Graph unterstützt dieses Feature derzeit nur im Betaendpunkt und plant, es in Kürze für v1.0 zu veröffentlichen.
Streamingbenachrichtigungen Die Outlook-API unterstützt Streamingbenachrichtigungen in der Vorschauversion der Beta-Endpunkts. Microsoft Graph unterstützt dieses Feature nicht und ist nicht Teil der Roadmap.

Verschiebung vom Outlook-Endpunkt zu Microsoft Graph

Die APIs ähneln sehr stark dem Microsoft Graph-Endpunkt und dem Outlook-Endpunkt. Es gibt jedoch einige Unterschiede zu beachten, insbesondere, wenn Sie zu Microsoft Graph migrieren oder beide Endpunkte in der gleichen Anwendung verwenden.

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

Obwohl die Microsoft Graph- und Outlook-Endpunkte beide auf von Azure AD ausgestellten Token basieren und die verwendeten Berechtigungen identisch sind, weicht die Art, auf die Ihre Anwendung diese Berechtigungen anfordert, geringfügig für jeden Endpunkt ab.

Azure v2 OAuth2-Endpunkt

Apps, die den Azure AD v2.0-Endpunkt für OAuth2 verwenden, fordern die Berechtigungsbereiche im scope-Parameter in einer Authentifizierung oder eine Tokenanforderung an.

  • Für Microsoft Graph geben Apps die Berechtigungen mit dem Präfix https://graph.microsoft.com/ an. Beispiel: Eine App kann die Mail.Read-Berechtigung durch Einschließen von https://graph.microsoft.com/Mail.Read im scope-Parameter anfordern.
  • Für den Outlook-Endpunkt geben Apps die Berechtigungen mit dem Präfix https://outlook.office.com/ an. Beispiel: Eine App kann die Mail.Read-Berechtigung durch Einschließen von https://outlook.office.com/Mail.Read im scope-Parameter anfordern.

Hinweis

Wenn eine Domäne nicht in einem Bereich enthalten ist, wird Microsoft Graph verwendet.

Token, die für einen bestimmten Endpunkt ausgestellt sind, gelten nicht für andere Endpunkte. Darüber hinaus können Sie nicht die Berechtigungen für einen Endpunkt und die Berechtigungen für den anderen Endpunkt in einer einzigen Anforderung gemeinsam verwenden.

Der Azure AD v2.0-Endpunkt unterstützt nur den Fluss für Clientanmeldeinformationen für den Microsoft Graph-Endpunkt. Apps, die ein Nur-App-Token mit dem Outlook-Endpunkt verwenden müssen, müssen den Azure AD v1.0-Endpunkt verwenden.

Azure v1 OAuth2-Endpunkt

Apps, die den Azure AD v1.0-Endpunkt verwenden, geben die erforderlichen Berechtigungen während der App-Registrierung im Azure-Portal an.

  • Wählen Sie für Microsoft Graph die Microsoft Graph-API beim Hinzufügen der erforderlichen Berechtigungen.
  • Wählen Sie für den Outlook-Endpunkt die Office 365 Exchange Online-API beim Hinzufügen der erforderlichen Berechtigungen.

Eigenschaftenname von Ressourcen

Die Ressourcen sind zwischen Microsoft Graph und Outlook weitgehend identisch. Die beiden Endpunkte behandeln die Groß-/Kleinschreibung der Eigenschaftennamen jedoch unterschiedlich. Microsoft Graph verwendet camelCase für Eigenschaftsnamen, während Outlook PascalCase verwendet. Die Übersetzung zwischen den beiden erfordert lediglich die Konvertierung der Groß-/Kleinschreibung. Geänderte Eigenschaftsnamen werden in der folgenden Tabelle angegeben.

Beispielsweise definiert die Microsoft Graph-Nachrichtenressource Eigenschaften wie subject, fromund receivedDateTime. Auf dem Outlook-Endpunkt heißen Subjectdiese Eigenschaften , Fromund ReceivedDateTime.

Geänderte Eigenschaftennamen

Die folgenden Eigenschaftennamen sind unterschiedlich zwischen Microsoft Graph und Outlook.

Ressourcentyp Microsoft Graph-Eigenschaft Outlook-Eigenschaft
contact mobilePhone MobilePhone1

Nachverfolgen von Änderungen (Synchronisierung)

Beide Endpunkte unterstützen das Abfragen von Sammlungen im Hinblick auf Änderungen im Zusammenhang mit einem Synchronisierungsstatus. Die Funktionalität ist zwar identisch, die Methoden unterscheiden sich aber geringfügig.

Am Microsoft Graph-Endpunkt werden Änderungen mithilfe von Delta-Abfragen abgefragt. Dies delta-Funktion für die Datensammlung implementiert.

Am Outlook-Endpunkt werden Änderungen durch Hinzufügen eines Headers zu normalen Abfragen von Ressourcensammlungen abgefragt.

Batchverarbeitung

Beide Endpunkte unterstützen die Batchverarbeitung von bis zu 20 separaten Anforderungen in einer HTTP-Anforderung.

Bei der Microsoft Graph-Batchverarbeitung werden mehrere API-Anfragen in einem JSON-Nachrichtentext mit einem Inhaltstyp von application/json codiert.

Zusätzlich zum JSON-Format unterstützt die Batchverarbeitung am Outlook-Endpunkt auch ein mehrteiliges Textformat mit einem Inhaltstyps von multipart/mixed.

Beispiel: Abrufen einer Nachricht

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

Microsoft Graph

Zunächst muss sich der Benutzer für die App anmelden, um die Anwendung zu autorisieren. Da die App den Microsoft Graph-Bereich Mail.Readverwendet, 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": "AAMkAGI2...",
      "receivedDateTime": "2015-11-03T03:21:04Z",
      "subject": "Scrum",
      "isRead": false,
      "from": {
        "emailAddress": {
          "name": "user0TestUser",
          "address": "user0@contoso.com"
        }
      }
    }
  ]
}

Outlook

Zunächst muss sich der Benutzer für die App anmelden, um die Anwendung zu autorisieren. Da die App den Outlook-Bereich https://outlook.office.com/Mail.Readverwendet, 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": "AAMkAGI2...",
      "ReceivedDateTime": "2015-11-03T03:21:04Z",
      "Subject": "Scrum",
      "IsRead": false,
      "From": {
        "EmailAddress": {
          "Name": "user0TestUser",
          "Address": "user0@contoso.com"
        }
      }
    }
  ]
}