Outlook REST API für Mail, Kontakte, Termine
Auf der MEC2014 wurde ein neuer Weg für den Zugriff auf Postfachinhalte jeder Art vorgestellt. Ich gehe davon aus, dass dieser Zugriff auch für Exchange On-Prem bald zur Verfügung stehen wird. Auslöser ist sicher, dass in der Cloud keine Zugriffe per MAPI/RPC oder CDO mehr möglich sind, und RPC/HTTP einen größeren Overhead hat. Gefragt sind also einfache Wege auf die Informationen zuzugreifen und EWS ist vielleicht nicht einfach genug. Da sind REST und JSON die neuen Schlagworte. Und der Zugriff ist so schlank, dass man sogar einen RaspberryPI oder Arduino dafür als Client einbinden kann.
Im Aug 2024 hat Microsoft Teams immer noch die /API-Verzeichnisse genutzt.
End of Live?
Am 4. März hat Microsoft über verschiedene Kanäle das "Ende" von GPAPH/REST für On-Premises Postfächer verkündet. Siehe auch Graph und Exchange On-Premises. Ich gehe davon aus, dass damit auch die On-Premises-Version der REST-API vermutlich nicht mehr weiter geführt wird oder zumindest unklar und damit keine stabile Option mehr ist.
Wer automatisiert mit Exchange On-Premises arbeitet, sollte daher weiter die Exchange Web Services (EWS) nutzen.
Outlook REST API v2.0 Deprecation Notice
(30. Nov 2022)
https://developer.microsoft.com/en-us/office/blogs/outlook-rest-api-v2-0-deprecation-notice/
Achtung: Diese API ist nicht für den
öffentlichen Zugriff gedacht sondern wird von Graph in der
Cloud als Proxy angesprochen.
Outlook REST API v2.0 and Beta deprecation update
(23. Nov 2022)
https://techcommunity.microsoft.com/t5/exchange-team-blog/outlook-rest-api-v2-0-and-beta-deprecation-update/ba-p/3682745
Verschoben aber soll 2023 kommen mit 6 Monaten
Vorankündigung. Wir sind also zumindest im Sommer 2023
Interessante Information in einem Twitter-Post von Ross
Shared mailboxes are coming real soon to
@Outlook mobile. Requires O365 accounts. #outlook #ems
https://twitter.com/RossSmithIV/status/1136742431830024203
Wenn ich den Text genau lese, dann ist es der Verzicht auf REST, EWS und ActiveSync, warum diese Funktion nur mit Exchange Online funktioniert. Das kann man aber auch so interpretieren, dass REST auch mit Exchange On-Premises ganz legitim genutzt werden kann. Auch in der Beschreibung zu Microsoft Graph befindet sich eine interessante Aussage:
Behind the scenes, when Microsoft Graph
identifies that a REST API call is attempting to access an
On-Premises mailbox in a hybrid deployment, it proxies the
REST request to an On-Premises REST endpoint which then
processes the request. This discovery makes accessing the
REST API possible.
Quelle:
https://docs.microsoft.com/de-de/graph/hybrid-rest-support
Damit sollte klar sein, dass auch das On-Premises-Verzeichnis "/REST" sogar aktiv von Graph aus der Cloud angesprochen wird.
- Graph und Exchange On-Premises
- REST - Representational State Transfer
- On-Premises Architectural Requirements
for the REST API
https://techcommunity.microsoft.com/t5/exchange-team-blog/On-Premises-architectural-requirements-for-the-rest-api/ba-p/605609
https://blogs.technet.microsoft.com/exchange/2016/09/26/On-Premises-architectural-requirements-for-the-rest-api/ (Alt)
Basis
Die meisten Lösungen erfordern nur wenige Basisfunktionen, die möglichst auf jedem Client zur Verfügung stehen sollten. HTTP bzw. HTTPS ist das präferierte Protokoll und die Parameter werden einfach per Parameter übergeben. Und dann könnte das wie folgt aussehen:
Die Hostnamen in den URLs hier sind keine realen Adressen und funktionieren natürlich nicht und selbst wenn ist natürlich eine Authentifizierung erforderlich.
- Die ersten 10 Nachrichten aus dem Posteigang lesen
https://owa.msxfaq.net/EWS/OData/Me/Inbox/Messages?$top=10 - Die nächsten 10 Mail lesen
https://owa.msxfaq.net/EWS/OData/Me/Inbox/Messages?$top=10&$skip=10 - Hole die 5 aktuellsten Mail nach "DateTimeCreated
https://owa.msxfaq.net/EWS/OData/Me/Inbox/Messages?$top=5&$orderby=DateTimeCreated - Gefilterte Anfrage auf ausgewählte Eigenschaften der ersten
20 Mails (Datenreduktion)
https://owa.msxfaq.net/EWS/OData/Me/Inbox/Messages?$top=20&$select=From,DateTimeCreated,Subject - Termine lesen, die später als das angegebene Datum sind
https://owa.msxfaq.net/EWS/OData/Me/Events?$top=5&$select=Subject,Start,End&$filter=Start ge 2014-03-04T20:00:00Z - Kontakte lesen, deren Namen den Teilstring "Carius"
enthalten
https://owa.msxfaq.net/EWS/OData/Me/Contacts?$top=10&$filter=contains(DisplayName,’Carius’) - Exchange 2016: REST Api für lokale Exchange Server
schon verfügbar?
https://www.frankysweb.de/exchange-2016-rest-api-fr-lokale-exchange-server-schon-verfgbar/
Sie sehen schon, wie einfach so eine Anfrage ist, wenn der Client sich erst einmal "authentifizieren" und die Rückantworten interpretieren kann. Die API lässt sich für den Zugriff auf die eigene Mailbox als auch auf eine andere Mailbox nutzen. Man muss nur den Pfad entsprechend anpassen:
- Eigene Mailbox
https://owa.msxfaq.net/ews/odata/Me - Anderes Postfach
https://owa.msxfaq.net/ews/odata/Users(‘Username@msxfaq.net’)
Auf der MSDN gibt es weitergehende Artikel:
-
Mail
https://msdn.microsoft.com/office/office365/APi/mail-rest-operations -
Calendar
https://msdn.microsoft.com/office/office365/APi/calendar-rest-operations -
Contact
https://msdn.microsoft.com/office/office365/APi/contacts-rest-operations
Auf dem Server
Wie Microsoft die Rest-API auf Office 365 umgesetzt hat, kann man leider nicht einsehen. Aber da die Rest API mittlerweile auch auf dem "On-Prem-Server" vorhanden ist, können Sie hier natürlich schauen.
Das virtuelle Verzeichnis /API ist mit Exchange 2016 CU3 erstmals im IIS-Manager aufgetaucht. Das Verzeichnis "/REST" war aber schon seit CU1 in den Installationsquellen aber wurde wohl vorher noch nicht eingebunden.
Das virtuelle Verzeichnis "/API", gibt es sowohl auf dem Frontend Server als auch auf dem Backend:
- Virtuelles Verzeichnis /API auf dem
Frontend
- Virtuelles Verzeichnis auf dem Backend
Hier noch ein paar weitere Details:
Frontend | Backend | |
---|---|---|
Basisverzeichniss | C:\Program Files\Microsoft\Exchange Server\V15\FrontEnd\HttpProxy\Rest |
C:\Program Files\Microsoft\Exchange Server\V15\ClientAccess\rest |
ApplicationPool |
MSExchangeRestFrontEndAppPool |
MSExchangeRestAppPool |
Authentication | Anonymous |
Anonymous |
SSL Setting | Required, Ignore Client Cert |
Required, Ignore Client Cert |
Verwaltung per PowerShell
Auch wenn es seit CU3 die virtuellen Verzeichnisse im IIS gibt, so liefern die entsprechenden PowerShell Commandlets auch mit CU3 noch keine Rückgabe.
[PS] C:\Windows\system32>get-command *-RestVirtualDirectory CommandType Name ----------- ---- Function Get-RestVirtualDirectory Function New-RestVirtualDirectory Function Remove-RestVirtualDirectory Function Set-RestVirtualDirectory
Das virtuelle Verzeichnis ist schon vorhanden aber nicht als "RestVirtualDirectory" gelistet. Ich bin gespannt, ab wann diese Funktion "offiziell" vorhanden ist.
Autodiscover
Mit Autodiscover V2 können Sie sehr einfach ein Einstiegspunkt per REST auf eine Mailbox ermitteln.
Invoke-RestMethod -Uri ‘https://autodiscover.msxfaq.de/autodiscover/autodiscover.json?Email=User@msxfaq.de&Protocol=REST’ Protocol Url -------- --- REST https://outlook.msxfaq.de/api
Authentifizierung
In der Office 365 Umgebung geht das natürlich nicht einfach per "Benutzername/Kennwort", denn in der Cloud sind andere Verfahren, z.B. ADFS, üblich. Ihr Client wird sich daher beim Zugriff einen 401-Fehler einfangen, in dem Der Weg zur Authentifizierungsserver hinterlegt ist. für den Einsatz On-Prem hingegen wird man die Anmeldung gleich als HTTP-Anmeldung mit übergeben.
Beispiele folgen später.
- Outlook REST API v1.0 BasicAuth
Deprecation
https://developer.microsoft.com/en-us/office/blogs/outlook-rest-api-v1-0-basicauth-deprecation/ - Get access tokens to call Microsoft
Graph
https://docs.microsoft.com/de-de/graph/auth-overview - Migrating from Outlook REST API v1.0 to
Microsoft Graph
https://developer.microsoft.com/en-us/office/blogs/migrating-from-outlook-rest-api-v1-0-to-microsoft-graph/
API-Verzeichnis und Microsoft Teams
Wer das /API-Verzeichnis von Exchange OnPremises in welcher Form und Intensität nutzt, können Sie über die Auswertung der IISLogs kontrollieren. Interessanter ist aber ein Tracing der Aufrufe über
IIS - Webserver Troubleshooting
Rückmeldung
Abhängig von Programm, das sie nutzen, sind die Rückgaben bereits aufbereitet. Wer z.B. mit der PowerShell ein "Invoke-RESTMethod" nutzt, bekommt ein schöne PowerShell Objekt zurück, welches sehr einfach ausgewertet werden kann.
Beispiele folgen später
Offen: App Passwort
So schön die Anmeldung per Credentials oder per ADFS-Tokens ist, so risikobehaftet ist dies natürlich insbesondere für Dienste, die auf Postfächer zugreifen wollen. Wie schon auf App Password beschrieben, fehlt mir auch hier die Option ein sehr langes Kennwort für eine Applikation zu hinterlegen, welches dann auch nur für diesen Zugriff genutzt werden kann.
Beispiele folgen später.
Offen: Impersonation
Eine der großen Stärken von EWS ist die Möglichkeit der Impersonation, d.h. sich als anderer Benutzer auszugeben. Ich bin gespannt ob und wann das auch per REST möglich sein wird.
Weitere Links
- EWS
- REST - Representational State Transfer
- Graph und Exchange On-Premises
- On-Premises Architectural
Requirements for the REST API
https://blogs.technet.microsoft.com/exchange/2016/09/26/On-Premises-architectural-requirements-for-the-rest-api/ - Exchange Server 2016 REST
Api
https://www.frankysweb.de/exchange-server-2016-rest-api/ - Searching Mailbox folders
using the REST API In Powershell
on Office365 and Exchange 2016
http://gsexdev.blogspot.de/2018/02/searching-mailbox-folders-using-rest.html - MEC 2014: Vortrag: 0 To 60 Developing Apps für Outlook, Exchange Online, And
Office 365.pptx
http://channel9.msdn.com/Events/MEC/2014/EXT301 - MEC 2014: Achieving better business productivity using Apps für Office and
Office 365
http://channel9.msdn.com/Events/MEC/2014/EXT304 - Using the Office365/Exchange
2016 REST API Calendaring
https://gsexdev.blogspot.com/2017/09/using-office365exchange-2016-rest-api.html - Exchange 2016: REST Api für
lokale Exchange Server
schon verfügbar?
https://www.frankysweb.de/exchange-2016-rest-api-fr-lokale-exchange-server-schon-verfgbar/ - Using the Office 365 Odata API für accessing Exchange data from a MVC
application
http://wp.sjkp.dk/using-the-office-365-odata-api-for-accessing-exchange-data-from-mvc-application/ - Exchange Online Mailbox Access from PowerShell via REST
http://blogs.utexas.edu/glenmark/2014/04/30/exchange-online-mailbox-access-from-PowerShell-via-rest/ - Oneliner Mailbox access with PowerShell in Exchange Online using the oData
preview
http://gsexdev.blogspot.de/2014/04/oneliner-mailbox-access-in-PowerShell.html - Dynamics 2013: OData Web Services
http://msdn.microsoft.com/en-us/library/hh166950(v=nav.71).aspx