Web Services
Topic Last Modified: 2009-07-15
The Web services that are included in Microsoft Exchange Server 2007 provide an XML messaging interface for managing Exchange store items and accessing functionality on a computer that is running Exchange 2007 from client applications. The SOAP protocol provides the messaging framework for messages that are sent between the client application and the Exchange server. The SOAP messages are sent by HTTP.
Exchange 2007 includes the following Web services:
- Exchange Web Services
- Autodiscover Service
- Unified Messaging Web Service
Exchange Web Services
Exchange Web Services provides the functionality to enable client applications to communicate with the Exchange server. Exchange Web Services provides access to much of the same data that is made available through Microsoft Office Outlook. Exchange Web Services clients can integrate Outlook data into line-of-business (LOB) applications.
Exchange Web Services is described by three files:
- Services.wsdl Describes the contract between client and server.
- Messages.xsd Defines the request and response SOAP messages.
- Types.xsd Defines the elements that are used in the SOAP messages.
These schema files are located in the EWS virtual directory of the computer that is running Exchange 2007 that has the Client Access server role installed.
Exchange Web Services provides the following types of operations:
- Availability
- Delegate Management (starting with Exchange 2007 Service Pack 1)
- Folder
- Item
- Messaging Records Management
- Notification
- Synchronization
- Utility
Availability Operations
The Availability operations improve information workers' calendar and free/busy sharing experience by providing secure, up-to-date, and rich free/busy information. This information enables developers to create sophisticated collaboration and scheduling applications.
The Availability Web service provides tools to create enhanced Exchange 2007 client applications by doing the following:
- Retrieving live free/busy information for Exchange 2007 mailboxes.
- Retrieving live free/busy information from other Exchange 2007 forests.
- Retrieving published free/busy information from public folders.
- Retrieving suggested meeting times.
- Supplying up-to-date free/busy data so that users and resources can be scheduled with more confidence.
- Supplying more specific data that describes the status of users and resources, such as the start times and the end times of individual appointments, subjects, locations, work hours, and so on.
- Securing the distribution of free/busy data by specifying the level of detail to share with specified users.
In addition, the Availability operations enable users to share their calendar information in more granular ways. For each target person/group, the user can select one of four levels of sharing:
- Share nothing
- Share their free/busy information
- Share more detail including subject, location, and timing
- Share full calendar details
Delegate Management Operations
Starting with Exchange 2007 SP1, delegate management is available through Exchange Web Services. Four Exchange Web Services operations provide delegate management functionality. These operations enable you to do the following:
- Add new delegates.
- Retrieve and update existing delegate permissions.
- Remove existing delegates.
Delegate access supports the following types of scenarios:
- Delegates can open the folders of a principal and manipulate items based on folder-level permissions.
- Delegates can create and send meeting messages on behalf of the principal.
- Delegates can receive meeting messages that are forwarded by the principal and respond to them for the principal.
- Users who have owner rights on a shared mailbox can open the mailbox and act as the owner.
- Delegates can create notification subscriptions on folders in the mailbox of the principal.
Folder Operations
The Folder operations provide access to folders in the Exchange data store. A client application can create, update, delete, copy, find, get, and move folders that are associated with a mailbox user. Folders are used to gain access to items in the store, and provide a reference container for items in the store.
The folder operations enable client applications to do the following:
- Get the identity of a single folder.
- Identify which folder properties are returned by a request.
- Enumerate the items or folders that are descendants of a single folder.
- Access data fields in an item or folder.
- Search a folder hierarchy.
- Use search restrictions to narrow the response set.
- Create search folders.
- Provide support for delegate and administrative access to items and folders in the store.
Item Operations
The Item operations provide access to items in the Exchange data store. By using these operations, a client application can create, update, delete, copy, get, move, and send items. The Item operations work on the following item types:
- Message Items Message items are XML representations of the Internet Message Format defined in [RFC2822] that are defined in e-mail messages.
- Contact Items Contact items are a set of properties that represent contacts that are located either in the Active Directory directory service or in private contact stores. It is important to note that, while these two types of contacts are similar in data content, they differ in the types of operations that you can perform on them.
- Task Items Task items are the Outlook Personal Information Manager (PIM) objects that can be accessed by the Task pane. Tasks can be single items or recurring activities.
- Calendar Items Calendar items identify the location, resources, recurrence, and attendees involved at a discrete time. Calendar items are represented by Meetings, Appointments, Meeting Invitations, and Invitation-handling objects. Meeting organizers can create, update, and delete both individual and recurring meetings. Organizers can also send out meeting invitations. Meeting attendees can accept, decline, and acknowledge the receipt of invitations and counter-propose a time or recurring schedule for a meeting.
Messaging Records Management Operations
The Messaging Records Management operation enables the assignment of managed custom folders to mailbox users. Client applications that consume this Web service give users the ability to add managed custom folders to their mailbox instead of having an administrator perform the task. Administrators in large organizations do not have the resources to set up user subscriptions to policy folders. Frequently, administrators do not know which policy folders an individual user should use. Users can subscribe to individual policy folders. This works in addition to policy folders assigned to groups of users by the administrators.
Notification Operations
The Notification operations notify client systems of events and changes in mailboxes on computers that are running Exchange 2007. Clients subscribe for notifications to the Event Notifications subsystem, and specify the types of events to monitor on the specified mailboxes. The Notification operations provide push and pull subscriptions from the Exchange 2007 computer that is running the Client Access server role. The following are the events that are monitored by the Event Notification subsystem:
- Mail arrival
- Item creation
- Item deletion
- Item modification
- Item movement
- Item copied
- Mail submission
Synchronization Operations
The Synchronization operations provide a one-way, synchronized cached copy of a user's folders and items. This Web service provides two forms of synchronization:
- Folder Hierarchy A client synchronizes the folder hierarchy of a whole mailbox or any subfolder hierarchy within the mailbox.
- Folder Items A client synchronizes all items in a folder.
Clients can also explicitly ignore items so that they are not synchronized, and specify how many items should be synchronized between server and client.
Utility Operations
The Utility operations enable client applications to resolve ambiguous names and return the membership of a distribution list.
Versioning
Starting with Exchange 2007 SP1, the schema includes a SOAP header element that is used to version SOAP requests. The SOAP header is required to identify the schema against which client requests are validated and upon which the server's response is based.
Public Folder Access
Starting with Exchange 2007 SP1, you can use Exchange Web Services operations to access public folders. This includes the following functionality:
- Access to the public folder hierarchy
- Access to detailed information about public folders
- Access to detailed information about public folder items
- The ability to post items
- The ability to synchronize public folder items
- Subscription notifications for public folders
Folder-Level Permissions
Starting with Exchange 2007 SP1, Exchange Web Services provides folder-level permissions. You can access and set these permissions by using the CreateFolder, GetFolder, UpdateFolder, and SyncFolderHierarchy operations. This includes the following functionality:
- Clients can query and configure the sharing of permissions on the folder.
- Clients can retrieve the effective rights to get the effective permission for the logon user.
- Free/busy calendar folder permissions are exposed.
Identifier Translation
Starting with Exchange 2007 SP1, you can use the ConvertId operation to convert different item identifiers. The ConvertId operation supports public folders, mailbox folders, and item identifiers. The following are the supported identifier formats:
- The initial release of Exchange 2007 Exchange Web Services identifiers. These are the identifiers that Exchange Web Services creates and consumes for folders and items in Exchange 2007.
- Exchange Web Services SP1 or Exchange Web Services SP2 identifiers. These are the identifiers that Exchange Web Services creates and consumes for folders and items in Exchange 2007 SP1 and Exchange 2007 SP2.
- EntryID identifiers. These are provided by MAPI components.
- Outlook Web Access identifiers. These are the identifiers that are created by Outlook Web Access and offered to consumers in the query string of the Outlook Web Access URL.
- Availability Calendar ID identifiers. These identifiers are hexadecimal-encoded entry IDs that are used by the Availability feature to represent calendar items in a GetUserAvailability response.
Identifier Format
Starting with Exchange 2007 SP1, the format of Exchange Web Services identifiers for folders and items differs from the format of identifiers in the initial release version of Exchange 2007. In Exchange 2007, the primary SMTP address is embedded in the identifier format. Because primary SMTP addresses can change, identifiers that are cached on a client will not match identifiers of items on the server if the primary SMTP address is updated, and attempts to reference the item will fail. In Exchange 2007 SP1 and Exchange 2007 SP2, the identifiers encode a mailbox identifier instead of the primary SMTP address to uniquely identify the item or folder.
If an Exchange 2007 client sends requests against a computer that is running Exchange 2007 SP1 or Exchange 2007 SP2, the identifier will work unless the SMTP address has changed. If the SMTP address has changed, the Exchange 2007 client must resynchronize.
Autodiscover Service
The Autodiscover service provides a mechanism to automatically configure Exchange 2007 client applications to access the Client Access server. Autodiscover provides a powerful tool for configuring client application profiles used to discover Exchange Web Services and associated mailbox information. Autodiscover provides configuration information inside or outside of firewalls. In addition, Autodiscover will work in resource forest and multiple forest scenarios.
Unified Messaging Web Service
The Unified Messaging Web Service provides an extensibility point for clients to read and change information about Unified Messaging properties.