Vergleich der Microsoft Graph- und Outlook-REST-API-EndpunkteCompare the 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 the 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?

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.Microsoft recommends using the Microsoft Graph whenever possible. The Microsoft Graph APIs include more features than just Outlook-related APIs, including OneDrive and Active Directory. Choosing the Microsoft Graph endpoints 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.

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.However, there are some features that are either only available on the Outlook endpoint, or are only in beta on the Microsoft Graph. If your app needs these features, you should choose the Outlook endpoints.

Features, die nur im Outlook-Endpunkt verfügbar sindFeatures only available on the Outlook endpoint

FeatureFeature BeschreibungDescription
Outlook-AufgabenOutlook Tasks Die Outlook-API bietet Zugriff auf Benutzeraufgaben. Dieses Feature steht derzeit nur in der Beta-API des Microsoft Graph-Endpunkts zur Verfügung.The Outlook API provides acccess to user's tasks. This feature is currently only available in beta on the Microsoft Graph endpoint.

Umwandeln zwischen Graph und OutlookTranslating between Graph and 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.The majority of the Outlook APIs are documented in the Microsoft Graph API reference documentation. In order to use this information on the Outlook endpoint, you need to translate a few bits of information.

API-VersionenAPI versions

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.The Microsoft Graph API offers two versions: v1.0 and beta, while Outlook offers v1.0, v2.0, and beta. Microsoft Graph v1.0 matches Outlook v2.0, and Microsoft Graph beta matches Outlook beta.

OAuth-BereicheOAuth scopes

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.While the Microsoft Graph and Outlook endpoints both rely on Azure AD-issued tokens, the scopes that each endpoint are slightly different. Apps that use Microsoft Graph request scopes like Mail.Read or Calendars.Write.Shared. Tokens generated by requesting these scopes will not be valid for the Outlook endpoint.

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.To translate the scopes, simply qualify them with https://outlook.office.com/. For example, the Microsoft Graph scope Mail.Read translates to https://outlook.office.com/Mail.Read for the Outlook endpoint.

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 the 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.

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": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEMAACd9nJ-tVysQos2hTfspaWRAAD8tDzlAAA=",
      "receivedDateTime": "2015-11-03T03:21:04Z",
      "subject": "Scrum",
      "isRead": false,
      "from": {
        "emailAddress": {
          "name": "user0TestUser",
          "address": "user0@a830edad9050849NDA1.onmicrosoft.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": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEMAACd9nJ-tVysQos2hTfspaWRAAD8tDzlAAA=",
      "ReceivedDateTime": "2015-11-03T03:21:04Z",
      "Subject": "Scrum",
      "IsRead": false,
      "From": {
        "EmailAddress": {
          "Name": "user0TestUser",
          "Address": "user0@a830edad9050849NDA1.onmicrosoft.com"
        }
      }
    }
  ]
}