Verwenden der Outlook REST-API (Version 2.0)

  • Artikel

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

Hinweis

Verwenden Sie Microsoft Graph, um umfassendere Szenarien für Microsoft 365-Dienste einschließlich Outlook zu erstellen. Erfahren Sie, wie Sie zur Microsoft Graph-basierten Outlook REST API übergehen.

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.

API-Teilmenge Verfügbare Versionen
Batchverarbeitung mehrerer API-Aufrufe v2.0, Beta
Kalender-API v2.0, v1.0, Beta
Kontakte-API v2.0, v1.0, Beta
Datenerweiterungen-API v2.0, Beta
API für erweiterte Eigenschaften v2.0, Beta
Mail-API v2.0, v1.0, Beta
Pushbenachrichtigungs-API v2.0, Beta
Streaming-Benachrichtigungen API (Vorschauversion) Beta
Personen-API Beta
Aufgaben-API v2.0, Beta
Benutzerfoto-API v2.0, Beta

Hinweis

Der Rest dieses Artikels beschreibt allgemeine Informationen, die für alle Untergruppen der Outlook REST-API gelten. Zur Vereinfachung des Verweises verwendet der Rest dieses Artikels Outlook.com , um Konten in den Domänen Hotmail.com, Live.com, MSN-, 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.

Wichtig

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.

Hinweis

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. Weitere Informationen finden Sie unter Verwenden von Windows Live-Bereichen und der Outlook-REST-API für den Zugriff auf Outlook.com-Postfachdaten.

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.

Wichtig

  • 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. Sie können zum Testen des Datenzugriffs Ihre Anwendung auf bereits aktivierte Outlook.com-Postfächer ein neues, aktiviertes Outlook.com-Entwicklervorschaukonto über eine E-Mail an outlookdev@microsoft.com anfordern.
  • 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 Bereiche Outlook-REST-API-Bereiche
wl.basic User.Read, Contacts.Read
wl.calendars Calendars.Read
wl.calendars_update Calendars.ReadWrite
wl.contacts_create Contacts.ReadWrite
wl.contacts_calendars Calendars.Read
wl.emails User.Read
wl.events_create Calendars.ReadWrite
wl.imap Mail.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 https://outlook.office365.com/api/{version}/{user_context} verwendet, wird Ihr Code noch eine Weile für Office 365 funktionieren, aber Sie sollten planen, auf die neue Stamm-URL zu wechseln.

Wichtig

Für eine optimale Leistung fügen Sie bei einer REST-Anfrage mit der neuen Stamm-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 Fehlercodes 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-Endpunkt und 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 kann im Produktionscode verwendet werden. Ein Beispiel für eine URL ist http://outlook.office.com/api/v1.0/me/events.

  • 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.com werden.

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

Die Verwendung ist eine Frage der Vorliebe.

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

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-Clientbibliotheken erleichtern die Interaktion mit der REST-API:

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. Für den Abschluss dieses Übergangs schalten wir den alten Vorschau-Endpunkt https://outlook.office365.com/ews/odata am 15. Oktober 2015 ab.

Wir forderten an, dass alle Anwendungen und Dienste, die den alten Endpunkt https://outlook.office365.com/ews/odata verwenden, bis zum 15. Oktober 2015 zu https://outlook.office.com/api/v1.0 übergehen. v1.0 war 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: