Download RopID

Exchange Protocols Overview
Andrew Davidoff
Senior Software Engineer
Microsoft Corporation
Agenda
Brief introduction to Exchange Server Open Specifications
An overview of the protocol architecture for Exchange
Important protocol families that are used to communicate with
Exchange Server
Introduction to Open Specifications
Normative language
Designed to document bits over the wire
No APIs – only Protocols
Normative and informative content
Follows RFC 2119
MUST, SHOULD, MAY are used to document version-specific behavior
Strict document structure
Windows/Exchange or product API knowledge not required…
Microsoft Products are not mentioned in normative content, only in endnotes
We are striving to make our Open Specifications complete, accurate
and implementable
Exchange Protocols
Overview Document
[MS-OXPROTO]
Defines Exchange protocol families
Informative and Scenario-Based
How multiple protocols work together
in typical scenarios
How to complete the same task using
different protocol families
Walkthroughs and examples
Send email via RPC/ROPs, EWS, or
Exchange ActiveSync
Resolve a recipient from an Address
Book
Synchronize items
Provision mobile client using Exchange
ActiveSync
Many other scenarios
Protocol families
Remote Operations (a.k.a. RPC)
Exchange Web Services (EWS)
Exchange ActiveSync (EAS)
Other groups of protocols
Autodiscover
Name Service Provider Interface (NSPI)
Content Conversion
Standards Support
Client communication with Exchange
EAS
EWS
RPC/ROPs
POP/IMAP
SMTP
Storage
Exchange RPC/ROPs protocols
Implemented in some form from “Day 1” (such as Exchange 4.0), extended
and re-architected several times
Low-level access to Exchange Storage
Workhorse for Outlook communication with Exchange
Used by MAPI
Transport layer: ROPs (Remote Operations) within an RPC binary blob
Optimized to minimize traffic on the wire; very complex parsing
RPC can use HTTP(S) or TCP connections (HTTP(S) only in Exchange 2013)
New [MS-OXCMAPIHTTP] as alternative to use ROPs over HTTP; no RPCs
Exchange RPC/ROPs: Transport
RPC :
(EcDoRpcExt2)
Header
RopSize
ROP1
RopID
ROP Data
Note: No ROP Data size or end marker.
Every ROP Data in the blob must be parsed.
Every RopID has different ROP Data structure.
Number of documented RopIDs: 130
Binary Blob
ROP2
RopID
…
HSOT Table
ROP Data
RPC/ROPS protocols - continued
RPC/ROPs protocols define both Exchange (server) and Outlook
(client) behaviors
Client is handling most of low-level processing and logic behind
complex items – messages, folders, calendar items, contacts, tasks,
etc.
Naming: [MS-OXO*] and [MS-OXC*] (few exceptions)
40+ Protocols, ~3000 pages
Exchange Web Services (EWS)
Alternative to RPC protocols
Higher level of abstraction compared with RPC protocols
In Exchange RPC world, it is the responsibility of the client to implement tasks,
contacts, calendars, etc. EWS (and EAS) implement them on server side in a
way that is interoperable with Outlook.
First implemented in Exchange Server 2007
Outlook uses subset of EWS protocols
Unified Messaging, MailTips, Availability, OOF, Office Apps, Room List,
Archive, Mailbox Policies, Calendar Sharing, Site Mailboxes, etc.
New Exchange features tend to be implemented in EWS
Exchange Web Services (EWS) - continued
Lync/Skype and SharePoint use several EWS protocols to
communicate with Exchange Server
Outlook for Mac is built on EWS
Mac OSX Snow Leopard has EWS support via Apple’s Mail application
Exchange LOB applications should use EWS
Transport:
SOAP
HTTP/HTTPS
Naming: [MS-OXW*]
43 Protocols, ~2000 pages
Exchange ActiveSync (EAS)
High level of abstraction, similar to EWS in complexity, limited set of
objects and features
Designed to be used by smartphones and handhelds
Industry standard, several non-Exchange Server implementations
Wide range of clients – Windows 8, iOS, Android, … even Outlook to
Hotmail
Transport:
WBXML
HTTP/HTTPS
Naming: [MS-AS*]
15 Protocols, ~900 pages
Other Exchange protocols
NSPI (Address Book)
Directory/Profile Services (Autodiscover)
Content Conversion, how Internet (RFC-based) content gets
converted to Exchange objects and back
Standards-based protocols – Extensions and Compliance
[MS-OXPROTO] is a good reference
Exchange WebDAV protocols – deprecated
Exchange test tools update
New parsers for Message Analyzer
Protocol families: EAS, EWS, RPC, and MAPIHTTP
Retirement of Exchange RPC Extractor (RPX)
New test suites for EAS, EWS, RPC, and MAPIHTTP
Summary
Many options are available when developing with Exchange
protocols; choose the protocol family carefully.
There are a lot of resources to assist with your development (most
are free) that you can take advantage of.
Many interoperability tools (test suites, parsers, etc.) are already
available.
Exchange protocols resources
All Exchange protocol documents
https://msdn.microsoft.com/en-us/library/cc425499(v=exchg.80).aspx
Microsoft Message Analyzer
http://www.microsoft.com/en-us/download/details.aspx?id=44226
Protocol Test Suites
https://connect.microsoft.com/site216/Downloads
Help with Open Specifications:
mailto:[email protected]
Office Interoperability blog:
http://blogs.msdn.com/b/officeinteroperability/
Mail, Calendar, and Contacts REST APIs
Andrew Davidoff
Senior Software Engineer
Microsoft Corporation
Why use REST APIs?
Hundreds of millions of Users
Office 365, Outlook.com; hybrid and on-premises on the roadmap
Powerful, easy, and intuitive way to access and manipulate
Office 365 data
Granular, tightly scoped permissions to access user data
Based on open standards – OAuth 2.0, JSON, ODATA v4.0
Web-friendly APIs to enable web and mobile applications developers
What do the REST APIs in Office 365 offer?
Common Consent Framework
Single Authentication flow for O365
Azure AD Graph, Exchange, SharePoint
Device apps and web apps
Admin and end-user consent
Secure protocol
OAuth 2.0 authorization
No capturing of user credentials
Fine-grained access scopes
Supports multi-factor authentication (MFA) and
federated user sign-in
Long-term access through refresh tokens
Discovering endpoints and APIs
Office 365 discovery services
Rich service metadata
• Lists all entities, collections, actions, complex types, enumerations and their properties
• For example: https://outlook.office365.com/api/v1.0/$metadata
Rich tooling
.NET SDK to build many types of apps using Visual Studio
.NET Windows Store Apps
Windows Forms Applications
WPF Applications
ASP.NET MVC Web Applications
ASP.NET Web Forms Applications
Xamarin Android and iOS Applications
Multi-device Hybrid Apps (Cordova)
Android and iOS SDKs
You’ve got mail!
Permissions
Read, Read+Write, Send
Entities, Collections, Actions
Entity
Collection
Actions
Folder
Folders
CRUD, Copy, Move
Message
Messages
CRUD, Copy, Move, Reply, ReplyAll,
Forward, Send, CreateReply,
CreateReplyAll, CreateForward
Attachment
Attachments
CRUD
Samples
https://outlook.office365.com/api/v1.0/Me/Folders/Inbox
https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages?$top=1
https://outlook.office365.com/api/v1.0/Me/SendMail/
Calendar – Coffee @ 4?
Permissions
•
Read, Read+Write
Entities, Collections, Actions
Entity
Collection
Actions
CalendarGroup
CalendarGroups
CRUD
Calendar
Calendars
CRUD
Event
Events
CRUD, Accept, Decline, TentativelyAccept
CalendarView
N/A
Read
Attachment
Attachments
CRUD
Samples
https://outlook.office365.com/api/v1.0/Me/Calendar
https://outlook.office365.com/api/v1.0/Me/Calendar/Events?$top=1
https://outlook.office365.com/api/v1.0/Me/CalendarView?startDateTime=2015-05-01 & endDateTime=2015-05-31
Contacts – Your number again?
Permissions
• Read, Read+Write
Entities, Collections, Actions
Entity
Collection
Actions
ContactFolder
ContactFolders
CRUD
Contact
Contacts
CRUD
Samples
https://outlook.office365.com/api/v1.0/Me/ContactFolders/
https://outlook.office365.com/api/v1.0/Me/Contacts/
Use Azure Active Directory API to find users in an O365 organization (tenant)
Demo
Sample REST API Requests
Rich query syntax using OData
Scenario
URL
Get 5 messages from Inbox
https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages?$top=5
Get the next 10 messages
https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages?$top=10&$skip=5
Get top 10 messages sorted by
DateTimeReceived
https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages?$top=10&$orderby=DateTimeReceived
Get selective properties on messages
https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages?$top=5&$select=From,DateTimeCreated
,Subject
Get events starting after a particular
DateTime
https://outlook.office365.com/api/v1.0/Me/Events?$top=5&$select=Subject,Start,End&$filter=Start ge 201510-19T20:00:00Z
Get calendar view for a week with
selected properties, latest events first
https://outlook.office365.com/api/v1.0/me/calendarview?startDateTime=2015-0326T00:00:00Z&endDateTime=2015-10-19T00:00:00Z&$select=Subject,Start,End&$orderby=Start
Get # of messages with attachment(s)
https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages/$count?$filter=HasAttachments eq true
Get count and selected props on
messages with attachment(s)
https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages?$format=application/json;odata.metada
ta=none&$select=Subject&$filter=HasAttachments%20eq%20true&$count=true
Get contact with a given name
https://outlook.office365.com/api/v1.0/Me/Contacts/?$filter=Givenname eq 'John'
Roadmap
Enable end-to-end scenarios – with focus on web and mobile applications
Notifications
Custom/Extended properties
Sync
Free/Busy
Mail tips, OOF settings
Delegate scenarios
On-premises Exchange Server 2016 support for REST APIs is coming
Support for Exchange Server 2013 is on the roadmap as well
Outlook.com accounts can be accessed by REST APIs
Different endpoint, same principles
New Unified (Graph) APIs coming very soon
The same REST APIs to access Exchange, SharePoint, Active Directory, and One Drive
for Business data
Perfect for complex workflow-based solutions
Code samples on GitHub
Plenty of sample code on GitHub
MailSim tool now supports REST APIs
https://github.com/OfficeDev/Interop-MailSim
Two implementations: using SDK or direct HTTPS
Includes code that does Authentication (OAuth2) in both implementations
More Open Source Applications are in the works
REST API Resources
http://dev.office.com
Sign up
http://dev.office.com/getting-started
Explore
http://apisandbox.msdn.microsoft.com
Training
http://dev.office.com/training
API endpoints for China
https://msdn.microsoft.com/office/office365/APi/o365-china-endpoints
Questions?