Table of contents
TOC
Inhaltsverzeichnis reduzieren
Inhaltsverzeichnis erweitern
Zuletzt aktualisiert: 20.06.2018

Verwenden der Outlook REST-API

Gilt für: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Version 1.0 der Outlook REST API ist veraltet. Ab 1. November 2018können Anwendungen die Standardauthentifizierung nicht mehr mit dem REST-Endpunkt v1.0 verwenden (https://outlook.office.com/api/v1.0)). Ab dem 1. November 2019wird der v1.0 REST-Endpunkt vollständig stillgelegt und die v1.0-Dokumentation kurz darauf entfernt. Starten Sie die Migration Ihrer Anwendung zur Verwendung der Outlook REST API in v1.0 von Microsoft Graph. Weitere Details finden Sie in unserer Ankündigung.

Die Outlook REST-API enthält die folgenden Untergruppen, um den Zugriff auf die Postfachdaten der Benutzer in Office 365, Hotmail.com, Live.com, MSN.com, Outlook.com und Passport.com zu ermöglichen. Die folgende Tabelle listet die erste Version auf, in der die Kernfunktionalität jeder Teilmenge verfügbar gemacht wurde. Beachten Sie, dass innerhalb einer Teilmenge neue Funktionen und APIs nachträglich zu einer späteren Version hinzugefügt werden können. Beispielsweise wurde die Kalender-API in v1.0 eingeführt, und das Feature, das Besprechungszeiten vorschlägt, ist derzeit nur in der Beta-Version verfügbar, nicht jedoch in v1.0 oder v2.0.

API-TeilmengeVerfügbare Versionen
Kalender-APIv1.0 und später
Kontakte-APIv1.0 und später
Datenerweiterungen APIv2.0 und später
API für erweiterte Eigenschaftenv2.0 und später
Mail-APIv1.0 und später
Pushbenachrichtigungen-APIv2.0 und später
Streaming-Benachrichtigungen API (Vorschau)Beta
Personen API (Vorschau)Beta
Aufgaben-APIv2.0 und später
Benutzerfoto-APIv2.0 und später
Batchverarbeitung mehrerer API-Aufrufev2.0 und später

Notiz

Der Rest dieses Artikels beschreibt allgemeine Informationen, die für alle Untergruppen der Outlook REST-API gelten. Wegen der Einfachheit des Verweises verwendet der Rest dieses Artikels "Outlook.com", um Konten in den Domänen Hotmail.com, Live.com, MSN.com, Outlook.com und Passport.com. einzubeziehen.

Registrieren und authentifizieren Ihrer App

Um die Outlook REST-API für den Zugriff auf die Postfachdaten eines Benutzers zu verwenden, sollte Ihre App die Registrierung und Benutzerautorisierung übernehmen:

  1. Registrieren Sie zunächst Ihre App, um Zugriff auf die Outlook REST-API zu erhalten. Anschließend können Sie die API-Aufrufe in Ihrer App implementieren.

  2. Erwerben Sie zur Laufzeit die Autorisierung des Benutzers und stellen Sie REST-API-Anforderungen für den Zugriff auf das Postfach des Benutzers.

Derzeit gibt es zwei Ansätze, um die Registrierung von Anwendungen und die Autorisierung von Benutzern zu handhaben:

Azure AD v2 Authentifizierungs-Endpunkt

Der Azure AD v2-Authentifizierungs-Endpunkt vereinfacht die Erstellung einer App, die sowohl mit Microsoft-Organisationskonten als auch mit persönlichen Konten funktioniert. Er ermöglicht Benutzern von Arbeit, Schule und persönlichem Konto, sich mit einer einzigen Schaltfläche anzumelden.

Dieses konvergierte Programmiermodell ist der neueste Ansatz, der Folgendes umfasst:

Dieser Ansatz bietet Ihnen eine nahtlose App-Registrierung und Benutzerautorisierung, um die entsprechenden Token für den Zugriff auf die Postfachdaten der Benutzer auf Office 365 und/oder Outlook.com zu erhalten. Wenn Sie eine App für Outlook.com entwickeln, müssen Sie diesen Ansatz verwenden.

Anstatt während der App-Registrierung Berechtigungen anzufordern, können Sie auf dem v2-Authentifizierungs-Endpunkt die erforderlichen Berechtigungen zur Laufzeit auf der Grundlage entsprechender Benutzeraktionen dynamisch anfordern und anfragen.

Dieses konvergierte Programmiermodell besteht aus mehreren Komponenten, wenn Sie also eine Komponente verwenden, sollten Sie auch die anderen verwenden. Weitere Informationen finden Sie unter Beispiele für die ersten Schritteund Authentifizierung von Office 365 und Outlook.com-APIs mit dem v2-Authentifizierungs-Endpunkt.

Achtung

Wenn Sie eine Anwendung erstellen oder aktualisieren, stellen Sie sicher, dass Ihre Anwendung mit aktivierten Outlook.com-Postfächern umgehen kann und Sie über die Outlook REST-API darauf zugreifen können, sowie mit solchen Postfächern, die darauf warten, aktiviert zu werden. Erfahren Sie mehr über Prüfung und Handhabung solcher Outlook.com-Szenarien.

Registrieren und authentifizieren mit Azure AD und OAuth

Dies ist ein früherer Ansatz, um auf Postfachdaten nur in Office 365 zuzugreifen. Wenn Sie planen, auf Daten auf Outlook.com zuzugreifen oder eine neue App für Office 365 zu erstellen, verwenden Sie stattdessen den v2-Authentifizierungs-Endpunkt.

Um auf Office 365-Postfachdaten zuzugreifen, können Sie wie bisher eine App in Azure AD registrieren, indem Sie die Berechtigungen im entsprechenden Umfang angeben, die Ihre App benötigt. Zur Laufzeit kann Ihre App weiterhin Azure AD und OAuth zur Authentifizierung von App-Anforderungen verwenden. Details finden Sie unter Office 365 App Authentfizierungs-Konzepte. Sie sollten einen Aktualisierungs-Pfadaktualisieren.

Bei diesem Ansatz können Sie auf die Outlook-REST-API zugreifen, indem Sie sie direkt in Ihren Office 365-Anwendungen aufrufen oder indem Sie die Office 365-Client-Bibliotheken verwenden.

Pfad aktualisieren

Der Endpunkt für die v2-Authentifizierung wurde für Outlook- und Outlook.com-Entwickler von der Vorschau in den Status "Allgemein verfügbar" (GA) befördert. Wenn Sie eine produktive Anwendung haben, die auf Office 365-Postfachdaten zugreift, oder wenn Sie eine neue App für Office 365 oder Outlook.com erstellen, planen Sie, den v2-Authentifizierungs-Endpunkt zusammen mit dem neuesten Outlook-Endpunkt (https://outlook.office.com/, siehe weiter unten) zu verwenden, um nur einen Satz Codes für Office 365- und Outlook.com-Benutzer zu schreiben.

Wenn Sie eine produktive Anwendung haben, die die Windows Live-API verwendet, um auf die Postfachdaten von Outlook.com zuzugreifen, müssen Sie die Anwendung neu schreiben, um den Endpunkt der v2-Authentifizierung und die Outlook REST-API zu verwenden. Da die Windows Live-API für Outlook.com veraltet ist und Outlook.com-Benutzer ihre Postfächer für die Outlook REST-API aktivieren, erhalten diese Benutzer HTTP 404-Fehler, wenn sie versuchen, solche Windows Live-API-Apps auszuführen. Andererseits eröffnet Ihnen die Outlook REST API neue Möglichkeiten - Sie können aus einer Liste gängiger Sprachen wie Node, Python, Swift, Java usw. wählen, die App einmal schreiben und sowohl Benutzer von Outlook.com als auch von Office 365 im Web, iOS, Android oder Windows-Geräten erfassen.

Notiz

Wenn Sie beabsichtigen, dass Ihre produktive Anwendung weiterhin nur auf Outlook.com-Postfachdaten zugreift, können Sie weiterhin dieselben Windows Live-Bereiche verwenden, um auf die meisten der Outlook REST-API zuzugreifen. Finden Sie unter
Verwenden von Windows Live-Bereichen und der Outlook REST-API für den Zugriff auf Outlook.com-Postfachdaten weitere Informationen.

Unabhängig vom Ansatz, den Sie für die App-Registrierung und Benutzerautorisierung verwenden, oder ob Ihre App Office 365- oder Outlook.com-Postfachdaten anspricht, ist der neueste Outlook-REST-Endpunkt in Produktion und Sie können ihn jederzeit in Ihren REST-API-Aufrufen verwenden, wann immer Sie bereit sind:

https://outlook.office.com/api/{version}/{user_context}

Der folgende Outlook REST-Endpunkt funktioniert noch eine Weile nur für Office 365-Postfachdaten:

https://outlook.office365.com/api/{version}/{user_context}

Siehe mehr über unterstützte REST-Aktionen, Endpunkte und Versionen unten.

Achtung

  • Die Basisberechtigung wird vom Outlook REST API Endpunkt https://outlook.office.comnicht mehr unterstützt. Verwenden Sie den v2-Authentifizierungs-Endpunkt oder Azure AD, um die Autorisierung und Authentifizierung für eine Anwendung durchzuführen, die den neuen Outlook REST-API-Endpunkt verwendet.
  • Für eine optimale Performance bei der Verwendung des neuen Outlook REST-Endpunkts fügen Sie für jede Anfrage einen x-AnchorMailbox Header hinzu und setzen ihn auf die E-Mail-Adresse des Benutzers. Beispiel: x-AnchorMailbox:john@contoso.com
  • Da die Aktivierung von Postfächern auf Outlook.com für die Outlook-REST-API über einen längeren Zeitraum erfolgt, kann es einige Zeit dauern, bis Ihr vorhandenes Outlook.com-Konto aktiviert wird. Um Ihre App auf Daten in einem aktivierten Postfach zu testen, können Sie sich für ein neues Outlook.com-Konto hieranmelden. Alle neuen Konten werden sofort für die REST API aktiviert.
  • Wenn Ihre Anwendung auf Outlook.com-Postfachdaten zugreift, sollte sie Szenarien behandeln, in denen das Postfach des Benutzers noch nicht für die Outlook REST-API aktiviert wurde. In solchen Situationen erhalten Sie, wenn Sie eine REST-Anfrage stellen, erhalten Sie eine Fehlermeldung wie die folgende:
    • HTTP-Fehler: 404
    • Fehlercode: MailboxNotEnabledForRESTAPI oder MailboxNotSupportedForRESTAPI
    • Fehlermeldung "REST API wird für dieses Postfach noch nicht unterstützt.
  • Code-Beispiele, die den v2-Authentifizierungs-Endpunkt verwenden, finden Sie unter dev.outlook.com.

Verwenden von Windows Live-Bereichen und der Outlook REST-API für den Zugriff auf Outlook.com-Postfachdaten

Wenn Ihre produktive App für Outlook.com Windows Live-Bereiche verwendet und Sie nicht beabsichtigen, Office 365-Postfachdaten zu verwenden, können Sie diese Windows Live-Bereiche weiterhin mit den meisten der Outlook REST-API verwenden. Die folgende Tabelle zeigt, wie Windows Live-Bereiche den Outlook REST-API-Bereichen zugeordnet werden. Beachten Sie, dass es keine direkte Zuordnung des Windows Live-Bereich für Mail.Read gibt. Ihre Anwendung kann mit wl.imap auf die Outlook-REST-API-Vorgänge zugreifen, für die Mail.Read erforderlich ist.

Windows Live BereicheOutlook REST-API-Bereiche
wl.basicUser.Read, Contacts.Read
wl.calendarsCalendars.Read
wl.calendars_updateCalendars.ReadWrite
wl.contacts_createContacts.ReadWrite
wl.contacts_calendarsCalendars.Read
wl.emailsUser.Read
wl.events_createCalendars.ReadWrite
wl.imapMail.ReadWrite, Mail.Send

Unterstützte REST-Aktionen und Endpunkte

Um mit der Video-REST-API zu interagieren, senden Sie HTTP-Anforderungen, die eine unterstützte Methode anwenden: GET, POST, PATCH oder DELETE. POST und PATCH erfordern Texte und Server-Antworten werden in JSON-Payloads gesendet.

Bei den Pfad-URL-Ressourcennamen und Abfrageparametern wird Groß-/Kleinschreibung unterschieden. Bei zugewiesenen Werte, Entitäts-IDs und anderen base64-codierte Werten wird zwischen Groß-/Kleinschreibung unterschieden.

Alle Outlook REST-API-Anforderungen verwenden das folgende neue Root-URL-Format:

https://outlook.office.com/api/{version}/{user_context}

Mit der entsprechenden Benutzerberechtigung bietet die REST-API in dieser Stamm-URL Zugriff auf Postfachdaten auf Office 365 und Outlook.com. Der Rest dieses Artikels beschreibt die REST-API in diesem Endpunkt.

Wenn Sie einen Code haben, der die bereits existierende Stamm-URL verwendet:

https://outlook.office365.com/api/{version}/{user_context}

Ihr Code wird noch eine Weile für Office 365 funktionieren, aber Sie sollten planen, auf die neue Root-URL zu wechseln.

Achtung Für eine optimale Leistung fügen Sie bei einer REST-Anfrage mit der neuen Root-URL einen x-AnchorMailbox Header hinzu und setzen Sie ihn auf die E-Mail-Adresse des Benutzers. Behandeln Sie auch den Fall, in dem das Postfach eines Outlook.com-Benutzers noch nicht für die Outlook-REST-API aktiviert wurde - suchen Sie nach den Fehlernummern MailboxNotEnabledForRESTAPI und MailboxNotSupportedForRESTAPI. Mehr erfahren Sie hier.

Hinweise für Entwickler in China

  • Wenn Sie Anwendungen für Office 365 in China entwickeln, sollten Sie weiterhin die API-Endpunkte von Office 365 für Chinaverwenden.

  • Wenn Sie Anwendungen für Outlook.com in China erstellen, versuchen Sie den v2-Authentifizierungs-Endpunktund verwenden Sie den folgenden neuen Outlook REST-Endpunkt: https://outlook.office.com/api/{version}/{user_context}

Unterstützte Versionen der API

{version} stellt die Version der Outlook REST-API in der angegebenen Root-URL dar. Sie können einen der folgenden Werte angeben:

  • v1.0. Dies ist die früheste Version im Status Allgemeine Verfügbarkeit (GA) und sie ist veraltet. Ein Beispiel für eine URL ist http://outlook.office.com/api/v1.0/me/events. Migrieren Sie Ihre Anwendung auf Microsoft Graph. Weitere Details finden Sie in unserer Ankündigung.

  • v2.0. Diese Version befindet sich ebenfalls im GA-Status und kann im Produktionscode verwendet werden. Ein Beispiel für eine URL ist http://outlook.office.com/api/v2.0/me/events. Diese Version enthält Änderungen, die v1.0 brechen können, und zusätzliche API-Sets, die gereift sind und von der Vorschau zum GA-Status befördert wurden.

  • beta. Diese Version befindet sich im Vorschau-Status und sollte nicht im Produktionscode verwendet werden. Ein Beispiel für eine URL ist http://outlook.office.com/api/beta/me/events. Diese Version enthält die neueste API in GA, sowie zusätzliche API-Sets, die sich in der Vorschau befinden und sich vor der Fertigstellung ändern können.

Der Großteil der REST-Operationen in der Outlook REST-API wird unterstützt und verhält sich in gleicher Weise wie in den oben genannten Versionen beschrieben.

Ziel-Benutzer

Mit Ausnahme der Benutzer Photo-REST-API ist {user_context} der derzeit angemeldete Benutzer, da die Anforderungen der Outlook-REST-API immer im Namen des aktuellen Benutzers ausgeführt werden.

Für die Benutzer Photo-REST-API kann {user_context} der angemeldete Benutzer oder ein Benutzer sein, der durch eine Benutzer-ID festgelegt wurde.

Unabhängig vom Set der Outlook REST-API können Sie {user_context} in REST Anforderungen auf eine der folgenden Arten angeben:

  • Mit der me Abkürzung: /api/{version}/me. Die Stamm-URL wird https://outlook.office.com/api/{version}/me.
  • Mit dem Format users/{upn} , um die UPN oder eine Proxy-Adresse des angemeldeten Benutzers zu übergeben, z.B.: /api/beta/users/sadie@contoso.com. In diesem Beispiel würde die Stamm-URL https://outlook.office.com/api/beta/users/sadie@contoso.comwerden.

  • Mit dem Format users/{AAD_userId@AAD_tenandId} unter Verwendung der Benutzer-ID und der Mandanten-ID in Azure Active Directory. Zum Beispiel: users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77. Die Stamm-URL würde https://outlook.office.com/api/beta/users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77werden.

Die Verwendung ist eine Frage der Vorliebe.

In den _Antworten_des Servers wird der Benutzerkontext in diesem Format identifiziert: users/{AAD_userId@AAD_tenandId}.

  • Mit dem Format users/{upn} , um die UPN oder eine Proxy-Adresse des angemeldeten Benutzers zu übergeben, z.B.: /api/beta/users/sadie@contoso.com. In diesem Beispiel würde die Stamm-URL https://outlook.office.com/api/beta/users/sadie@contoso.comwerden.

  • Mit dem Format users/{AAD_userId@AAD_tenandId} unter Verwendung der Benutzer-ID und der Mandanten-ID in Azure Active Directory. Zum Beispiel: users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77. Die Stamm-URL würde https://outlook.office.com/api/beta/users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77werden.

Die Verwendung ist eine Frage der Vorliebe.

In den _Antworten_des Servers wird der Benutzerkontext in diesem Format identifiziert: users/{AAD_userId@AAD_tenandId}.

  • Mit dem Format users/{upn} , um die UPN oder eine Proxy-Adresse des angemeldeten Benutzers zu übergeben, z.B.: /api/v1.0/users/sadie@contoso.com. In diesem Beispiel würde die Stamm-URL https://outlook.office.com/api/v1.0/users/sadie@contoso.comwerden.

Die Verwendung ist eine Frage der Vorliebe. In Serverantworten wird der Benutzerkontext in diesem Format identifiziert: /api/v1.0/users('sadie@contoso.com')

Zugriff auf ein Objekt in einer Sammlung

Die Outlook REST-API unterstützt zwei Möglichkeiten, ein Element in einer Entity-Sammlung anzugeben. Sie werden identisch ausgewertet, so dass die Verwendung eine Frage der Präferenz ist.

  • Zum Beispiel im URL-Segment nach der Sammlung: /api/{version}/me/events/AAMkAGI3...

  • In Klammern z.B. als Anführungszeichenkette: /api/{version}/me/events('AAMkAGI3...')


Verwenden Sie eine Client-Bibliothek, um auf die Outlook REST-API zuzugreifen

Die Office 365 API-Client-Bibliotheken erleichtern die Interaktion mit der REST-API: .NET, JavaScript, Androidund iOS. Sie helfen bei der Verwaltung von Authentifizierungstoken und vereinfachen den Code für die Abfrage und Verwendung von Daten in Office 365.


Herunterfahren eines früheren Vorschau-Endpunkts

Wenn Sie bereits https://outlook.office.com/api oder https://outlook.office365.com/api als Stamm-URL verwenden
um auf die Outlook REST-API zuzugreifen, wirkt sich diese Missbilligung nicht auf Sie aus. Lesen Sie weiter, wenn Sie noch den früheren Vorschau-Endpunkt https://outlook.office365.com/ews/odataverwenden.

Die Outlook-REST-API wurde im Oktober 2014 von ihrer ursprünglichen Vorschau auf die allgemeine Verfügbarkeit v1.0 verschoben. Um diesen Übergang abzuschließen, schalten wir den alten Vorschau-Endpunkt https://outlook.office365.com/ews/odata am 15. Oktober 2015ab.

Wir benötigen alle Apps & Services, die den alten Endpunkt verwenden:

https://outlook.office365.com/ews/odata

um umzuziehen zum:

https://outlook.office.com/api/v1.0

  1. Oktober 2015 v1.0 ist der minimale allgemeine Verfügbarkeitsendpunkt (GA), der bis zu diesem Datum erreicht werden muss.

Alternativ können Sie den bevorzugten GA-Endpunkt v2.0 (https://outlook.office.com/api/v2.0) oder den Vorschau-Endpunkt (https://outlook.office.com/api/beta) verwenden, um die neuesten APIs im Vorschau-Status zu testen. Beachten Sie, dass sich der Status der API in der Vorschau im Allgemeinen vor der Fertigstellung ändern kann. Wenn Sie sie verwenden, sollten Sie darauf vorbereitet sein, die Funktionen in Ihrer App zu überprüfen und entsprechende Änderungen vorzunehmen. Wenn die APIs in der Vorschau fertiggestellt sind, können Sie auch auf diese Verbesserungen in einem GA-Endpunkt zugreifen.

Nächste Schritte

Fahren Sie mit der Verwendung der Outlook REST-API fort:

© 2018 Microsoft