使用 Exchange 中的 EWS 获取有关邮箱事件的通知Pull notifications about mailbox events by using EWS in Exchange

了解如何使用 EWS 托管 API 或 EWS 订阅拉取通知和获取事件。Find out how to use the EWS Managed API or EWS to subscribe to pull notifications and get events.

Exchange 中的 EWS 使用拉取通知,使客户端能够请求(或拉取)对邮箱的更改通知到客户端。EWS in Exchange uses pull notifications to enable clients to request (or pull) notifications about changes to the mailbox from the server to the client.

如果你正在订阅使用 EWS 托管 API 请求获取通知,请使用SubscribeToPullNotifications方法订阅并获取拉取通知If you're subscribing to pull notifications by using the EWS Managed API, you subscribe to and get pull notifications by using the SubscribeToPullNotifications method. 然后,通过使用GetEvents方法从服务器获取事件。You then get events from the server by using the GetEvents method.

若要使用 EWS 订阅拉取通知,请使用订阅操作创建订阅,分析响应,然后使用GetEvents 操作获取通知To subscribe to pull notifications by using EWS, you create a subscription by using the Subscribe operation, parse the response, and then get the notifications by using the GetEvents operation.

在客户端收到在服务器上发生更改或创建的项目的通知后,它便可以同步更改After the client receives notifications of items that are changed or created on the server, it can then synchronize the changes.

使用 EWS 托管 API 订阅和获取拉取通知Subscribe to and get pull notifications by using the EWS Managed API

下面的代码示例演示如何使用SubscribeToPullNotifications方法为 "收件箱" 文件夹中的所有事件订阅 pull 通知。The following code example shows how to use the SubscribeToPullNotifications method to subscribe to pull notifications for all events in the Inbox folder. 然后,该示例使用GetEvents方法从服务器检索事件。The example then uses the GetEvents method to retrieve events from the server. 在此示例中,我们假定服务是有效的ExchangeService绑定。In this example, we assume that service is a valid ExchangeService binding.

// Subscribe to pull notifications in the Inbox.
PullSubscription subscription = service.SubscribeToPullNotifications( 
    new FolderId[] { WellKnownFolderName.Inbox }, 30, null, 
    EventType.NewMail, EventType.Created, EventType.Deleted,
    EventType.Modified, EventType.Moved, EventType.Copied, EventType.FreeBusyChanged); 
 
// Call GetEvents to retrieve events from the server. 
GetEventsResults events = subscription.GetEvents(); 

从服务器接收到事件后,可以将这些更改与服务器同步After you receive an event from the server, you can synchronize those changes with the server. 使用在 "如何取消订阅通知? " 中指定的取消订阅方法之一,以便在不再需要订阅时结束与服务器的订阅。Use one of the unsubscribe methods specified in How do I unsubscribe to notifications? to end the subscription with the server when the subscription is no longer needed.

使用 EWS 订阅拉取通知Subscribe to pull notifications by using EWS

下面的示例演示使用订阅操作发送到服务器以订阅 "收件箱" 文件夹中所有EventTypes的 XML 请求。The following example shows the XML request to send to the server to subscribe to all EventTypes in the Inbox folder by using the Subscribe operation. 这也是在通过使用SubscribeToPullNotifications方法订阅拉取通知时,EWS 托管 API 发送的 XML 请求。This is also the XML request that the EWS Managed API sends when subscribing to pull notifications by using the SubscribeToPullNotifications method.

<?xml version="1.0" encoding="utf-8"?>
<Subscribe xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PullSubscriptionRequest xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
    <FolderIds xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
      <DistinguishedFolderId Id="inbox" />
    </FolderIds>
    <EventTypes xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
            <EventType>NewMailEvent</EventType>
            <EventType>CreatedEvent</EventType>
            <EventType>DeletedEvent</EventType>
            <EventType>ModifiedEvent</EventType>
            <EventType>MovedEvent</EventType>
            <EventType>CopiedEvent</EventType>
            <EventType>FreeBusyChangedEvent</EventType>
    </EventTypes>
    <Timeout xmlns="https://schemas.microsoft.com/exchange/services/2006/types">30</Timeout>
  </PullSubscriptionRequest>
</Subscribe>

