Vergleich der Microsoft Graph- und Outlook-REST-API-Endpunkte
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.
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.
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. |
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.
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
.
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.
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 dieMail.Read
-Berechtigung durch Einschließen vonhttps://graph.microsoft.com/Mail.Read
imscope
-Parameter anfordern. - Für den Outlook-Endpunkt geben Apps die Berechtigungen mit dem Präfix
https://outlook.office.com/
an. Beispiel: Eine App kann dieMail.Read
-Berechtigung durch Einschließen vonhttps://outlook.office.com/Mail.Read
imscope
-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.
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.
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
, from
und receivedDateTime
. Auf dem Outlook-Endpunkt heißen Subject
diese Eigenschaften , From
und ReceivedDateTime
.
Die folgenden Eigenschaftennamen sind unterschiedlich zwischen Microsoft Graph und Outlook.
Ressourcentyp | Microsoft Graph-Eigenschaft | Outlook-Eigenschaft |
---|---|---|
contact |
mobilePhone |
MobilePhone1 |
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.
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
.
Betrachten wir ein einfaches Beispiel. In diesem Szenario fordert eine Web-App eine Liste von Nachrichten im Posteingang des Benutzers an.
Zunächst muss sich der Benutzer für die App anmelden, 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": "AAMkAGI2...",
"receivedDateTime": "2015-11-03T03:21:04Z",
"subject": "Scrum",
"isRead": false,
"from": {
"emailAddress": {
"name": "user0TestUser",
"address": "user0@contoso.com"
}
}
}
]
}
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.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": "AAMkAGI2...",
"ReceivedDateTime": "2015-11-03T03:21:04Z",
"Subject": "Scrum",
"IsRead": false,
"From": {
"EmailAddress": {
"Name": "user0TestUser",
"Address": "user0@contoso.com"
}
}
}
]
}