Vergleich der Microsoft Graph- und Outlook-REST-API-EndpunkteCompare Microsoft Graph and Outlook REST API endpoints

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.The Outlook REST APIs are available in both Microsoft Graph and the Outlook API endpoint (https://outlook.office.com/api). The APIs generally provide the same functionality and use the same resource types.

Welchen Endpunkt sollte ich verwenden?Which endpoint should I use?

Verwenden Sie nach Möglichkeit Microsoft Graph.Use Microsoft Graph whenever possible. 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.The Microsoft Graph endpoint lets you access Outlook and many more services and features, including other Office 365 services, Enterprise Mobility + Security, and 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.Choosing the Microsoft Graph endpoint allows your app to get an access token that can provide access to both Outlook data and other resources, without having to make multiple token requests.

FeatureunterschiedeFeature differences

Es gibt einige Features, die derzeit entweder nur im Outlook-Endpunkt oder nur in der Betaversion von Microsoft Graph verfügbar sind.There are some features that are currently either only available on the Outlook endpoint, or are only in beta in Microsoft Graph. Wenn Ihre App diese Features benötigt, sollten Sie über den Outlook-Endpunkt auf diese zugreifen.If your app needs these features, you should access them via the Outlook endpoint.

Hinweis: Wir arbeiten ständig daran, alle derzeit auf dem Outlook-Endpunkt in Microsoft Graph verfügbaren Features zu integrieren.Note: We are constantly working to incorporate all of the features currently available on the Outlook endpoint into Microsoft Graph. Es wird empfohlen, diese Liste regelmäßig nach Updates zu überprüfen.Be sure to check back periodically as this list is updated.

FeatureFeature Unterschied zwischen EndpunktenDifference between endpoints
Outlook-AufgabenOutlook tasks Die Outlook-API bietet Zugriff auf Benutzeraufgaben.The Outlook API provides access to user's tasks. Dieses Feature steht derzeit nur in der Betaversion von Microsoft Graph zur Verfügung.This feature is currently only available in beta in Microsoft Graph.
Anlagen größer als 4 MBAttachments over 4MB in size Microsoft Graph kann keine Anlagen erstellen, die größer als 4 MB sind.Microsoft Graph cannot create attachments over 4MB in size. Beim Versuch, eine Anlage zu erstellen, die größer als 4 MB ist, tritt ein 413 Request Entity Too Large-Fehler auf.Attempts to create an attachment larger than 4MB results in a 413 Request Entity Too Large error.
Umfassende BenachrichtigungenRich notifications Die Outlook-API ermöglicht es Entwicklern, bestimmte Felder in die Benachrichtigungsnutzlast einzubeziehen, indem sie den $select-Parameter verwenden.The Outlook API allows developers to request specific fields to be included with the notification payload by using the $select parameter. Microsoft Graph unterstützt dieses Feature nicht.Microsoft Graph does not support this feature.
StreamingbenachrichtigungenStreaming notifications Die Outlook-API unterstützt Streamingbenachrichtigungen in der Vorschauversion der Beta-Endpunkts.The Outlook API supports streaming notifications in preview on the beta endpoint. Microsoft Graph unterstützt dieses Feature nicht.Microsoft Graph does not support this feature.

Verschiebung vom Outlook-Endpunkt zu Microsoft GraphMoving from Outlook endpoint to Microsoft Graph

Die APIs ähneln sehr stark dem Microsoft Graph-Endpunkt und dem Outlook-Endpunkt.The APIs are very similar on the Microsoft Graph endpoint and the Outlook endpoint. Es gibt jedoch einige Unterschiede zu beachten, insbesondere, wenn Sie zu Microsoft Graph migrieren oder beide Endpunkte in der gleichen Anwendung verwenden.However, there are some differences to be aware of, especially if you are migrating to Microsoft Graph or using both endpoints in the same application.

API-VersionenAPI versions

Die Microsoft Graph-API bietet zwei Versionen: v1.0 und beta, während Outlook v1.0, v2.0 und beta bietet.The Microsoft Graph API offers two versions: v1.0 and beta, while Outlook offers v1.0, v2.0, and beta. Microsoft Graph v1.0 entspricht Outlook v2.0 und Microsoft Graph beta entspricht Outlook beta.Microsoft Graph v1.0 matches Outlook v2.0, and Microsoft Graph beta matches Outlook beta. Die Outlook-Version v1.0 ist veraltet.The Outlook v1.0 version is being deprecated.

OAuth-BereicheOAuth scopes

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.While the Microsoft Graph and Outlook endpoints both rely on Azure AD-issued tokens, and the permissions used are the same, the way that your application requests those permissions is slightly different for each endpoint.

Azure v2 OAuth2-EndpunktAzure v2 OAuth2 endpoint

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.Apps that use the Azure AD v2.0 endpoint for OAuth2 request permission scopes in the scope parameter in an authentication or token request.

  • Für Microsoft Graph geben Apps die Berechtigungen mit dem Präfix https://graph.microsoft.com/ an.For Microsoft Graph, apps specify permissions prefixed with https://graph.microsoft.com/. Beispiel: Eine App kann die Mail.Read-Berechtigung durch Einschließen von https://graph.microsoft.com/Mail.Read im scope-Parameter anfordern.For example, an app can request the Mail.Read permission by including https://graph.microsoft.com/Mail.Read in the scope parameter.
  • Für den Outlook-Endpunkt geben Apps die Berechtigungen mit dem Präfix https://outlook.office.com/ an.For the Outlook endpoint, apps specify permissions prefixed with https://outlook.office.com/. Beispiel: Eine App kann die Mail.Read-Berechtigung durch Einschließen von https://outlook.office.com/Mail.Read im scope-Parameter anfordern.For example, an app can request the Mail.Read permission by including https://outlook.office.com/Mail.Read in the scope parameter.

Hinweis: Wenn eine Domäne nicht in einem Bereich enthalten ist, wird Microsoft Graph verwendet.Note: If a domain is not included in a scope, Microsoft Graph is assumed.

Token, die für einen bestimmten Endpunkt ausgestellt sind, gelten nicht für andere Endpunkte.Tokens issued for one endpoint are not valid for the other. 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.Additionally, you cannot mix permissions for one endpoint with permissions for the other in a single request.

Der Azure AD v2.0-Endpunkt unterstützt nur den Fluss für Clientanmeldeinformationen für den Microsoft Graph-Endpunkt.The Azure AD v2.0 endpoint only supports the client credentials flow for the Microsoft Graph endpoint. Apps, die ein Nur-App-Token mit dem Outlook-Endpunkt verwenden müssen, müssen den Azure AD v1.0-Endpunkt verwenden.Apps that need to use an app-only token with the Outlook endpoint must use the Azure AD v1.0 endpoint.

Azure v1 OAuth2-EndpunktAzure v1 OAuth2 endpoint

Apps, die den Azure AD v1.0-Endpunkt verwenden, geben die erforderlichen Berechtigungen während der App-Registrierung im Azure-Portal an.Apps that use the Azure AD v1.0 endpoint specify their required permissions during app registration in the Azure Portal.

  • Wählen Sie für Microsoft Graph die Microsoft Graph-API beim Hinzufügen der erforderlichen Berechtigungen.For Microsoft Graph, choose the Microsoft Graph API when adding required permissions.
  • Wählen Sie für den Outlook-Endpunkt die Office 365 Exchange Online-API beim Hinzufügen der erforderlichen Berechtigungen.For the Outlook endpoint, choose the Office 365 Exchange Online API when adding required permissions.

Eigenschaftenname von RessourcenResource property names

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.The resources are the same between Microsoft Graph and Outlook. However, the two endpoints handle casing of the property names differently. Microsoft Graph uses camelCase for property names, while Outlook uses PascalCase. Translating between the two simply requires converting the case.

Die Microsoft Graph-Nachrichtenressource definiert beispielsweise Eigenschaften wie subject, from und receivedDateTime. Im Outlook-Endpunkt lauten die Namen dieser Eigenschaften Subject, From und ReceivedDateTime.For example, the Microsoft Graph message resource defines properties such as subject, from, and receivedDateTime. On the Outlook endpoint, these properties are named Subject, From, and ReceivedDateTime.

Nachverfolgen von Änderungen (Synchronisierung)Tracking changes (synchronization)

Beide Endpunkte unterstützen das Abfragen von Sammlungen im Hinblick auf Änderungen im Zusammenhang mit einem Synchronisierungsstatus.Both endpoints support querying collections for changes relative to a synchronization state. Die Funktionalität ist zwar identisch, die Methoden unterscheiden sich aber geringfügig.While the functionality is the same, the methods are slightly different.

Am Microsoft Graph-Endpunkt werden Änderungen mithilfe von Delta-Abfragen abgefragt.On the Microsoft Graph endpoint, changes are queried by using delta queries. Dies delta-Funktion für die Datensammlung implementiert.This is implemented as a delta function on the collection.

Am Outlook-Endpunkt werden Änderungen durch Hinzufügen eines Headers zu normalen Abfragen von Ressourcensammlungen abgefragt.On the Outlook endpoint, changes are queried by adding a header to normal resource collection queries.

BatchverarbeitungBatching

Beide Endpunkte unterstützen die Batchverarbeitung von bis zu 20 separaten Anforderungen in einer HTTP-Anforderung.Both endpoints support batching up to 20 separate requests into one HTTP request.

Bei der Microsoft Graph-Batchverarbeitung werden mehrere API-Anfragen in einem JSON-Nachrichtentext mit einem Inhaltstyp von application/json codiert.Microsoft Graph batching encodes multiple API requests into a JSON body with a content type of application/json.

Zusätzlich zum JSON-Format unterstützt die Batchverarbeitung am Outlook-Endpunkt auch ein mehrteiliges Textformat mit einem Inhaltstyps von multipart/mixed.In addition to the JSON body format, Outlook endpoint batching also supports a multi-part body format with a content type of multipart/mixed.

Beispiel: Abrufen einer NachrichtExample: retrieving a message

Betrachten wird ein einfaches Beispiel. In diesem Szenario fordert eine Web-App eine Liste von Nachrichten im Posteingang des Benutzers an.Let's take a look at a simple example. In this scenario, a web app requests a list of messages in the user's inbox.

Microsoft GraphMicrosoft 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:First, the app has the user sign in to authorize the application. Because the app uses the Microsoft Graph scope Mail.Read, the authorization URL looks like the following:

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:Once the app has an access token, it sends the following request:

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:The server returns the following response:

{
  "@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"
        }
      }
    }
  ]
}

OutlookOutlook

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:First, the app has the user sign in to authorize the application. Because the app uses the Outlook scope https://outlook.office.com/Mail.Read, the authorization URL looks like the following:

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:Once the app has an access token, it sends the following request:

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:The server returns the following response:

{
  "@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"
        }
      }
    }
  ]
}