下面的 XML 示例显示从服务器发送到客户端以响应订阅操作请求的SubscribeResponse消息。The following XML example shows the SubscribeResponse message that is sent from the server to the client in response to the Subscribe operation request. ResponseCode元素的 NoError 值的包含意味着已成功创建订阅。The inclusion of the NoError value for the ResponseCode element means that the subscription was created successfully. SubscriptionId元素唯一标识服务器上的拉取通知订阅。The SubscriptionId element uniquely identifies the pull notification subscription on the server. 水印元素表示邮箱事件队列中的书签。The Watermark element represents a bookmark in the mailbox event queue.

<?xml version="1.0" encoding="utf-8"?>
<SubscribeResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <ResponseMessages xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
    <SubscribeResponseMessage ResponseClass="Success">
      <ResponseCode>NoError</ResponseCode>
      <SubscriptionId>d581ab79-a2ec-4653-9c8e-564d7cfc1d8c</SubscriptionId>
      <Watermark>AAAAAGUhAAAAAAAAAQ==</Watermark>
    </SubscribeResponseMessage>
  </ResponseMessages>
</SubscribeResponse>

创建订阅后,您现在可以使用SubscribeResponse邮件中返回的SubscriptionId获取事件。After creating the subscription, you can now get events by using the SubscriptionId that is returned in the SubscribeResponse message.

使用 EWS 获取拉取通知Get pull notifications by using EWS

下面的 XML 示例显示从客户端发送到服务器的GetEvents 操作请求消息,以获取SubscribeResponse邮件中返回的SubscriptionId的通知。The following XML example shows the GetEvents operation request message that is sent from the client to the server to get notifications for the SubscriptionId that is returned in the SubscribeResponse message. 对于第一个GetEvents请求,使用订阅响应中返回的水印For the first GetEvents request, use the Watermark returned in the Subscribe response. 对于后续的GetEvents请求,请使用上一GetEvents请求中返回的最后一个水印For subsequent GetEvents requests, use the last Watermark that was returned in the previous GetEvents request.

<?xml version="1.0" encoding="utf-8"?>
<GetEvents xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SubscriptionId xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">d581ab79-a2ec-4653-9c8e-564d7cfc1d8c</SubscriptionId>
  <Watermark xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">AAAAAGUhAAAAAAAAAQ==</Watermark>
</GetEvents>

下面的 XML 示例展示了从服务器发送到客户端的GetEvents响应消息。The following XML example shows the GetEvents response message that is sent from the server to the client. 每个GetEvents响应都包含有关一个或多个事件的信息。Each GetEvents response includes information about one or more events. 为每个事件返回一个水印A Watermark is returned for each event. 必须保存最后一个水印并将其用于下一个GetEvents请求。The last Watermark must be saved and used in the next GetEvents request. 如果自上次GetEvents请求以来未发生任何存储事件,则返回一个 status 事件。If no store events have occurred since the last GetEvents request, a status event is returned.

<?xml version="1.0" encoding="utf-8"?>
<GetEventsResponseType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                       xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <ResponseMessages xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
    <GetEventsResponseMessage ResponseClass="Success">
      <ResponseCode>NoError</ResponseCode>
      <Notification>
        <SubscriptionId xmlns="https://schemas.microsoft.com/exchange/services/2006/types">d581ab79-a2ec-4653-9c8e-564d7cfc1d8c</SubscriptionId>
        <PreviousWatermark xmlns="https://schemas.microsoft.com/exchange/services/2006/types">AAAAAGUhAAAAAAAAAQ==</PreviousWatermark>
        <MoreEvents xmlns="https://schemas.microsoft.com/exchange/services/2006/types">false</MoreEvents>
        <NewMailEvent xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
          <Watermark>AAAAAHMhAAAAAAAAAQ==</Watermark>
          <TimeStamp>2013-09-15T21:37:01Z</TimeStamp>
          <ItemId Id="AAAtA=" ChangeKey="CQAAAA==" />
          <ParentFolderId Id="AQAtAEFkbWA==" ChangeKey="AQAAAA==" />
        </NewMailEvent>
      </Notification>
    </GetEventsResponseMessage>
  </ResponseMessages>
</GetEventsResponse>

从服务器接收到事件后,将更改同步到客户端当不再需要订阅时,使用取消订阅操作可在服务器上结束订阅。Use the Unsubscribe operation to end the subscription with the server when the subscription is no longer needed.

后续步骤Next steps

收到通知后,可以同步文件夹层次结构同步已更改的文件夹的内容After you're received notifications, you can sync the folder hierarchy or sync the contents of the folder that changed.

另请参阅See also